Member Function Documentation

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

Constructs a main window.

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

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).

See also KAboutData.

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

Destructor.

Will also destroy the toolbars and menubar if needed.

[slot] void KMainWindow::appHelpActivated()

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 also helpMenu() and toolBar().

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

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

config Config group to read the settings from.

[since 4.1] KConfigGroup KMainWindow::autoSaveConfigGroup() const

Returns 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.

This function was introduced in 4.1.

See also setAutoSaveSettings() and autoSaveGroup().

QString KMainWindow::autoSaveGroup() const

Returns 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.

See also autoSaveSettings(), setAutoSaveSettings(), saveAutoSaveSettings(), resetAutoSaveSettings(), and autoSaveConfigGroup().

bool KMainWindow::autoSaveSettings() const

Returns true if setAutoSaveSettings() was called, false by default or if resetAutoSaveSettings() was called.

See also setAutoSaveSettings() and resetAutoSaveSettings().

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

Returns true if the number of KMainWindow instances of the previous session did contain the requested numberOfInstances, false otherwise.

numberOfInstances The number of KMainWindow instances in the application.

See also restore().

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

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 instanceNumber.

See also restore().

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

Reimplements: QWidget::closeEvent(QCloseEvent *event).

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.

[since 4.0.1] QString KMainWindow::dbusName() const

Returns The path for the exported window's D-Bus object.

This function was introduced in 4.0.1.

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

Reimplements: QMainWindow::event(QEvent *event).

Reimplemented to return the event 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 true if there is a menubar, false otherwise.

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

Reimplements: QWidget::keyPressEvent(QKeyEvent *event).

Reimplemented to open context menus on Shift+F10.

keyEvent The event assigned to a key press.

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

Returns The list of members of the KMainWindow class.

[virtual protected] bool KMainWindow::queryClose()

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.

Usage 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;

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

See also KApplication::sessionSaving().

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

Reads your application-wide properties.

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

See also saveGlobalProperties() and readProperties().

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

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 also readGlobalProperties().

void KMainWindow::resetAutoSaveSettings()

Disables the autosave settings feature. You don't normally need to call this, ever.

See also setAutoSaveSettings() and autoSaveSettings().

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

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

You should call canBeRestored() first.

If the session did not contain so high a number, the configuration is not changed and 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 show is 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.

numberOfInstances The number of KMainWindow instances from the last session.

show Whether the KMainWindow instances will be visible by default.

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

See also kRestoreMainWindows(), readProperties(), and 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.

Usage example:

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

See also setAutoSaveSettings() and setSettingsDirty().

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

Saves your application-wide properties.

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 also readGlobalProperties() and saveProperties().

void KMainWindow::saveMainWindowSettings(KConfigGroup &config)

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

Usage example:

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

config Config group to save the settings to.

See also setAutoSaveSettings(), KConfig, KSharedConfig, and KConfigGroup.

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

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.

Usage example:

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

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

This enables autosave of toolbar/menubar/statusbar settings (and optionally window size).

groupName A name that identifies the type of window. You can have several types of window in the same application. If no groupName is specified, the value defaults to "MainWindow".

saveWindowSize Whether to include the window size when saving. 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 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 also autoSaveSettings(), KConfig, KSharedConfig, saveMainWindowSettings(), toolBar(), and KXmlGuiWindow::setupGUI().

[since 4.1] void KMainWindow::setAutoSaveSettings(const KConfigGroup &group, bool saveWindowSize = true)

This function overloads KMainWindow::setAutoSaveSettings(const QString &groupName = QStringLiteral("MainWindow"), bool saveWindowSize = true).

This allows the settings to be saved into a different file that does not correspond to that used for KSharedConfig::openConfig().

group A name that identifies the type of window. You can have several types of window in the same application.

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

This function was introduced in 4.1.

See also setAutoSaveSettings(const QString &groupName, bool saveWindowSize), KConfig, and KSharedConfig.

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

Assigns a KDE compliant caption (window title).

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

See also setPlainCaption().

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

Makes a KDE compliant caption.

caption Your caption.

modified Whether the document is modified. This displays an additional sign in the title bar, usually "**".

This is an overloaded function.

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

Make a plain caption without any modifications.

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

See also setCaption().

[slot] void KMainWindow::setSettingsDirty()

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 also settingsDirty() and saveAutoSaveSettings().

[since 5.88] void KMainWindow::setStateConfigGroup(const QString &configGroup)

Assigns the config group name for the KConfigGroup returned by stateConfigGroup.

configGroup The config group to be assigned.

Window size and state are stored in the resulting KConfigGroup when this function is called.

This function was introduced in 5.88.

See also KConfigGroup(), KSharedConfig::openStateConfig(), and stateConfigGroup().

[protected] bool KMainWindow::settingsDirty() const

Returns whether there are unsaved changes.

For inherited classes.

[since 5.88] 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.

This function was introduced in 5.88.

See also setStateConfigGroup() and KConfigGroup.

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

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.

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

Returns A pointer to the toolbar with the specified name.

See also toolBars().

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

Returns a list of all toolbars for this window

int main(int argc, char *argv[])
{
    // [...]
    if (qApp->isSessionRestored())
        kRestoreMainWindows<ChildMW1, ChildMW2, ChildMW3>();
    else {
      // create default application as usual
    }
    // [...]
}