Member Function Documentation

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

@brief Construct a main window.

Note that by default a KXmlGuiWindow 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:

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

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

@code KXmlGuiWindow *kmw = new KXmlGuiWindow(...); kmw->setObjectName(...); @endcode

IMPORTANT: For session management and window management to work properly, all main windows in the application should have a different name. Otherwise, the base class 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#".

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

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

@see KMainWindow::KMainWindow

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

@brief Destructor.

Will also destroy the toolbars and menubar if needed.

[protected] void KXmlGuiWindow::checkAmbiguousShortcuts()

@brief Checks if there are actions using the same shortcut.

This is called automatically from createGUI().

@since 5.30

[virtual slot] void KXmlGuiWindow::configureToolbars()

@brief Show a standard configure toolbar dialog.

This slot can be connected directly to the action to configure the toolbar.

@code KStandardAction::configureToolbars(this, &KXmlGuiWindow::configureToolbars, actionCollection); @endcode

void KXmlGuiWindow::createGUI(const QString &xmlfile = QString())

@brief Generates the interface based on a local XML file.

This is the function that generates UI elements such as the main menu, toolbar (if any) and statusbar. This is called by setupGUI(Create) as well.

Typically, in a regular application, you would use setupGUI() instead, as it sets up the toolbar/shortcut edit actions, among other things.

If @p xmlfile is an empty string, this method will try to construct a local XML filename like appnameui.rc where 'appname' is your app's name. Typically that app name is what KXMLGUIClient::componentName() returns. If that file does not exist, then the XML UI code will use only the global (standard) XML file for its layout purposes.

@param xmlfile The path (relative or absolute) to the local xmlfile

@see setupGUI()

void KXmlGuiWindow::createStandardStatusBarAction()

@brief Creates a toggle under the 'Settings' menu to show/hide the statusbar.

Calling this method will create a statusbar if one doesn't already exist.

If an application maintains the action on its own (i.e. never calls this function), a connection needs to be made to let KMainWindow know when the hidden/shown status of the statusbar has changed. For example: @code connect(action, &QAction::triggered, kmainwindow, &KMainWindow::setSettingsDirty); @endcode Otherwise the status might not be saved by KMainWindow.

@note This function only makes sense before calling createGUI() or when using setupGUI() without @ref StandardWindowOption::StatusBar.

@see createGUI() @see setupGUI() @see StandardWindowOption @see KStandardAction::showStatusbar() @see setStandardToolBarMenuEnabled() @see QMainWindow::setStatusBar() @see QMainWindow::statusBar()

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

Reimplements: 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.

void KXmlGuiWindow::finalizeGUI(bool force)

@internal

bool KXmlGuiWindow::isCommandBarEnabled() const

@brief Returns whether a KCommandBar was set. @returns @c true by default, @c false if setCommandBarEnabled(false) was set. @since 5.83 @see setCommandBarEnabled()

bool KXmlGuiWindow::isHelpMenuEnabled() const

@returns @c true if the help menu is enabled, @c false if setHelpMenuEnabled(false) was set. @see setHelpMenuEnabled()

bool KXmlGuiWindow::isStandardToolBarMenuEnabled() const

@brief Returns whether setStandardToolBarMenuEnabled() was set.

@note This function only makes sense if createGUI() was used. This function returns true only if setStandardToolBarMenuEnabled() was set and will return false even if @ref StandardWindowOption::ToolBar was used.

@returns @c true if setStandardToolBarMenuEnabled() was set, @c false otherwise.

@see createGUI() @see setupGUI() @see setStandardToolBarMenuEnabled() @see StandardWindowOption

[virtual protected slot] void KXmlGuiWindow::saveNewToolbarConfig()

@brief Rebuilds the GUI after KEditToolBar changes the toolbar layout. @see configureToolbars()

void KXmlGuiWindow::setCommandBarEnabled(bool showCommandBar)

@brief Enable a KCommandBar to list and quickly execute actions.

A KXmlGuiWindow by default automatically creates a KCommandBar, but it is inaccessible unless createGUI() or setupGUI(Create) is used.

It provides a HUD-like menu that lists all QActions in your application and can be activated via Ctrl+Atl+i or via an action in the 'Help' menu.

If you need more than a global set of QActions listed for your application, use KCommandBar directly instead.

@param showCommandBar Whether to show the command bar. @c true by default.

@since 5.83

