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 | (C) 2000-2008 David Faure (faure@kde.org) |
12 | |
13 | This library is free software; you can redistribute it and/or |
14 | modify it under the terms of the GNU Library General Public |
15 | License version 2 as published by the Free Software Foundation. |
16 | |
17 | This library is distributed in the hope that it will be useful, |
18 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
19 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
20 | Library General Public License for more details. |
21 | |
22 | You should have received a copy of the GNU Library General Public License |
23 | along with this library; see the file COPYING.LIB. If not, write to |
24 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
25 | Boston, MA 02110-1301, USA. |
26 | |
27 | |
28 | */ |
29 | |
30 | #ifndef KMAINWINDOW_H |
31 | #define KMAINWINDOW_H |
32 | |
33 | #include <kdeui_export.h> |
34 | |
35 | #include <QtGui/QMainWindow> |
36 | #include <QtCore/QMetaClassInfo> |
37 | |
38 | class ; |
39 | class KConfig; |
40 | class KConfigGroup; |
41 | class KStatusBar; |
42 | class ; |
43 | class KMWSessionManager; |
44 | class KMainWindowPrivate; |
45 | class KToolBar; |
46 | |
47 | // internal, not public API, may change any time |
48 | #define KDEUI_DECLARE_PRIVATE(classname) \ |
49 | inline classname ## Private *k_func() { return reinterpret_cast<classname ## Private *>(k_ptr); } \ |
50 | inline const classname ## Private *k_func() const { return reinterpret_cast<classname ## Private *>(k_ptr); } \ |
51 | friend class classname ## Private; |
52 | |
53 | // This is mostly from KDE3. TODO KDE5: remove the constructor parameter. |
54 | #define KDE_DEFAULT_WINDOWFLAGS 0 |
55 | |
56 | /** |
57 | * @short %KDE top level main window |
58 | * |
59 | * Top level widget that provides toolbars, a status line and a frame. |
60 | * |
61 | * It should be used as a top level (parent-less) widget. |
62 | * It manages the geometry for all its children, including your |
63 | * main widget. |
64 | * |
65 | * Normally, you will inherit from KMainWindow, |
66 | * then construct (or use some existing) widget as |
67 | * your main view. You can set only one main view. |
68 | * |
69 | * You can add as many toolbars as you like. There can be only one menubar |
70 | * and only one statusbar. |
71 | * |
72 | * The toolbars, menubar, and statusbar can be created by the |
73 | * KMainWindow and - unlike the old KMainWindow - may, but do not |
74 | * have to, be deleted by you. KMainWindow will handle that internally. |
75 | * |
76 | * Height and width can be operated independently from each other. Simply |
77 | * define the minimum/maximum height/width of your main widget and |
78 | * KMainWindow will take this into account. For fixed size windows set |
79 | * your main widget to a fixed size. |
80 | * |
81 | * Fixed aspect ratios (heightForWidth()) and fixed width widgets are |
82 | * not supported. |
83 | * |
84 | * KMainWindow will set icon, mini icon and caption, which it gets |
85 | * from KApplication. It provides full session management, and |
86 | * will save its position, geometry and positions of toolbars and |
87 | * menubar on logout. If you want to save additional data, reimplement |
88 | * saveProperties() and (to read them again on next login) |
89 | * readProperties(). To save special data about your data, reimplement |
90 | * saveGlobalProperties(). To warn user that application or |
91 | * windows have unsaved data on close or logout, reimplement |
92 | * queryClose(). |
93 | * |
94 | * You have to implement session restoring also in your main() function. |
95 | * There are also kRestoreMainWindows convenience functions which |
96 | * can do this for you and restore all your windows on next login. |
97 | * |
98 | * Note that KMainWindow uses KGlobal::ref() and KGlobal::deref() so that closing |
99 | * the last mainwindow will quit the application unless there is still something |
100 | * that holds a ref in KGlobal - like a KIO job, or a systray icon. |
101 | * |
102 | * @see KApplication |
103 | * @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 David Faure (faure@kde.org) |
104 | */ |
105 | |
106 | class KDEUI_EXPORT KMainWindow : public QMainWindow |
107 | { |
108 | friend class KMWSessionManager; |
109 | friend class DockResizeListener; |
110 | KDEUI_DECLARE_PRIVATE(KMainWindow) |
111 | Q_OBJECT |
112 | Q_PROPERTY( bool hasMenuBar READ hasMenuBar ) |
113 | Q_PROPERTY( bool autoSaveSettings READ autoSaveSettings ) |
114 | Q_PROPERTY( QString autoSaveGroup READ autoSaveGroup ) |
115 | Q_PROPERTY( bool initialGeometrySet READ initialGeometrySet ) |
116 | |
117 | public: |
118 | /** |
119 | * Construct a main window. |
120 | * |
121 | * @param parent The widget parent. This is usually 0 but it may also be the window |
122 | * group leader. In that case, the KMainWindow becomes sort of a |
123 | * secondary window. |
124 | * |
125 | * @param f Specify the window flags. The default is none. |
126 | * |
127 | * Note that a KMainWindow per-default is created with the |
128 | * WA_DeleteOnClose attribute, i.e. it is automatically destroyed when the |
129 | * window is closed. If you do not want this behavior, call |
130 | * setAttribute(Qt::WA_DeleteOnClose, false); |
131 | * |
132 | * KMainWindows must be created on the heap with 'new', like: |
133 | * \code |
134 | * KMainWindow *kmw = new KMainWindow(...); |
135 | * kmw->setObjectName(...); |
136 | * \endcode |
137 | * |
138 | * IMPORTANT: For session management and window management to work |
139 | * properly, all main windows in the application should have a |
140 | * different name. If you don't do it, KMainWindow will create |
141 | * a unique name, but it's recommended to explicitly pass a window name that will |
142 | * also describe the type of the window. If there can be several windows of the same |
143 | * type, append '#' (hash) to the name, and KMainWindow will replace it with numbers to make |
144 | * the names unique. For example, for a mail client which has one main window showing |
145 | * the mails and folders, and which can also have one or more windows for composing |
146 | * mails, the name for the folders window should be e.g. "mainwindow" and |
147 | * for the composer windows "composer#". |
148 | * |
149 | */ |
150 | explicit KMainWindow( QWidget* parent = 0, Qt::WindowFlags f = KDE_DEFAULT_WINDOWFLAGS ); |
151 | |
152 | /** |
153 | * \brief Destructor. |
154 | * |
155 | * Will also destroy the toolbars, and menubar if |
156 | * needed. |
157 | */ |
158 | virtual ~KMainWindow(); |
159 | |
160 | /** |
161 | * Retrieve the standard help menu. |
162 | * |
163 | * It contains entries for the |
164 | * help system (activated by F1), an optional "What's This?" entry |
165 | * (activated by Shift F1), an application specific dialog box, |
166 | * and an "About KDE" dialog box. |
167 | * |
168 | * Example (adding a standard help menu to your application): |
169 | * \code |
170 | * KMenu *help = helpMenu( <myTextString> ); |
171 | * menuBar()->addMenu( help ); |
172 | * \endcode |
173 | * |
174 | * @param aboutAppText The string that is used in the application |
175 | * specific dialog box. If you leave this string empty the |
176 | * information in the global KAboutData of the |
177 | * application will be used to make a standard dialog box. |
178 | * |
179 | * @param showWhatsThis Set this to false if you do not want to include |
180 | * the "What's This" menu entry. |
181 | * |
182 | * @return A standard help menu. |
183 | */ |
184 | KMenu* helpMenu( const QString &aboutAppText = QString(), |
185 | bool showWhatsThis = true ); |
186 | |
187 | /** |
188 | * Returns the help menu. Creates a standard help menu if none exists yet. |
189 | * |
190 | * It contains entries for the |
191 | * help system (activated by F1), an optional "What's This?" entry |
192 | * (activated by Shift F1), an application specific dialog box, |
193 | * and an "About KDE" dialog box. You must create the application |
194 | * specific dialog box yourself. When the "About application" |
195 | * menu entry is activated, a signal will trigger the |
196 | * showAboutApplication slot. See showAboutApplication for more |
197 | * information. |
198 | * |
199 | * Example (adding a help menu to your application): |
200 | * \code |
201 | * menuBar()->addMenu( customHelpMenu() ); |
202 | * \endcode |
203 | * |
204 | * @param showWhatsThis Set this to @p false if you do not want to include |
205 | * the "What's This" menu entry. |
206 | * |
207 | * @return A standard help menu. |
208 | */ |
209 | KMenu* customHelpMenu( bool showWhatsThis = true ); |
210 | |
211 | /** |
212 | * If the session did contain so high a number, @p true is returned, |
213 | * else @p false. |
214 | * @see restore() |
215 | **/ |
216 | static bool canBeRestored( int number ); |
217 | |
218 | /** |
219 | * Returns the className() of the @p number of the toplevel window which |
220 | * should be restored. |
221 | * |
222 | * This is only useful if your application uses |
223 | * different kinds of toplevel windows. |
224 | */ |
225 | static const QString classNameOfToplevel( int number ); |
226 | |
227 | /** |
228 | * Try to restore the toplevel widget as defined by @p number (1..X). |
229 | * |
230 | * You should call canBeRestored() first. |
231 | * |
232 | * If the session did not contain so high a number, the configuration |
233 | * is not changed and @p false returned. |
234 | * |
235 | * That means clients could simply do the following: |
236 | * \code |
237 | * if (qApp->isSessionRestored()){ |
238 | * int n = 1; |
239 | * while (KMainWindow::canBeRestored(n)){ |
240 | * (new childMW)->restore(n); |
241 | * n++; |
242 | * } |
243 | * } else { |
244 | * // create default application as usual |
245 | * } |
246 | * \endcode |
247 | * Note that if @p show is true (default), QWidget::show() is called |
248 | * implicitly in restore. |
249 | * |
250 | * With this you can easily restore all toplevel windows of your |
251 | * application. |
252 | * |
253 | * If your application uses different kinds of toplevel |
254 | * windows, then you can use KMainWindow::classNameOfToplevel(n) |
255 | * to determine the exact type before calling the childMW |
256 | * constructor in the example from above. |
257 | * |
258 | * <i>Note that you don't need to deal with this function. Use the |
259 | * kRestoreMainWindows() convenience template function instead!</i> |
260 | * @see kRestoreMainWindows() |
261 | * @see #RESTORE |
262 | * @see readProperties() |
263 | * @see canBeRestored() |
264 | */ |
265 | bool restore( int number, bool show = true ); |
266 | |
267 | /** |
268 | * Returns true, if there is a menubar |
269 | */ |
270 | bool hasMenuBar(); |
271 | |
272 | /** |
273 | * Returns a pointer to the menu bar. |
274 | * |
275 | * If there is no menu bar yet one will be created. |
276 | **/ |
277 | KMenuBar *menuBar(); |
278 | |
279 | /** |
280 | * Returns a pointer to the status bar. |
281 | * |
282 | * If there is no status bar yet, one will be created. |
283 | * |
284 | * Note that tooltips for kactions in actionCollection() are not |
285 | * automatically connected to this statusBar. |
286 | * See the KActionCollection documentation for more details. |
287 | * |
288 | * @see KActionCollection |
289 | */ |
290 | KStatusBar *statusBar(); |
291 | |
292 | |
293 | /** |
294 | * List of members of KMainWindow class. |
295 | */ |
296 | static QList<KMainWindow*> memberList(); |
297 | |
298 | /** |
299 | * Returns a pointer to the toolbar with the specified name. |
300 | * This refers to toolbars created dynamically from the XML UI |
301 | * framework. If the toolbar does not exist one will be created. |
302 | * |
303 | * @param name The internal name of the toolbar. If no name is |
304 | * specified "mainToolBar" is assumed. |
305 | * |
306 | * @return A pointer to the toolbar |
307 | **/ |
308 | KToolBar *toolBar( const QString& name = QString() ); |
309 | |
310 | /** |
311 | * @return A list of all toolbars for this window |
312 | */ |
313 | QList<KToolBar*> toolBars() const; |
314 | |
315 | /** |
316 | * Call this to enable "auto-save" of toolbar/menubar/statusbar settings |
317 | * (and optionally window size). |
318 | * If the *bars were moved around/shown/hidden when the window is closed, |
319 | * saveMainWindowSettings( KConfigGroup(KGlobal::config(), groupName) ) will be called. |
320 | * |
321 | * @param groupName a name that identifies this "type of window". |
322 | * You can have several types of window in the same application. |
323 | * |
324 | * @param saveWindowSize set it to true to include the window size |
325 | * when saving. |
326 | * |
327 | * Typically, you will call setAutoSaveSettings() in your |
328 | * KMainWindow-inherited class constructor, and it will take care |
329 | * of restoring and saving automatically. Make sure you call this |
330 | * _after all_ your *bars have been created. |
331 | * |
332 | * To make sure that KMainWindow propertly obtains the default |
333 | * size of the window you should do the following: |
334 | * - Remove hard coded resize() calls in the constructor or main, they |
335 | * should be removed in favor of letting the automatic resizing |
336 | * determine the default window size. Hard coded window sizes will |
337 | * be wrong for users that have big fonts, use different styles, |
338 | * long/small translations, large toolbars, and other factors. |
339 | * - Put the setAutoSaveSettings ( or setupGUI() ) call after all widgets |
340 | * have been created and placed inside the main window (i.e. for 99% of |
341 | * apps setCentralWidget()) |
342 | * - Widgets that inherit from QWidget (like game boards) should overload |
343 | * "virtual QSize sizeHint() const;" to specify a default size rather |
344 | * than letting QWidget::adjust use the default size of 0x0. |
345 | */ |
346 | void setAutoSaveSettings( const QString & groupName = QLatin1String("MainWindow" ), |
347 | bool saveWindowSize = true ); |
348 | |
349 | /** |
350 | * Overload that lets you specify a KConfigGroup. |
351 | * This allows the settings to be saved into another file than KGlobal::config(). |
352 | * @since 4.1 |
353 | */ |
354 | void setAutoSaveSettings(const KConfigGroup & group, |
355 | bool saveWindowSize = true); |
356 | |
357 | /** |
358 | * Disable the auto-save-settings feature. |
359 | * You don't normally need to call this, ever. |
360 | */ |
361 | void resetAutoSaveSettings(); |
362 | |
363 | /** |
364 | * @return the current autosave setting, i.e. true if setAutoSaveSettings() was called, |
365 | * false by default or if resetAutoSaveSettings() was called. |
366 | */ |
367 | bool autoSaveSettings() const; |
368 | |
369 | /** |
370 | * @return the group used for setting-autosaving. |
371 | * Only meaningful if setAutoSaveSettings(QString) was called. |
372 | * This can be useful for forcing a save or an apply, e.g. before and after |
373 | * using KEditToolbar. |
374 | * |
375 | * NOTE: you should rather use saveAutoSaveSettings() for saving or autoSaveConfigGroup() for loading. |
376 | * This method doesn't make sense if setAutoSaveSettings(KConfigGroup) was called. |
377 | */ |
378 | QString autoSaveGroup() const; |
379 | |
380 | /** |
381 | * @return the group used for setting-autosaving. |
382 | * Only meaningful if setAutoSaveSettings() was called. |
383 | * This can be useful for forcing an apply, e.g. after using KEditToolbar. |
384 | * @since 4.1 |
385 | */ |
386 | KConfigGroup autoSaveConfigGroup() const; |
387 | |
388 | /** |
389 | * Read settings for statusbar, menubar and toolbar from their respective |
390 | * groups in the config file and apply them. |
391 | * |
392 | * @param config Config group to read the settings from. |
393 | * @param forceGlobal see the same argument in KToolBar::applySettings |
394 | */ |
395 | virtual void applyMainWindowSettings( const KConfigGroup &config, bool forceGlobal = false); |
396 | |
397 | /** |
398 | * Save settings for statusbar, menubar and toolbar to their respective |
399 | * groups in the config group @p config. |
400 | * |
401 | * @param config Config group to save the settings to. |
402 | */ |
403 | void saveMainWindowSettings(const KConfigGroup &config); |
404 | |
405 | /** |
406 | * @return true if a -geometry argument was given on the command line, |
407 | * and this is the first window created (the one on which this option applies) |
408 | */ |
409 | bool initialGeometrySet() const; |
410 | |
411 | /** |
412 | * @internal |
413 | * Used from Konqueror when reusing the main window. |
414 | */ |
415 | void ignoreInitialGeometry(); |
416 | |
417 | /** |
418 | * Returns the path under which this window's D-Bus object is exported. |
419 | * @since 4.0.1 |
420 | */ |
421 | QString dbusName() const; |
422 | |
423 | public Q_SLOTS: |
424 | /** |
425 | * Makes a KDE compliant caption (window title). |
426 | * |
427 | * @param caption Your caption. @em Do @em not include the application name |
428 | * in this string. It will be added automatically according to the KDE |
429 | * standard. |
430 | */ |
431 | virtual void setCaption( const QString &caption ); |
432 | /** |
433 | * Makes a KDE compliant caption. |
434 | * |
435 | * @param caption Your caption. @em Do @em not include the application name |
436 | * in this string. It will be added automatically according to the KDE |
437 | * standard. |
438 | * @param modified Specify whether the document is modified. This displays |
439 | * an additional sign in the title bar, usually "**". |
440 | */ |
441 | virtual void setCaption( const QString &caption, bool modified ); |
442 | |
443 | /** |
444 | * Make a plain caption without any modifications. |
445 | * |
446 | * @param caption Your caption. This is the string that will be |
447 | * displayed in the window title. |
448 | */ |
449 | virtual void setPlainCaption( const QString &caption ); |
450 | |
451 | /** |
452 | * Open the help page for the application. |
453 | * |
454 | * The application name is |
455 | * used as a key to determine what to display and the system will attempt |
456 | * to open \<appName\>/index.html. |
457 | * |
458 | * This method is intended for use by a help button in the toolbar or |
459 | * components outside the regular help menu. Use helpMenu() when you |
460 | * want to provide access to the help system from the help menu. |
461 | * |
462 | * Example (adding a help button to the first toolbar): |
463 | * |
464 | * \code |
465 | * toolBar(0)->addAction(KIcon("help-contents"), i18n("Help"), |
466 | * this, SLOT(appHelpActivated())); |
467 | * \endcode |
468 | * |
469 | */ |
470 | void appHelpActivated( void ); |
471 | |
472 | /** |
473 | * Tell the main window that it should save its settings when being closed. |
474 | * This is part of the auto-save-settings feature. |
475 | * For everything related to toolbars this happens automatically, |
476 | * but you have to call setSettingsDirty() in the slot that toggles |
477 | * the visibility of the statusbar. |
478 | */ |
479 | void setSettingsDirty(); |
480 | |
481 | protected: |
482 | /** |
483 | * Reimplemented to catch QEvent::Polish in order to adjust the object name |
484 | * if needed, once all constructor code for the main window has run. |
485 | * Also reimplemented to catch when a QDockWidget is added or removed. |
486 | */ |
487 | virtual bool event( QEvent * event ); |
488 | |
489 | /** |
490 | * Reimplemented to call the queryClose() and queryExit() handlers. |
491 | */ |
492 | virtual void closeEvent ( QCloseEvent *); |
493 | |
494 | // KDE4 This seems to be flawed to me. Either the app has only one |
495 | // mainwindow, so queryClose() is enough, or if it can have more of them, |
496 | // then the windows should take care of themselves, and queryExit() |
497 | // would be useful only for the annoying 'really quit' dialog, which |
498 | // also doesn't make sense in apps with multiple mainwindows. |
499 | // And saving configuration in something called queryExit()? IMHO |
500 | // one can e.g. use QCoreApplication::aboutToQuit(), which if nothing else |
501 | // has at least better fitting name. |
502 | // See also KApplication::sessionSaving(). |
503 | // This stuff should get changed somehow, so that it at least doesn't |
504 | // mess with session management. |
505 | /** |
506 | Called before the very last window is closed, either by the |
507 | user or indirectly by the session manager. |
508 | |
509 | It is not recommended to do any user interaction in this |
510 | function other than indicating severe errors. Better ask the |
511 | user on queryClose() (see below). |
512 | |
513 | A typical usage of queryExit() is to write configuration data back. |
514 | Note that the application may continue to run after queryExit() |
515 | (the user may have canceled a shutdown), so you should not do any cleanups |
516 | here. The purpose of queryExit() is purely to prepare the application |
517 | (with possible user interaction) so it can safely be closed later (without |
518 | user interaction). |
519 | |
520 | If you need to do serious things on exit (like shutting a |
521 | dial-up connection down), connect to the signal |
522 | QCoreApplication::aboutToQuit(). |
523 | |
524 | Default implementation returns @p true. Returning @p false will |
525 | cancel the exiting. In the latter case, the last window will |
526 | remain visible. If KApplication::sessionSaving() is true, refusing |
527 | the exit will also cancel KDE logout. |
528 | |
529 | @see queryClose() |
530 | @see KApplication::sessionSaving() |
531 | |
532 | @deprecated since 4.14 Do not reimplement queryExit. Either reimplement queryClose |
533 | (called for every window) or connect QCoreApplication::aboutToQuit() into a slot |
534 | of a non-gui object (not a KMainWindow, it will be deleted before that!). |
535 | */ |
536 | virtual bool queryExit(); |
537 | |
538 | /** |
539 | Called before the window is closed, either by the user or indirectly by |
540 | the session manager. |
541 | |
542 | The purpose of this function is to prepare the window in a way that it is |
543 | safe to close it, i.e. without the user losing some data. |
544 | |
545 | Default implementation returns true. Returning @p false will cancel |
546 | the closing, and, if KApplication::sessionSaving() is true, it will also |
547 | cancel KDE logout. |
548 | |
549 | Reimplement this function to prevent the user from losing data. |
550 | Example: |
551 | \code |
552 | switch ( KMessageBox::warningYesNoCancel( this, |
553 | i18n("Save changes to document foo?")) ) { |
554 | case KMessageBox::Yes : |
555 | // save document here. If saving fails, return false; |
556 | return true; |
557 | case KMessageBox::No : |
558 | return true; |
559 | default: // cancel |
560 | return false; |
561 | \endcode |
562 | |
563 | Note that you should probably @em not actually close the document from |
564 | within this method, as it may be called by the session manager before the |
565 | session is saved. If the document is closed before the session save occurs, |
566 | its location might not be properly saved. In addition, the session shutdown |
567 | may be canceled, in which case the document should remain open. |
568 | |
569 | @see queryExit() |
570 | @see KApplication::sessionSaving() |
571 | */ |
572 | virtual bool queryClose(); |
573 | |
574 | /** |
575 | * Save your instance-specific properties. The function is |
576 | * invoked when the session manager requests your application |
577 | * to save its state. |
578 | * |
579 | * Please reimplement these function in childclasses. |
580 | * |
581 | * Note: No user interaction is allowed |
582 | * in this function! |
583 | * |
584 | */ |
585 | virtual void saveProperties( KConfigGroup & ) {} |
586 | |
587 | /** |
588 | * Read your instance-specific properties. |
589 | * |
590 | * Is called indirectly by restore(). |
591 | */ |
592 | virtual void readProperties( const KConfigGroup & ) {} |
593 | |
594 | /** |
595 | * Save your application-wide properties. The function is |
596 | * invoked when the session manager requests your application |
597 | * to save its state. |
598 | * |
599 | * This function is similar to saveProperties() but is only called for |
600 | * the very first main window, regardless how many main window are open. |
601 | |
602 | * Override it if you need to save other data about your documents on |
603 | * session end. sessionConfig is a config to which that data should be |
604 | * saved. Normally, you don't need this function. But if you want to save |
605 | * data about your documents that are not in opened windows you might need |
606 | * it. |
607 | * |
608 | * Default implementation does nothing. |
609 | */ |
610 | virtual void saveGlobalProperties( KConfig* sessionConfig ); |
611 | |
612 | /** |
613 | * The counterpart of saveGlobalProperties(). |
614 | * |
615 | * Read the application-specific properties in again. |
616 | */ |
617 | virtual void readGlobalProperties( KConfig* sessionConfig ); |
618 | void savePropertiesInternal( KConfig*, int ); |
619 | bool readPropertiesInternal( KConfig*, int ); |
620 | |
621 | /** |
622 | * For inherited classes |
623 | */ |
624 | bool settingsDirty() const; |
625 | /** |
626 | * For inherited classes |
627 | */ |
628 | void saveWindowSize( const KConfigGroup &config ) const; |
629 | /** |
630 | * For inherited classes |
631 | * Note that a -geometry on the command line has priority. |
632 | */ |
633 | void restoreWindowSize( const KConfigGroup & config ); |
634 | |
635 | /// parse the geometry from the geometry command line argument |
636 | void parseGeometry(bool parsewidth); |
637 | |
638 | protected Q_SLOTS: |
639 | /** |
640 | * This slot does nothing. |
641 | * |
642 | * It must be reimplemented if you want |
643 | * to use a custom About Application dialog box. This slot is |
644 | * connected to the About Application entry in the menu returned |
645 | * by customHelpMenu. |
646 | * |
647 | * Example: |
648 | * \code |
649 | * |
650 | * void MyMainLevel::setupInterface() |
651 | * { |
652 | * .. |
653 | * menuBar()->addMenu( customHelpMenu() ); |
654 | * .. |
655 | * } |
656 | * |
657 | * void MyMainLevel::showAboutApplication() |
658 | * { |
659 | * <activate your custom dialog> |
660 | * } |
661 | * \endcode |
662 | */ |
663 | virtual void showAboutApplication(); |
664 | |
665 | /** |
666 | * This slot should only be called in case you reimplement closeEvent() and |
667 | * if you are using the "auto-save" feature. In all other cases, |
668 | * setSettingsDirty() should be called instead to benefit from the delayed |
669 | * saving. |
670 | * |
671 | * @see setAutoSaveSettings |
672 | * @see setSettingsDirty |
673 | * |
674 | * Example: |
675 | * \code |
676 | * |
677 | * void MyMainWindow::closeEvent( QCloseEvent *e ) |
678 | * { |
679 | * // Save settings if auto-save is enabled, and settings have changed |
680 | * if ( settingsDirty() && autoSaveSettings() ) |
681 | * saveAutoSaveSettings(); |
682 | * .. |
683 | * } |
684 | * \endcode |
685 | */ |
686 | void saveAutoSaveSettings(); |
687 | |
688 | protected: |
689 | KMainWindow(KMainWindowPrivate &dd, QWidget *parent, Qt::WindowFlags f); |
690 | |
691 | KMainWindowPrivate * const k_ptr; |
692 | private: |
693 | Q_PRIVATE_SLOT(k_func(), void _k_shuttingDown()) |
694 | Q_PRIVATE_SLOT(k_func(), void _k_slotSettingsChanged(int)) |
695 | Q_PRIVATE_SLOT(k_func(), void _k_slotSaveAutoSaveSize()) |
696 | }; |
697 | |
698 | /** |
699 | * @def RESTORE |
700 | * @ingroup KDEUIMacros |
701 | * Restores the last session. (To be used in your main function). |
702 | * |
703 | * If your client has only one kind of toplevel widgets (which |
704 | * should be pretty usual) then you can use this macro, |
705 | * which is provided for backwards compatibility with 3.1 and 3.0 |
706 | * branches: |
707 | * |
708 | * \code |
709 | * if (qApp->isSessionRestored()) |
710 | * RESTORE(childMW) |
711 | * else { |
712 | * // create default application as usual |
713 | * } |
714 | * \endcode |
715 | * |
716 | * The macro expects the type of your toplevel widget as argument. |
717 | * |
718 | * Since KDE4, you can also use kRestoreMainWindows(), which |
719 | * supports also clients with more than one kind of toplevel |
720 | * widgets. |
721 | * |
722 | * @see KMainWindow::restore() |
723 | * @see kRestoreMainWindows() |
724 | **/ |
725 | #define RESTORE(type) { int n = 1;\ |
726 | while (KMainWindow::canBeRestored(n)){\ |
727 | (new type)->restore(n);\ |
728 | n++;}} |
729 | |
730 | /** |
731 | * @def KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS |
732 | * @ingroup KDEUIMacros |
733 | * Returns the maximal number of arguments that are actually |
734 | * supported by kRestoreMainWindows(). |
735 | **/ |
736 | #define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS 3 |
737 | |
738 | /** |
739 | * Restores the last session. (To be used in your main function). |
740 | * |
741 | * These functions work also if you have more than one kind of toplevel |
742 | * widget (each derived from KMainWindow, of course). |
743 | * |
744 | * Imagine you have three kinds of toplevel widgets: the classes childMW1, |
745 | * childMW2 and childMW3. Than you can just do: |
746 | * |
747 | * \code |
748 | * if (qApp->isSessionRestored()) |
749 | * kRestoreMainWindows< childMW1, childMW2, childMW3 >(); |
750 | * else { |
751 | * // create default application as usual |
752 | * } |
753 | * \endcode |
754 | * |
755 | * kRestoreMainWindows<>() will create (on the heap) as many instances |
756 | * of your main windows as have existed in the last session and |
757 | * call KMainWindow::restore() with the correct arguments. Note that |
758 | * also QWidget::show() is called implicitly. |
759 | * |
760 | * Currently, these functions are provided for up to three |
761 | * template arguments. If you need more, tell us. To help you in |
762 | * deciding whether or not you can use kRestoreMainWindows, a |
763 | * define #KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS is provided. |
764 | * |
765 | * These global convenience functions (that come with a varying |
766 | * number of template arguments) are a replacement for the #RESTORE |
767 | * macro provided in earlier versions of KDE. The old #RESTORE macro |
768 | * is still provided for backwards compatibility. |
769 | * |
770 | * @see KMainWindow::restore() |
771 | * @see #RESTORE |
772 | * @see KMainWindow::classNameOfToplevel() |
773 | **/ |
774 | template <typename T> |
775 | inline void kRestoreMainWindows() { |
776 | for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) { |
777 | const QString className = KMainWindow::classNameOfToplevel( n ); |
778 | if ( className == QLatin1String( T::staticMetaObject.className() ) ) |
779 | (new T)->restore( n ); |
780 | } |
781 | } |
782 | |
783 | template <typename T0, typename T1> |
784 | inline void kRestoreMainWindows() { |
785 | const char * classNames[2]; |
786 | classNames[0] = T0::staticMetaObject.className(); |
787 | classNames[1] = T1::staticMetaObject.className(); |
788 | for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) { |
789 | const QString className = KMainWindow::classNameOfToplevel( n ); |
790 | if ( className == QLatin1String( classNames[0] ) ) |
791 | (new T0)->restore( n ); |
792 | else if ( className == QLatin1String( classNames[1] ) ) |
793 | (new T1)->restore( n ); |
794 | } |
795 | } |
796 | |
797 | template <typename T0, typename T1, typename T2> |
798 | inline void kRestoreMainWindows() { |
799 | const char * classNames[3]; |
800 | classNames[0] = T0::staticMetaObject.className(); |
801 | classNames[1] = T1::staticMetaObject.className(); |
802 | classNames[2] = T2::staticMetaObject.className(); |
803 | for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) { |
804 | const QString className = KMainWindow::classNameOfToplevel( n ); |
805 | if ( className == QLatin1String( classNames[0] ) ) |
806 | (new T0)->restore( n ); |
807 | else if ( className == QLatin1String( classNames[1] ) ) |
808 | (new T1)->restore( n ); |
809 | else if ( className == QLatin1String( classNames[2] ) ) |
810 | (new T2)->restore( n ); |
811 | } |
812 | } |
813 | |
814 | #endif |
815 | |