Member Function Documentation

[explicit] KMainWindow::KMainWindow(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

@brief Constructs a main window.

@param parent The parent widget. This is usually @c nullptr, but it may also be the window group leader. In that case, the KMainWindow becomes a secondary window.

@param flags Specify the window flags. The default is none.

Note that by default a KMainWindow is created with the Qt::WA_DeleteOnClose attribute set, i.e. it is automatically destroyed when the window is closed. If you do not want this behavior, call

window->setAttribute(Qt::WA_DeleteOnClose, false);

KMainWindows must be created on the heap with 'new', like:

KMainWindow *kmw = new KMainWindow(...);
kmw->setObjectName(...);

Since KDE Frameworks 5.16, KMainWindow will enter information regarding the application's translators by default, using KAboutData::setTranslator(). This only occurs if no translators are already assigned in KAboutData (see KAboutData::setTranslator() for details – the auto-assignment here uses the same translated strings as specified for that function).

IMPORTANT: For session management and window management to work properly, all main windows in the application should have a different name. Otherwise, KMainWindow will create a unique name, but it's recommended to explicitly pass a window name that will also describe the type of the window. If there can be several windows of the same type, append '#' (hash) to the name, and KMainWindow will replace it with numbers to make the names unique. For example, for a mail client which has one main window showing the mails and folders, and which can also have one or more windows for composing mails, the name for the folders window should be e.g. "mainwindow" and for the composer windows "composer#".

@see KAboutData

[override virtual noexcept] KMainWindow::~KMainWindow()

@brief Destructor.

Will also destroy the toolbars and menubar if needed.

[slot] void KMainWindow::appHelpActivated()

@brief Opens the help page for the application.

The application name is used as a key to determine what to display and the system will attempt to open <appName>/index.html.

This method is intended for use by a help button in the toolbar or components outside the regular help menu.

Use helpMenu() when you want to provide access to the help system from the help menu.

Example (adding a help button to the first toolbar):

toolBar()->addAction(QIcon::fromTheme("help-contents"), i18n("Help"),
                      this, &KMainWindow::appHelpActivated);

@see helpMenu() @see toolBar()

[virtual] void KMainWindow::applyMainWindowSettings(const KConfigGroup &config)

@brief Read settings for statusbar, menubar and toolbar from their respective groups in the config file and apply them.

@param config Config group to read the settings from.

KConfigGroup KMainWindow::autoSaveConfigGroup() const

@return The group used for autosaving settings.

Only meaningful if setAutoSaveSettings(const QString&, bool) was called.

Do not use this method if setAutoSaveSettings(const KConfigGroup&, bool) was called.

This can be useful for forcing an apply, e.g. after using KEditToolBar.

@see setAutoSaveSettings() @see autoSaveGroup() @since 4.1

QString KMainWindow::autoSaveGroup() const

@return The group used for autosaving settings.

Do not mistake this with autoSaveConfigGroup.

Only meaningful if setAutoSaveSettings(const QString&, bool) was called.

Do not use this method if setAutoSaveSettings(const KConfigGroup&, bool) was called.

This can be useful for forcing a save or an apply, e.g. before and after using KEditToolBar.

@note Prefer saveAutoSaveSettings() for saving or autoSaveConfigGroup() for loading.

@see autoSaveSettings() @see setAutoSaveSettings() @see saveAutoSaveSettings() @see resetAutoSaveSettings() @see autoSaveConfigGroup()

bool KMainWindow::autoSaveSettings() const

@return @c true if setAutoSaveSettings() was called, @c false by default or if resetAutoSaveSettings() was called. @see setAutoSaveSettings() @see resetAutoSaveSettings()

See also setAutoSaveSettings().

[static] bool KMainWindow::canBeRestored(int numberOfInstances)

@param numberOfInstances The number of KMainWindow instances in the application. @returns @c true if the number of KMainWindow instances of the previous session did contain the requested @p numberOfInstances, @c false otherwise. @see restore()

[static] const QString KMainWindow::classNameOfToplevel(int instanceNumber)

@brief Useful if your application uses different kinds of top-level windows.

@returns The class name of the top-level window to be restored that corresponds to @p instanceNumber.

@param instanceNumber @see restore()

[override virtual protected] void KMainWindow::closeEvent(QCloseEvent *)

Reimplemented to autosave settings and call queryClose().

We recommend that you reimplement queryClose() rather than closeEvent(). If you do it anyway, ensure to call the base implementation to keep the feature of autosaving window settings working.

QString KMainWindow::dbusName() const

@returns The path for the exported window's D-Bus object. @since 4.0.1

[override virtual protected] bool KMainWindow::event(QEvent *event)

Reimplemented to catch QEvent::Polish in order to adjust the object name if needed, once all constructor code for the main window has run. Also reimplemented to catch when a QDockWidget is added or removed.

bool KMainWindow::hasMenuBar()

@returns @c true if there is a menubar, @c false otherwise.

[override virtual protected] void KMainWindow::keyPressEvent(QKeyEvent *keyEvent)

Reimplemented to open context menus on Shift+F10.

[static] QList<KMainWindow *> KMainWindow::memberList()

@returns The list of members of the KMainWindow class.

[virtual protected] bool KMainWindow::queryClose()

@brief This function is called before the window is closed, either by the user or indirectly by the session manager.

This can be used to prompt the user to save unsaved data before the window is closed.

Example:

switch ( KMessageBox::warningTwoActionsCancel( this,
         i18n("Save changes to document foo?"), QString(),
         KStandardGuiItem::save(), KStandardGuiItem::discard())) ) {
  case KMessageBox::PrimaryAction :
    // save document here. If saving fails, return false;
    return true;
  case KMessageBox::SecondaryAction :
    return true;
  default: // cancel
    return false;

@note Do @em not close the document from within this method, as it may be called by the session manager before the session is saved. If the document is closed before the session save occurs, its location might not be properly saved. In addition, the session shutdown may be canceled, in which case the document should remain open.

@return @c true by default, @c false according to the reimplementation. Returning @c false will cancel the closing operation, and if KApplication::sessionSaving() is true, it cancels logout.

@see KApplication::sessionSaving()

[virtual protected] void KMainWindow::readGlobalProperties(KConfig *sessionConfig)

@brief Reads your application-wide properties.

@param sessionConfig A pointer to the KConfig instance used to load the session data.

@see saveGlobalProperties() @see readProperties()

[virtual protected] void KMainWindow::readProperties(const KConfigGroup &)

@brief Reads your instance-specific properties.

This function is called indirectly by restore().

void MainWindow::readProperties(KConfigGroup &config) {
  if (config.hasKey("myKey")) {
    config.readEntry("myKey", "DefaultValue");
  }
  ...
}

@see readGlobalProperties()

void KMainWindow::resetAutoSaveSettings()

@brief Disables the autosave settings feature. You don't normally need to call this, ever. @see setAutoSaveSettings() @see autoSaveSettings()

bool KMainWindow::restore(int numberOfInstances, bool show = true)

@brief Attempt to restore the top-level widget as defined by @p numberOfInstances (1..X).

You should call canBeRestored() first.

If the session did not contain so high a number, the configuration is not changed and @c false is returned.

That means clients could simply do the following:

if (qApp->isSessionRestored()){
  int n = 1;
  while (KMainWindow::canBeRestored(n)){
    (new childMW)->restore(n);
    n++;
  }
} else {
  // create default application as usual
}

Note that if @p show is @c true (default), QWidget::show() is called implicitly in restore.

With this you can easily restore all top-level windows of your application.

If your application uses different kinds of top-level windows, then you can use KMainWindow::classNameOfToplevel(n) to determine the exact type before calling the childMW constructor in the example from above.

@note You don't need to deal with this function. Use the kRestoreMainWindows() convenience template function instead!

@param numberOfInstances The number of KMainWindow instances from the last session. @param show Whether the KMainWindow instances will be visible by default.

@returns @c true if the session contained the same number of instances as the requested number, @c false if the session contained less instances than the requested number, in which case no configuration is changed.

@see kRestoreMainWindows() @see readProperties() @see canBeRestored()

[protected slot] void KMainWindow::saveAutoSaveSettings()

This slot should only be called in case you reimplement closeEvent() and if you are using the autosave feature. In all other cases, setSettingsDirty() should be called instead to benefit from the delayed saving.

Example:

void MyMainWindow::closeEvent( QCloseEvent *e )
{
  // Save settings if autosave is enabled, and settings have changed
  if ( settingsDirty() && autoSaveSettings() )
    saveAutoSaveSettings();
  ..
}

@see setAutoSaveSettings() @see setSettingsDirty()

[virtual protected] void KMainWindow::saveGlobalProperties(KConfig *sessionConfig)

@brief Saves your application-wide properties.

@param sessionConfig A pointer to the KConfig instance used to save the session data.

This function is invoked when the session manager requests your application to save its state. It is similar to saveProperties(), but it is only called for the first main window. This is useful to save global state of your application that isn't bound to a particular window.

The default implementation does nothing.

@see readGlobalProperties() @see saveProperties()

void KMainWindow::saveMainWindowSettings(KConfigGroup &config)

@brief Manually save the settings for statusbar, menubar and toolbar to their respective groups in the KConfigGroup @p config.

Example:

KConfigGroup group(KSharedConfig::openConfig(), "MainWindow");
saveMainWindowSettings(group);

@param config Config group to save the settings to. @see setAutoSaveSettings() @see KConfig @see KSharedConfig @see KConfigGroup

[virtual protected] void KMainWindow::saveProperties(KConfigGroup &)

@brief Saves your instance-specific properties.

The function is invoked when the session manager requests your application to save its state.

Reimplement this function in child classes.

void MainWindow::saveProperties(KConfigGroup &config) {
  config.writeEntry("myKey", "newValue");
  ...
}

@note No user interaction is allowed in this function!

void KMainWindow::setAutoSaveSettings(const KConfigGroup &group, bool saveWindowSize = true)

This is an overloaded function. This allows the settings to be saved into a different file that does not correspond to that used for KSharedConfig::openConfig(). @see setAutoSaveSettings(const QString &groupName, bool saveWindowSize) @see KConfig @see KSharedConfig @since 4.1

See also autoSaveSettings().

void KMainWindow::setAutoSaveSettings(const QString &groupName = QStringLiteral("MainWindow"), bool saveWindowSize = true)

@brief This enables autosave of toolbar/menubar/statusbar settings (and optionally window size). @param groupName A name that identifies the type of window. You can have several types of window in the same application. If no @p groupName is specified, the value defaults to "MainWindow".

@param saveWindowSize Whether to include the window size when saving. @c true by default.

If the *bars were modified when the window is closed, saveMainWindowSettings( KConfigGroup(KSharedConfig::openConfig(), groupName) ) will be called.

Typically, you will call setAutoSaveSettings() in your KMainWindow-inherited class constructor, and it will take care of restoring and saving automatically.

By default, this generates an appnamerc ini file as if using default KConfig constructor or KConfig::SimpleConfig.

Make sure you call this @em after all your *bars have been created.

To make sure that KMainWindow properly obtains the default size of the window you should do the following: - Remove hardcoded resize() calls in the constructor or main to let the automatic resizing determine the default window size. Hardcoded window sizes will be wrong for users that have big fonts, use different styles, long/small translations, large toolbars, and other factors. - Put the setAutoSaveSettings() call after all widgets have been created and placed inside the main window (for most apps this means QMainWindow::setCentralWidget()) - QWidget-based objects should overload "virtual QSize sizeHint() const;" to specify a default size. @see KConfig @see KSharedConfig @see saveMainWindowSettings() @see toolBar() @see KXmlGuiWindow::setupGUI()

[virtual slot] void KMainWindow::setCaption(const QString &caption)

@brief Assigns a KDE compliant caption (window title).

@param caption The string that will be displayed in the window title, before the application name.

@note This function does the same as setPlainCaption().

@note Do not include the application name in this string. It will be added automatically according to the KDE standard.

@see setPlainCaption()

[virtual slot] void KMainWindow::setCaption(const QString &caption, bool modified)

@brief Makes a KDE compliant caption. @param caption Your caption. @param modified Whether the document is modified. This displays an additional sign in the title bar, usually "**".

This is an overloaded function.

@note Do not include the application name in this string. It will be added automatically according to the KDE standard.

[virtual slot] void KMainWindow::setPlainCaption(const QString &caption)

@brief Make a plain caption without any modifications.

@param caption The string that will be displayed in the window title, before the application name.

@note This function does the same as setCaption().

@note Do not include the application name in this string. It will be added automatically according to the KDE standard.

@see setCaption()

[slot] void KMainWindow::setSettingsDirty()

@brief Tell the main window that it should save its settings when being closed.

This is part of the autosave settings feature.

For everything related to toolbars this happens automatically, but you have to call setSettingsDirty() in the slot that toggles the visibility of the statusbar.

@see saveAutoSaveSettings()

See also settingsDirty().

void KMainWindow::setStateConfigGroup(const QString &configGroup)

@brief Assigns the config group name for the KConfigGroup returned by stateConfigGroup. @param configGroup The config group to be assigned. Window size and state are stored in the resulting KConfigGroup when this function is called. @note If this is used in combination with setAutoSaveSettings, you should call this method first.

@see KConfigGroup() @see KSharedConfig::openStateConfig() @see stateConfigGroup()

@since 5.88

See also stateConfigGroup().

[protected] bool KMainWindow::settingsDirty() const

For inherited classes

KConfigGroup KMainWindow::stateConfigGroup() const

@returns The KConfigGroup used to store state data like window sizes or window state.

The resulting group is invalid if setStateConfig is not called explicitly.

@see KConfigGroup @since 5.88

See also setStateConfigGroup().

KToolBar *KMainWindow::toolBar(const QString &name = QString())

@brief This is useful to both call specific toolbars that have been created or to generate a default one upon call.

This refers to toolbars created dynamically from the XML UI framework via KConfig or appnameui.rc.

If the toolbar does not exist, one will be created.

@param name The internal name of the toolbar. If no name is specified, "mainToolBar" is assumed.

@return A pointer to the toolbar with the specified name. @see toolBars()

QList<KToolBar *> KMainWindow::toolBars() const

@return A list of all toolbars for this window