@see KCommandBar @see KCommandBar::setActions() @see isCommandBarEnabled()

See also isCommandBarEnabled().

void KXmlGuiWindow::setHelpMenuEnabled(bool showHelpMenu = true)

@brief Creates a standard help menu when calling createGUI() or setupGUI().

@param showHelpMenu Whether to create a Help Menu. @c true by default.

@see isHelpMenuEnabled()

See also isHelpMenuEnabled().

void KXmlGuiWindow::setStandardToolBarMenuEnabled(bool showToolBarMenu)

@brief Creates a toggle under the 'Settings' menu to show/hide the available toolbars.

The standard toolbar menu toggles the visibility of one or multiple toolbars.

If there is only one toolbar configured, a simple 'Show <toolbar name>' menu item is shown; if more than one toolbar is configured, a "Shown Toolbars" menu is created instead, with 'Show <toolbar1 name>', 'Show <toolbar2 name>' ... sub-menu actions.

If your application uses a non-default XmlGui resource file, then you can specify the exact position of the menu/menu item by adding a &lt;Merge name="StandardToolBarMenuHandler" /&gt; line to the settings menu section of your resource file ( usually appname.rc ).

@param showToolBarMenu Whether to show the standard toolbar menu. @c false by default.

@note This function only makes sense before calling createGUI(). Using setupGUI(ToolBar) overrides this function.

@see createGUI() @see setupGUI() @see KToggleBarAction @see StandardWindowOption @see KMainWindow::toolBar() @see KMainWindow::toolBars() @see QMainWindow::addToolBar() @see QMainWindow::removeToolBar() @see createStandardStatusBarAction()

See also isStandardToolBarMenuEnabled().

void KXmlGuiWindow::setupGUI(KXmlGuiWindow::StandardWindowOptions options = Default, const QString &xmlfile = QString())

@brief Configures the current window and its actions in the typical KDE fashion.

You can specify which window options/features are going to be set up using @p options, see the @ref StandardWindowOptions enum for more details.

@code MainWindow::MainWindow(QWidget* parent) : KXmlGuiWindow(parent){ textArea = new KTextEdit(); setCentralWidget(textArea); setupGUI(Default, "appnameui.rc"); } @endcode

Use a bitwise OR (|) to select multiple enum choices for setupGUI() (except when using StandardWindowOption::Default).

@code setupGUI(Save | Create, "appnameui.rc"); @endcode

Typically this function replaces createGUI(), but it is possible to call setupGUI(Create) together with helper functions such as setStandardToolBarMenuEnabled() and createStandardStatusBarAction().

@warning To use createGUI() and setupGUI() for the same window, you must avoid using @ref StandardWindowOption::Create. Prefer using only setupGUI().

@note When @ref StandardWindowOption::Save is used, this method will restore the state of the application window (toolbar, dockwindows positions ...etc), so you need to have added all your actions to your UI before calling this method.

@param options A combination of @ref StandardWindowOptions to specify UI elements to be present in your application window. @param xmlfile The relative or absolute path to the local xmlfile. If this is an empty string, the code will look for a local XML file appnameui.rc, where 'appname' is the name of your app. See the note about the xmlfile argument in createGUI(). @see StandardWindowOption

void KXmlGuiWindow::setupGUI(const QSize &defaultSize, KXmlGuiWindow::StandardWindowOptions options = Default, const QString &xmlfile = QString())

@brief This is an overloaded function.

@param defaultSize A manually specified window size that overrides the saved size. @param options A combination of @ref StandardWindowOptions to specify UI elements to be present in your application window. @param xmlfile The relative or absolute path to the local xmlfile. @see setupGUI()

void KXmlGuiWindow::setupToolbarMenuActions()

@internal for KToolBar

[virtual slot] void KXmlGuiWindow::slotStateChanged(const QString &newstate)

@brief Applies a state change

Reimplement this to enable and disable actions as defined in the XmlGui rc file.

@param newstate The state change to be applied.

[slot] void KXmlGuiWindow::slotStateChanged(const QString &newstate, bool reverse)

@brief Applies a state change

Reimplement this to enable and disable actions as defined in the XmlGui rc file.

This function can "reverse" the state (disable the actions which should be enabled, and vice-versa) if specified.

@param newstate The state change to be applied. @param reverse Whether to reverse @p newstate or not.

QAction *KXmlGuiWindow::toolBarMenuAction()

@returns A pointer to the main window's action responsible for the toolbar's menu.