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
38class KMenu;
39class KConfig;
40class KConfigGroup;
41class KStatusBar;
42class KMenuBar;
43class KMWSessionManager;
44class KMainWindowPrivate;
45class 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
106class 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
117public:
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
423public 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
481protected:
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
638protected 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
688protected:
689 KMainWindow(KMainWindowPrivate &dd, QWidget *parent, Qt::WindowFlags f);
690
691 KMainWindowPrivate * const k_ptr;
692private:
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 **/
774template <typename T>
775inline 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
783template <typename T0, typename T1>
784inline 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
797template <typename T0, typename T1, typename T2>
798inline 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