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 | |
37 | class ; |
38 | class KXMLGUIFactory; |
39 | class KConfig; |
40 | class KConfigGroup; |
41 | class KToolBar; |
42 | class 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 | |
61 | class 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 | |
72 | public: |
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 (bool = true); |
124 | |
125 | /** |
126 | * Return @p true when the help menu is enabled |
127 | */ |
128 | bool () 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 | * <Merge name="StandardToolBarMenuHandler" /> |
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 *(); |
285 | |
286 | /** |
287 | * @internal for KToolBar |
288 | */ |
289 | void (); |
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 | |
302 | public 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 | |
332 | protected: |
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 | |
340 | protected Q_SLOTS: |
341 | /** |
342 | * Rebuilds the GUI after KEditToolbar changed the toolbar layout. |
343 | * @see configureToolbars() |
344 | */ |
345 | virtual void saveNewToolbarConfig(); |
346 | |
347 | private: |
348 | Q_PRIVATE_SLOT(k_func(), void _k_slotFactoryMakingChanges(bool)) |
349 | }; |
350 | |
351 | Q_DECLARE_OPERATORS_FOR_FLAGS(KXmlGuiWindow::StandardWindowOptions) |
352 | |
353 | #endif |
354 | |