1/*
2 This file is part of the KDE libraries
3 Copyright
4 (C) 2000 Reginald Stadlbauer (reggie@kde.org)
5 (C) 1997 Stephan Kulow (coolo@kde.org)
6 (C) 1997-2000 Sven Radej (radej@kde.org)
7 (C) 1997-2000 Matthias Ettrich (ettrich@kde.org)
8 (C) 1999 Chris Schlaeger (cs@kde.org)
9 (C) 2002 Joseph Wenninger (jowenn@kde.org)
10 (C) 2005-2006 Hamish Rodda (rodda@kde.org)
11
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Library General Public
14 License version 2 as published by the Free Software Foundation.
15
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Library General Public License for more details.
20
21 You should have received a copy of the GNU Library General Public License
22 along with this library; see the file COPYING.LIB. If not, write to
23 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 Boston, MA 02110-1301, USA.
25
26
27*/
28
29#ifndef KXMLGUIWINDOW_H
30#define KXMLGUIWINDOW_H
31
32#include "kxmlguiclient.h"
33#include "kxmlguibuilder.h"
34#include <kmainwindow.h>
35#include <QtCore/QMetaClassInfo>
36
37class KMenu;
38class KXMLGUIFactory;
39class KConfig;
40class KConfigGroup;
41class KToolBar;
42class KXmlGuiWindowPrivate;
43
44#define KDE_DEFAULT_WINDOWFLAGS 0
45
46/**
47 * @short %KDE top level main window with predefined action layout
48 *
49 * Instead of creating a KMainWindow manually and assigning menus, menu entries,
50 * toolbar buttons and actions to it by hand, this class can be used to load an
51 * rc file to manage the main window's actions.
52 *
53 * See http://techbase.kde.org/Development/Tutorials/Using_KActions#XMLGUI
54 * for essential information on the XML file format and usage of this class.
55 *
56 * @see KMainWindow
57 * @author Reginald Stadlbauer (reggie@kde.org) Stephan Kulow (coolo@kde.org), Matthias Ettrich (ettrich@kde.org), Chris Schlaeger (cs@kde.org), Sven Radej (radej@kde.org). Maintained by Sven Radej (radej@kde.org)
58
59 */
60
61class KDEUI_EXPORT KXmlGuiWindow : public KMainWindow, public KXMLGUIBuilder, virtual public KXMLGUIClient
62{
63 KDEUI_DECLARE_PRIVATE(KXmlGuiWindow)
64 Q_OBJECT
65 Q_PROPERTY( bool hasMenuBar READ hasMenuBar )
66 Q_PROPERTY( bool autoSaveSettings READ autoSaveSettings )
67 Q_PROPERTY( QString autoSaveGroup READ autoSaveGroup )
68 Q_PROPERTY( bool standardToolBarMenuEnabled READ isStandardToolBarMenuEnabled WRITE setStandardToolBarMenuEnabled )
69 Q_FLAGS( StandardWindowOption )
70 Q_PROPERTY( bool initialGeometrySet READ initialGeometrySet )
71
72public:
73 /**
74 * Construct a main window.
75 *
76 * @param parent The widget parent. This is usually 0 but it may also be the window
77 * group leader. In that case, the KMainWindow becomes sort of a
78 * secondary window.
79 *
80 * @param f Specify the widget flags. The default is
81 * Qt::Window and Qt::WA_DeleteOnClose. Qt::Window indicates that a
82 * main window is a toplevel window, regardless of whether it has a
83 * parent or not. Qt::WA_DeleteOnClose indicates that a main window is
84 * automatically destroyed when its window is closed. Pass 0 if
85 * you do not want this behavior.
86 *
87 * @see http://doc.trolltech.com/qt.html#WindowType-enum
88 *
89 * KMainWindows must be created on the heap with 'new', like:
90 * \code
91 * KMainWindow *kmw = new KMainWindow(...);
92 * kmw->setObjectName(...);
93 * \endcode
94 *
95 * IMPORTANT: For session management and window management to work
96 * properly, all main windows in the application should have a
97 * different name. If you don't do it, KMainWindow will create
98 * a unique name, but it's recommended to explicitly pass a window name that will
99 * also describe the type of the window. If there can be several windows of the same
100 * type, append '#' (hash) to the name, and KMainWindow will replace it with numbers to make
101 * the names unique. For example, for a mail client which has one main window showing
102 * the mails and folders, and which can also have one or more windows for composing
103 * mails, the name for the folders window should be e.g. "mainwindow" and
104 * for the composer windows "composer#".
105 *
106 */
107 explicit KXmlGuiWindow( QWidget* parent = 0, Qt::WindowFlags f = KDE_DEFAULT_WINDOWFLAGS );
108
109 /**
110 * \brief Destructor.
111 *
112 * Will also destroy the toolbars, and menubar if
113 * needed.
114 */
115 virtual ~KXmlGuiWindow();
116
117 /**
118 * Enables the build of a standard help menu when calling createGUI/setupGUI().
119 *
120 * The default behavior is to build one, you must call this function
121 * to disable it
122 */
123 void setHelpMenuEnabled(bool showHelpMenu = true);
124
125 /**
126 * Return @p true when the help menu is enabled
127 */
128 bool isHelpMenuEnabled() const;
129
130 virtual KXMLGUIFactory *guiFactory();
131
132 /**
133 * Create a GUI given a local XML file. In a regular app you usually want to use
134 * setupGUI() instead of this one since it does more things for free
135 * like setting up the toolbar/shortcut edit actions, etc.
136 *
137 * If @p xmlfile is NULL,
138 * then it will try to construct a local XML filename like
139 * appnameui.rc where 'appname' is your app's name. If that file
140 * does not exist, then the XML UI code will only use the global
141 * (standard) XML file for the layout purposes.
142 *
143 * @param xmlfile The local xmlfile (relative or absolute)
144 */
145 void createGUI( const QString &xmlfile = QString() );
146
147
148 /**
149 * Sets whether KMainWindow should provide a menu that allows showing/hiding
150 * the available toolbars ( using KToggleToolBarAction ) . In case there
151 * is only one toolbar configured a simple 'Show \<toolbar name here\>' menu item
152 * is shown.
153 *
154 * The menu / menu item is implemented using xmlgui. It will be inserted in your
155 * menu structure in the 'Settings' menu.
156 *
157 * If your application uses a non-standard xmlgui resource file then you can
158 * specify the exact position of the menu / menu item by adding a
159 * &lt;Merge name="StandardToolBarMenuHandler" /&gt;
160 * line to the settings menu section of your resource file ( usually appname.rc ).
161 *
162 * Note that you should enable this feature before calling createGUI() ( or similar ) .
163 */
164 void setStandardToolBarMenuEnabled( bool enable );
165 bool isStandardToolBarMenuEnabled() const;
166
167
168 /**
169 * Sets whether KMainWindow should provide a menu that allows showing/hiding
170 * of the statusbar ( using KToggleStatusBarAction ).
171 *
172 * The menu / menu item is implemented using xmlgui. It will be inserted
173 * in your menu structure in the 'Settings' menu.
174 *
175 * Note that you should enable this feature before calling createGUI()
176 * ( or similar ).
177 *
178 * If an application maintains the action on its own (i.e. never calls
179 * this function) a connection needs to be made to let KMainWindow
180 * know when that status (hidden/shown) of the statusbar has changed.
181 * For example:
182 * connect(action, SIGNAL(activated()),
183 * kmainwindow, SLOT(setSettingsDirty()));
184 * Otherwise the status (hidden/show) of the statusbar might not be saved
185 * by KMainWindow.
186 */
187 void createStandardStatusBarAction();
188
189 /**
190 * @see setupGUI()
191 */
192 enum StandardWindowOption
193 {
194 /**
195 * adds action to show/hide the toolbar(s) and adds
196 * action to configure the toolbar(s).
197 * @see setStandardToolBarMenuEnabled
198 */
199 ToolBar = 1,
200
201 /**
202 * adds action to show the key configure action.
203 */
204 Keys = 2,
205
206 /**
207 * adds action to show/hide the statusbar if the
208 * statusbar exists. @see createStandardStatusBarAction
209 */
210 StatusBar = 4,
211
212 /**
213 * auto-saves (and loads) the toolbar/menubar/statusbar settings and
214 * window size using the default name. @see setAutoSaveSettings
215 *
216 * Typically you want to let the default window size be determined by
217 * the widgets size hints. Make sure that setupGUI() is called after
218 * all the widgets are created ( including setCentralWidget ) so the
219 * default size's will be correct. @see setAutoSaveSettings for
220 * more information on this topic.
221 */
222 Save = 8,
223
224 /**
225 * calls createGUI() once ToolBar, Keys and Statusbar have been
226 * taken care of. @see createGUI
227 *
228 * NOTE: when using KParts::MainWindow, remove this flag from the
229 * setupGUI call, since you'll be using createGUI(part) instead.
230 * @code
231 * setupGUI(ToolBar | Keys | StatusBar | Save);
232 * @endcode
233 */
234 Create = 16,
235
236 /**
237 * All the above option
238 * (this is the default)
239 */
240 Default = ToolBar | Keys | StatusBar | Save | Create
241 };
242 Q_DECLARE_FLAGS(StandardWindowOptions, StandardWindowOption)
243
244 /**
245 * Configures the current windows and its actions in the typical KDE
246 * fashion. The options are all enabled by default but can be turned
247 * off if desired through the params or if the prereqs don't exists.
248 *
249 * Typically this function replaces createGUI().
250 *
251 * @see StandardWindowOptions
252 * @note Since this method will restore the state of the application (toolbar, dockwindows
253 * positions...), you need to have added all your actions to your toolbars etc before
254 * calling to this method. (This note is only applicable if you are using the Default or
255 * Save flag).
256 * @warning If you are calling createGUI yourself, remember to remove the Create flag from
257 * the @p options parameter.
258 *
259 */
260 void setupGUI( StandardWindowOptions options = Default, const QString& xmlfile = QString() );
261
262 /**
263 * Configures the current windows and its actions in the typical KDE
264 * fashion. The options are all enabled by default but can be turned
265 * off if desired through the params or if the prereqs don't exists.
266 *
267 * @p defaultSize The default size of the window
268 *
269 * Typically this function replaces createGUI().
270 *
271 * @see StandardWindowOptions
272 * @note Since this method will restore the state of the application (toolbar, dockwindows
273 * positions...), you need to have added all your actions to your toolbars etc before
274 * calling to this method. (This note is only applicable if you are using the Default or
275 * Save flag).
276 * @warning If you are calling createGUI yourself, remember to remove the Create flag from
277 * the @p options parameter. Also, call setupGUI always after you call createGUI.
278 */
279 void setupGUI( const QSize& defaultSize, StandardWindowOptions options = Default, const QString& xmlfile = QString() );
280
281 /**
282 * Returns a pointer to the mainwindows action responsible for the toolbars menu
283 */
284 QAction *toolBarMenuAction();
285
286 /**
287 * @internal for KToolBar
288 */
289 void setupToolbarMenuActions();
290
291 // KDE5 TODO: change it to "using KXMLGUIBuilder::finalizeGUI;"
292 virtual void finalizeGUI( KXMLGUIClient *client );
293
294 /**
295 * @internal
296 */
297 void finalizeGUI( bool force );
298
299 // reimplemented for internal reasons
300 virtual void applyMainWindowSettings(const KConfigGroup &config, bool force = false);
301
302public Q_SLOTS:
303 /**
304 * Show a standard configure toolbar dialog.
305 *
306 * This slot can be connected directly to the action to configure toolbar.
307 * This is very simple to do that by adding a single line
308 * \code
309 * KStandardAction::configureToolbars( this, SLOT( configureToolbars() ),
310 * actionCollection() );
311 * \endcode
312 */
313 virtual void configureToolbars();
314
315 /**
316 * Apply a state change
317 *
318 * Enable and disable actions as defined in the XML rc file
319 */
320 virtual void slotStateChanged(const QString &newstate);
321
322 /**
323 * Apply a state change
324 *
325 * Enable and disable actions as defined in the XML rc file,
326 * can "reverse" the state (disable the actions which should be
327 * enabled, and vice-versa) if specified.
328 */
329 void slotStateChanged(const QString &newstate,
330 bool reverse);
331
332protected:
333 /**
334 * Reimplemented to catch QEvent::Polish in order to adjust the object name
335 * if needed, once all constructor code for the main window has run.
336 * Also reimplemented to catch when a QDockWidget is added or removed.
337 */
338 virtual bool event( QEvent * event );
339
340protected Q_SLOTS:
341 /**
342 * Rebuilds the GUI after KEditToolbar changed the toolbar layout.
343 * @see configureToolbars()
344 */
345 virtual void saveNewToolbarConfig();
346
347private:
348 Q_PRIVATE_SLOT(k_func(), void _k_slotFactoryMakingChanges(bool))
349};
350
351Q_DECLARE_OPERATORS_FOR_FLAGS(KXmlGuiWindow::StandardWindowOptions)
352
353#endif
354