File indexing completed on 2024-06-16 04:15:39
0001 /* 0002 This file is part of the KDE libraries 0003 Copyright 0004 (C) 2000 Reginald Stadlbauer (reggie@kde.org) 0005 (C) 1997 Stephan Kulow (coolo@kde.org) 0006 (C) 1997-2000 Sven Radej (radej@kde.org) 0007 (C) 1997-2000 Matthias Ettrich (ettrich@kde.org) 0008 (C) 1999 Chris Schlaeger (cs@kde.org) 0009 (C) 2002 Joseph Wenninger (jowenn@kde.org) 0010 (C) 2005-2006 Hamish Rodda (rodda@kde.org) 0011 (C) 2000-2008 David Faure (faure@kde.org) 0012 0013 SPDX-License-Identifier: LGPL-2.0-only 0014 0015 */ 0016 0017 #ifndef KMAINWINDOW_H 0018 #define KMAINWINDOW_H 0019 0020 #include <kritawidgetutils_export.h> 0021 0022 #include <QMainWindow> 0023 #include <QMetaClassInfo> 0024 0025 class QMenu; 0026 class KConfig; 0027 class KConfigGroup; 0028 class KMWSessionManager; 0029 class KisKMainWindowPrivate; 0030 class KisToolBar; 0031 0032 // internal, not public API, may change any time 0033 #define XMLGUI_DECLARE_PRIVATE(classname) \ 0034 inline classname ## Private *k_func() { return reinterpret_cast<classname ## Private *>(k_ptr); } \ 0035 inline const classname ## Private *k_func() const { return reinterpret_cast<classname ## Private *>(k_ptr); } \ 0036 friend class classname ## Private; 0037 0038 /** 0039 * @short %KDE top level main window 0040 * 0041 * Top level widget that provides toolbars, a status line and a frame. 0042 * 0043 * It should be used as a top level (parent-less) widget. 0044 * It manages the geometry for all its children, including your 0045 * main widget. 0046 * 0047 * Normally, you will inherit from KisKMainWindow, 0048 * then construct (or use some existing) widget as 0049 * your main view. You can set only one main view. 0050 * 0051 * You can add as many toolbars as you like. There can be only one menubar 0052 * and only one statusbar. 0053 * 0054 * The toolbars, menubar, and statusbar can be created by the 0055 * KisKMainWindow and - unlike the old KisKMainWindow - may, but do not 0056 * have to, be deleted by you. KisKMainWindow will handle that internally. 0057 * 0058 * Height and width can be operated independently from each other. Simply 0059 * define the minimum/maximum height/width of your main widget and 0060 * KisKMainWindow will take this into account. For fixed size windows set 0061 * your main widget to a fixed size. 0062 * 0063 * Fixed aspect ratios (heightForWidth()) and fixed width widgets are 0064 * not supported. 0065 * 0066 * KisKMainWindow will set icon, mini icon and caption, which it gets 0067 * from KApplication. It provides full session management, and 0068 * will save its position, geometry and positions of toolbars and 0069 * menubar on logout. If you want to save additional data, reimplement 0070 * saveProperties() and (to read them again on next login) 0071 * readProperties(). To save special data about your data, reimplement 0072 * saveGlobalProperties(). To warn user that application or 0073 * windows have unsaved data on close or logout, reimplement 0074 * queryClose(). 0075 * 0076 * You have to implement session restoring also in your main() function. 0077 * There are also kRestoreMainWindows convenience functions which 0078 * can do this for you and restore all your windows on next login. 0079 * 0080 * Note that KisKMainWindow uses KGlobal::ref() and KGlobal::deref() so that closing 0081 * the last mainwindow will quit the application unless there is still something 0082 * that holds a ref in KGlobal - like a KIO job, or a systray icon. 0083 * 0084 * @see KApplication 0085 * @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) 0086 */ 0087 0088 class KRITAWIDGETUTILS_EXPORT KisKMainWindow : public QMainWindow 0089 { 0090 friend class KMWSessionManager; 0091 friend class DockResizeListener; 0092 XMLGUI_DECLARE_PRIVATE(KisKMainWindow) 0093 Q_OBJECT 0094 Q_PROPERTY(bool hasMenuBar READ hasMenuBar) 0095 Q_PROPERTY(bool autoSaveSettings READ autoSaveSettings) 0096 Q_PROPERTY(QString autoSaveGroup READ autoSaveGroup) 0097 0098 public: 0099 /** 0100 * Construct a main window. 0101 * 0102 * @param parent The widget parent. This is usually 0 but it may also be the window 0103 * group leader. In that case, the KisKMainWindow becomes sort of a 0104 * secondary window. 0105 * 0106 * @param f Specify the window flags. The default is none. 0107 * 0108 * Note that a KisKMainWindow per-default is created with the 0109 * WA_DeleteOnClose attribute, i.e. it is automatically destroyed when the 0110 * window is closed. If you do not want this behavior, call 0111 * setAttribute(Qt::WA_DeleteOnClose, false); 0112 * 0113 * KisKMainWindows must be created on the heap with 'new', like: 0114 * \code 0115 * KisKMainWindow *kmw = new KisKMainWindow(...); 0116 * kmw->setObjectName(...); 0117 * \endcode 0118 * 0119 * IMPORTANT: For session management and window management to work 0120 * properly, all main windows in the application should have a 0121 * different name. If you don't do it, KisKMainWindow will create 0122 * a unique name, but it's recommended to explicitly pass a window name that will 0123 * also describe the type of the window. If there can be several windows of the same 0124 * type, append '#' (hash) to the name, and KisKMainWindow will replace it with numbers to make 0125 * the names unique. For example, for a mail client which has one main window showing 0126 * the mails and folders, and which can also have one or more windows for composing 0127 * mails, the name for the folders window should be e.g. "mainwindow" and 0128 * for the composer windows "composer#". 0129 * 0130 */ 0131 explicit KisKMainWindow(QWidget *parent = 0, Qt::WindowFlags f = Qt::WindowFlags()); 0132 0133 /** 0134 * \brief Destructor. 0135 * 0136 * Will also destroy the toolbars, and menubar if 0137 * needed. 0138 */ 0139 ~KisKMainWindow() override; 0140 0141 /** 0142 * If the session did contain so high a number, @p true is returned, 0143 * else @p false. 0144 * @see restore() 0145 **/ 0146 static bool canBeRestored(int number); 0147 0148 /** 0149 * Returns the className() of the @p number of the toplevel window which 0150 * should be restored. 0151 * 0152 * This is only useful if your application uses 0153 * different kinds of toplevel windows. 0154 */ 0155 static const QString classNameOfToplevel(int number); 0156 0157 /** 0158 * Try to restore the toplevel widget as defined by @p number (1..X). 0159 * 0160 * You should call canBeRestored() first. 0161 * 0162 * If the session did not contain so high a number, the configuration 0163 * is not changed and @p false returned. 0164 * 0165 * That means clients could simply do the following: 0166 * \code 0167 * if (qApp->isSessionRestored()){ 0168 * int n = 1; 0169 * while (KisKMainWindow::canBeRestored(n)){ 0170 * (new childMW)->restore(n); 0171 * n++; 0172 * } 0173 * } else { 0174 * // create default application as usual 0175 * } 0176 * \endcode 0177 * Note that if @p show is true (default), QWidget::show() is called 0178 * implicitly in restore. 0179 * 0180 * With this you can easily restore all toplevel windows of your 0181 * application. 0182 * 0183 * If your application uses different kinds of toplevel 0184 * windows, then you can use KisKMainWindow::classNameOfToplevel(n) 0185 * to determine the exact type before calling the childMW 0186 * constructor in the example from above. 0187 * 0188 * <i>Note that you don't need to deal with this function. Use the 0189 * kRestoreMainWindows() convenience template function instead!</i> 0190 * @see kRestoreMainWindows() 0191 * @see readProperties() 0192 * @see canBeRestored() 0193 */ 0194 bool restore(int number, bool show = true); 0195 0196 /** 0197 * Returns true, if there is a menubar 0198 */ 0199 bool hasMenuBar(); 0200 0201 /** 0202 * List of members of KisKMainWindow class. 0203 */ 0204 static QList<KisKMainWindow *> memberList(); 0205 0206 /** 0207 * Returns a pointer to the toolbar with the specified name. 0208 * This refers to toolbars created dynamically from the XML UI 0209 * framework. If the toolbar does not exist one will be created. 0210 * 0211 * @param name The internal name of the toolbar. If no name is 0212 * specified "mainToolBar" is assumed. 0213 * 0214 * @return A pointer to the toolbar 0215 **/ 0216 KisToolBar *toolBar(const QString &name = QString()); 0217 0218 /** 0219 * @return A list of all toolbars for this window 0220 */ 0221 QList<KisToolBar *> toolBars() const; 0222 0223 /** 0224 * Call this to enable "auto-save" of toolbar/menubar/statusbar settings 0225 * (and optionally window size). 0226 * If the *bars were moved around/shown/hidden when the window is closed, 0227 * saveMainWindowSettings( KConfigGroup(KSharedConfig::openConfig(), groupName) ) will be called. 0228 * 0229 * @param groupName a name that identifies this "type of window". 0230 * You can have several types of window in the same application. 0231 * 0232 * @param saveWindowSize set it to true to include the window size 0233 * when saving. 0234 * 0235 * Typically, you will call setAutoSaveSettings() in your 0236 * KisKMainWindow-inherited class constructor, and it will take care 0237 * of restoring and saving automatically. Make sure you call this 0238 * _after all_ your *bars have been created. 0239 * 0240 * To make sure that KisKMainWindow properly obtains the default 0241 * size of the window you should do the following: 0242 * - Remove hard coded resize() calls in the constructor or main, they 0243 * should be removed in favor of letting the automatic resizing 0244 * determine the default window size. Hard coded window sizes will 0245 * be wrong for users that have big fonts, use different styles, 0246 * long/small translations, large toolbars, and other factors. 0247 * - Put the setAutoSaveSettings ( or setupGUI() ) call after all widgets 0248 * have been created and placed inside the main window (i.e. for 99% of 0249 * apps setCentralWidget()) 0250 * - Widgets that inherit from QWidget (like game boards) should overload 0251 * "virtual QSize sizeHint() const;" to specify a default size rather 0252 * than letting QWidget::adjust use the default size of 0x0. 0253 */ 0254 void setAutoSaveSettings(const QString &groupName = QLatin1String("MainWindow"), 0255 bool saveWindowSize = true); 0256 0257 /** 0258 * Overload that lets you specify a KConfigGroup. 0259 * This allows the settings to be saved into another file than KSharedConfig::openConfig(). 0260 * @since 4.1 0261 */ 0262 void setAutoSaveSettings(const KConfigGroup &group, 0263 bool saveWindowSize = true); 0264 0265 /** 0266 * Disable the auto-save-settings feature. 0267 * You don't normally need to call this, ever. 0268 */ 0269 void resetAutoSaveSettings(); 0270 0271 /** 0272 * @return the current autosave setting, i.e. true if setAutoSaveSettings() was called, 0273 * false by default or if resetAutoSaveSettings() was called. 0274 */ 0275 bool autoSaveSettings() const; 0276 0277 /** 0278 * @return the group used for setting-autosaving. 0279 * Only meaningful if setAutoSaveSettings(QString) was called. 0280 * This can be useful for forcing a save or an apply, e.g. before and after 0281 * using KisKEditToolbar. 0282 * 0283 * NOTE: you should rather use saveAutoSaveSettings() for saving or autoSaveConfigGroup() for loading. 0284 * This method doesn't make sense if setAutoSaveSettings(KConfigGroup) was called. 0285 */ 0286 QString autoSaveGroup() const; 0287 0288 /** 0289 * @return the group used for setting-autosaving. 0290 * Only meaningful if setAutoSaveSettings() was called. 0291 * This can be useful for forcing an apply, e.g. after using KisKEditToolbar. 0292 * @since 4.1 0293 */ 0294 KConfigGroup autoSaveConfigGroup() const; 0295 0296 /** 0297 * Read settings for statusbar, menubar and toolbar from their respective 0298 * groups in the config file and apply them. 0299 * 0300 * @param config Config group to read the settings from. 0301 * KF5 porting note: the unused bool argument was removed, make sure to remove it from your 0302 * reimplementations too! And add a override for good measure. 0303 */ 0304 virtual void applyMainWindowSettings(const KConfigGroup &config); 0305 0306 /** 0307 * Save settings for statusbar, menubar and toolbar to their respective 0308 * groups in the config group @p config. 0309 * 0310 * @param config Config group to save the settings to. 0311 */ 0312 void saveMainWindowSettings(KConfigGroup &config); 0313 0314 /** 0315 * Returns the path under which this window's D-Bus object is exported. 0316 * @since 4.0.1 0317 */ 0318 QString dbusName() const; 0319 0320 public Q_SLOTS: 0321 0322 /** 0323 * Open the help page for the application. 0324 * 0325 * The application name is 0326 * used as a key to determine what to display and the system will attempt 0327 * to open \<appName\>/index.html. 0328 * 0329 * This method is intended for use by a help button in the toolbar or 0330 * components outside the regular help menu. Use helpMenu() when you 0331 * want to provide access to the help system from the help menu. 0332 * 0333 * Example (adding a help button to the first toolbar): 0334 * 0335 * \code 0336 * toolBar(0)->addAction(KisIconUtils::loadIcon("help-contents"), i18n("Help"), 0337 * this, SLOT(appHelpActivated())); 0338 * \endcode 0339 * 0340 */ 0341 void appHelpActivated(void); 0342 0343 /** 0344 * Tell the main window that it should save its settings when being closed. 0345 * This is part of the auto-save-settings feature. 0346 * For everything related to toolbars this happens automatically, 0347 * but you have to call setSettingsDirty() in the slot that toggles 0348 * the visibility of the statusbar. 0349 */ 0350 void setSettingsDirty(); 0351 0352 protected: 0353 /** 0354 * Reimplemented to catch QEvent::Polish in order to adjust the object name 0355 * if needed, once all constructor code for the main window has run. 0356 * Also reimplemented to catch when a QDockWidget is added or removed. 0357 */ 0358 bool event(QEvent *event) override; 0359 0360 /** 0361 * Reimplemented to autosave settings and call queryClose(). 0362 * 0363 * We recommend that you reimplement queryClose() rather than closeEvent(). 0364 * If you do it anyway, ensure to call the base implementation to keep 0365 * the feature of auto-saving window settings working. 0366 */ 0367 void closeEvent(QCloseEvent *) override; 0368 0369 /** 0370 Called before the window is closed, either by the user or indirectly by 0371 the session manager. 0372 0373 The purpose of this function is to prepare the window in a way that it is 0374 safe to close it, i.e. without the user losing some data. 0375 0376 Default implementation returns true. Returning @p false will cancel 0377 the closing, and, if KApplication::sessionSaving() is true, it will also 0378 cancel KDE logout. 0379 0380 Reimplement this function to prevent the user from losing data. 0381 Example: 0382 \code 0383 switch ( KMessageBox::warningYesNoCancel( this, 0384 i18n("Save changes to document foo?")) ) { 0385 case KMessageBox::Yes : 0386 // save document here. If saving fails, return false; 0387 return true; 0388 case KMessageBox::No : 0389 return true; 0390 default: // cancel 0391 return false; 0392 \endcode 0393 0394 Note that you should probably @em not actually close the document from 0395 within this method, as it may be called by the session manager before the 0396 session is saved. If the document is closed before the session save occurs, 0397 its location might not be properly saved. In addition, the session shutdown 0398 may be canceled, in which case the document should remain open. 0399 0400 @see KApplication::sessionSaving() 0401 */ 0402 virtual bool queryClose(); 0403 0404 /** 0405 * Save your instance-specific properties. The function is 0406 * invoked when the session manager requests your application 0407 * to save its state. 0408 * 0409 * Please reimplement these function in childclasses. 0410 * 0411 * Note: No user interaction is allowed 0412 * in this function! 0413 * 0414 */ 0415 virtual void saveProperties(KConfigGroup &) {} 0416 0417 /** 0418 * Read your instance-specific properties. 0419 * 0420 * Is called indirectly by restore(). 0421 */ 0422 virtual void readProperties(const KConfigGroup &) {} 0423 0424 /** 0425 * Save your application-wide properties. The function is 0426 * invoked when the session manager requests your application 0427 * to save its state. 0428 * 0429 * This function is similar to saveProperties() but is only called for 0430 * the very first main window, regardless how many main window are open. 0431 0432 * Override it if you need to save other data about your documents on 0433 * session end. sessionConfig is a config to which that data should be 0434 * saved. Normally, you don't need this function. But if you want to save 0435 * data about your documents that are not in opened windows you might need 0436 * it. 0437 * 0438 * Default implementation does nothing. 0439 */ 0440 virtual void saveGlobalProperties(KConfig *sessionConfig); 0441 0442 /** 0443 * The counterpart of saveGlobalProperties(). 0444 * 0445 * Read the application-specific properties in again. 0446 */ 0447 virtual void readGlobalProperties(KConfig *sessionConfig); 0448 void savePropertiesInternal(KConfig *, int); 0449 bool readPropertiesInternal(KConfig *, int); 0450 0451 /** 0452 * For inherited classes 0453 */ 0454 bool settingsDirty() const; 0455 0456 virtual bool windowsLayoutSavingAllowed() const; 0457 0458 protected Q_SLOTS: 0459 0460 /** 0461 * This slot should only be called in case you reimplement closeEvent() and 0462 * if you are using the "auto-save" feature. In all other cases, 0463 * setSettingsDirty() should be called instead to benefit from the delayed 0464 * saving. 0465 * 0466 * @see setAutoSaveSettings 0467 * @see setSettingsDirty 0468 * 0469 * Example: 0470 * \code 0471 * 0472 * void MyMainWindow::closeEvent( QCloseEvent *e ) 0473 * { 0474 * // Save settings if auto-save is enabled, and settings have changed 0475 * if ( settingsDirty() && autoSaveSettings() ) 0476 * saveAutoSaveSettings(); 0477 * .. 0478 * } 0479 * \endcode 0480 */ 0481 void saveAutoSaveSettings(); 0482 0483 protected: 0484 KisKMainWindow(KisKMainWindowPrivate &dd, QWidget *parent, Qt::WindowFlags f); 0485 0486 KisKMainWindowPrivate *const k_ptr; 0487 private: 0488 Q_PRIVATE_SLOT(k_func(), void _k_slotSettingsChanged(int)) 0489 Q_PRIVATE_SLOT(k_func(), void _k_slotSaveAutoSaveSize()) 0490 }; 0491 0492 /** 0493 * @def KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS 0494 * @ingroup XMLGUIMacros 0495 * Returns the maximal number of arguments that are actually 0496 * supported by kRestoreMainWindows(). 0497 **/ 0498 #define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS 3 0499 0500 /** 0501 * Restores the last session. (To be used in your main function). 0502 * 0503 * These functions work also if you have more than one kind of toplevel 0504 * widget (each derived from KisKMainWindow, of course). 0505 * 0506 * Imagine you have three kinds of toplevel widgets: the classes childMW1, 0507 * childMW2 and childMW3. Than you can just do: 0508 * 0509 * \code 0510 * if (qApp->isSessionRestored()) 0511 * kRestoreMainWindows< childMW1, childMW2, childMW3 >(); 0512 * else { 0513 * // create default application as usual 0514 * } 0515 * \endcode 0516 * 0517 * kRestoreMainWindows<>() will create (on the heap) as many instances 0518 * of your main windows as have existed in the last session and 0519 * call KisKMainWindow::restore() with the correct arguments. Note that 0520 * also QWidget::show() is called implicitly. 0521 * 0522 * Currently, these functions are provided for up to three 0523 * template arguments. If you need more, tell us. To help you in 0524 * deciding whether or not you can use kRestoreMainWindows, a 0525 * define #KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS is provided. 0526 * 0527 * @see KisKMainWindow::restore() 0528 * @see KisKMainWindow::classNameOfToplevel() 0529 **/ 0530 template <typename T> 0531 inline void kRestoreMainWindows() 0532 { 0533 for (int n = 1; KisKMainWindow::canBeRestored(n); ++n) { 0534 const QString className = KisKMainWindow::classNameOfToplevel(n); 0535 if (className == QLatin1String(T::staticMetaObject.className())) { 0536 (new T)->restore(n); 0537 } 0538 } 0539 } 0540 0541 template <typename T0, typename T1> 0542 inline void kRestoreMainWindows() 0543 { 0544 const char *classNames[2]; 0545 classNames[0] = T0::staticMetaObject.className(); 0546 classNames[1] = T1::staticMetaObject.className(); 0547 for (int n = 1; KisKMainWindow::canBeRestored(n); ++n) { 0548 const QString className = KisKMainWindow::classNameOfToplevel(n); 0549 if (className == QLatin1String(classNames[0])) { 0550 (new T0)->restore(n); 0551 } else if (className == QLatin1String(classNames[1])) { 0552 (new T1)->restore(n); 0553 } 0554 } 0555 } 0556 0557 template <typename T0, typename T1, typename T2> 0558 inline void kRestoreMainWindows() 0559 { 0560 const char *classNames[3]; 0561 classNames[0] = T0::staticMetaObject.className(); 0562 classNames[1] = T1::staticMetaObject.className(); 0563 classNames[2] = T2::staticMetaObject.className(); 0564 for (int n = 1; KisKMainWindow::canBeRestored(n); ++n) { 0565 const QString className = KisKMainWindow::classNameOfToplevel(n); 0566 if (className == QLatin1String(classNames[0])) { 0567 (new T0)->restore(n); 0568 } else if (className == QLatin1String(classNames[1])) { 0569 (new T1)->restore(n); 0570 } else if (className == QLatin1String(classNames[2])) { 0571 (new T2)->restore(n); 0572 } 0573 } 0574 } 0575 0576 #endif