KXmlGuiWindow
#include <KXmlGuiWindow>
Public Types | |
enum | StandardWindowOption { ToolBar = 1 , Keys = 2 , StatusBar = 4 , Save = 8 , Create = 16 , Default = ToolBar | Keys | StatusBar | Save | Create } |
typedef QFlags< StandardWindowOption > | StandardWindowOptions |
Public Types inherited from QMainWindow | |
enum | DockOption |
Public Types inherited from QWidget | |
enum | RenderFlag |
Public Types inherited from QPaintDevice | |
enum | PaintDeviceMetric |
Public Types inherited from KXMLGUIClient | |
enum | ReverseStateChange { StateNoReverse , StateReverse } |
Public Slots | |
virtual void | configureToolbars () |
virtual void | slotStateChanged (const QString &newstate) |
void | slotStateChanged (const QString &newstate, bool reverse) |
Public Slots inherited from KMainWindow | |
void | appHelpActivated () |
virtual void | setCaption (const QString &caption) |
virtual void | setCaption (const QString &caption, bool modified) |
virtual void | setPlainCaption (const QString &caption) |
void | setSettingsDirty () |
Protected Slots | |
virtual void | saveNewToolbarConfig () |
Protected Slots inherited from KMainWindow | |
void | saveAutoSaveSettings () |
Detailed Description
KMainWindow with convenience functions and integration with XmlGui files.
This class includes several convenience <action>Enabled() functions to toggle the presence of functionality in your main window, including a KCommandBar instance.
The StandardWindowOptions enum can be used to pass additional options to describe the main window behavior/appearance. Use it in conjunction with setupGUI() to load an appnameui.rc file to manage the main window's actions.
setCommandBarEnabled() is set by default.
A minimal example can be created with QMainWindow::setCentralWidget() and setupGUI():
With this, a ready-made main window with menubar and statusbar is created, as well as two default menus, Settings and Help.
Management of QActions is made trivial in combination with KActionCollection and KStandardAction.
See https://develop.kde.org/docs/use/kxmlgui/ for a tutorial on how to create a simple text editor using KXmlGuiWindow.
See https://develop.kde.org/docs/use/session-managment for more information on session management.
Definition at line 87 of file kxmlguiwindow.h.
Member Typedef Documentation
◆ StandardWindowOptions
Stores a combination of StandardWindowOptions values.
Use these options for the first argument of setupGUI().
- See also
- setupGUI()
- StandardWindowOption
Definition at line 334 of file kxmlguiwindow.h.
Member Enumeration Documentation
◆ StandardWindowOption
Use these options for the first argument of setupGUI().
- See also
- setupGUI()
- StandardWindowOption
Enumerator | |
---|---|
ToolBar | Adds action(s) to show/hide the toolbar(s) and adds a menu action to configure the toolbar(s). |
Keys | Adds an action in the 'Settings' menu to open the configure keyboard shortcuts dialog. |
StatusBar | Adds an action to show/hide the statusbar in the 'Settings' menu. Note that setting this value will create a statusbar if one doesn't already exist.
|
Save | Autosaves (and loads) the toolbar/menubar/statusbar settings and window size using the default name. Like KMainWindow::setAutoSaveSettings(), enabling this causes the application to save state data upon close in a KConfig-managed configuration file. Typically you want to let the default window size be determined by the widgets' size hints. Make sure that setupGUI() is called after all the widgets are created (including QMainWindow::setCentralWidget()) so that the default size is managed properly. |
Create | Calls createGUI() once ToolBar, Keys and Statusbar have been taken care of.
@ StatusBar Adds an action to show/hide the statusbar in the 'Settings' menu. Definition kxmlguiwindow.h:286 @ Save Autosaves (and loads) the toolbar/menubar/statusbar settings and window size using the default name. Definition kxmlguiwindow.h:303 @ Keys Adds an action in the 'Settings' menu to open the configure keyboard shortcuts dialog. Definition kxmlguiwindow.h:277
|
Default | Sets all of the above options as true. |
Definition at line 263 of file kxmlguiwindow.h.
Property Documentation
◆ autoSaveGroup
|
read |
Definition at line 92 of file kxmlguiwindow.h.
◆ autoSaveSettings
|
read |
Definition at line 91 of file kxmlguiwindow.h.
◆ hasMenuBar
|
read |
Definition at line 90 of file kxmlguiwindow.h.
◆ standardToolBarMenuEnabled
|
readwrite |
Definition at line 93 of file kxmlguiwindow.h.
Constructor & Destructor Documentation
◆ KXmlGuiWindow()
|
explicit |
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:
KXmlGuiWindows must be created on the heap with 'new', like:
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#".
- Parameters
-
parent The widget parent. This is usually nullptr
, but it may also be the window group leader. In that case, the KXmlGuiWindow becomes a secondary window.flags Specify the window flags. The default is none.
- See also
- KMainWindow::KMainWindow
Definition at line 148 of file kxmlguiwindow.cpp.
◆ ~KXmlGuiWindow()
|
override |
Destructor.
Will also destroy the toolbars and menubar if needed.
Definition at line 213 of file kxmlguiwindow.cpp.
Member Function Documentation
◆ applyMainWindowSettings()
|
overridevirtual |
Read settings for statusbar, menubar and toolbar from their respective groups in the config file and apply them.
- Parameters
-
config Config group to read the settings from.
Reimplemented from KMainWindow.
Definition at line 481 of file kxmlguiwindow.cpp.
◆ checkAmbiguousShortcuts()
|
protected |
Checks if there are actions using the same shortcut.
This is called automatically from createGUI().
- Since
- 5.30
Definition at line 491 of file kxmlguiwindow.cpp.
◆ configureToolbars
|
virtualslot |
Show a standard configure toolbar dialog.
This slot can be connected directly to the action to configure the toolbar.
Definition at line 261 of file kxmlguiwindow.cpp.
◆ createGUI()
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 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.
- Parameters
-
xmlfile The path (relative or absolute) to the local xmlfile
- See also
- setupGUI()
Definition at line 328 of file kxmlguiwindow.cpp.
◆ createStandardStatusBarAction()
void KXmlGuiWindow::createStandardStatusBarAction | ( | ) |
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:
Otherwise the status might not be saved by KMainWindow.
- Note
- This function only makes sense before calling createGUI() or when using setupGUI() without StandardWindowOption::StatusBar.
- See also
- createGUI()
- setupGUI()
- StandardWindowOption
- KStandardAction::showStatusbar()
- setStandardToolBarMenuEnabled()
- QMainWindow::setStatusBar()
- QMainWindow::statusBar()
Definition at line 453 of file kxmlguiwindow.cpp.
◆ event()
|
overrideprotectedvirtual |
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.
Reimplemented from KMainWindow.
Definition at line 219 of file kxmlguiwindow.cpp.
◆ finalizeGUI() [1/2]
void KXmlGuiWindow::finalizeGUI | ( | bool | force | ) |
Definition at line 470 of file kxmlguiwindow.cpp.
◆ finalizeGUI() [2/2]
|
virtual |
Reimplemented from KXMLGUIBuilder.
Definition at line 73 of file kxmlguibuilder.cpp.
◆ guiFactory()
|
virtual |
Definition at line 249 of file kxmlguiwindow.cpp.
◆ isCommandBarEnabled()
bool KXmlGuiWindow::isCommandBarEnabled | ( | ) | const |
Returns whether a KCommandBar was set.
- Returns
true
by default,false
if setCommandBarEnabled(false) was set.
- Since
- 5.83
- See also
- setCommandBarEnabled()
Definition at line 562 of file kxmlguiwindow.cpp.
◆ isHelpMenuEnabled()
bool KXmlGuiWindow::isHelpMenuEnabled | ( | ) | const |
- Returns
true
if the help menu is enabled,false
if setHelpMenuEnabled(false) was set.
- See also
- setHelpMenuEnabled()
Definition at line 243 of file kxmlguiwindow.cpp.
◆ isStandardToolBarMenuEnabled()
bool KXmlGuiWindow::isStandardToolBarMenuEnabled | ( | ) | const |
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 StandardWindowOption::ToolBar was used.
- Returns
true
if setStandardToolBarMenuEnabled() was set,false
otherwise.
Definition at line 447 of file kxmlguiwindow.cpp.
◆ saveNewToolbarConfig
|
protectedvirtualslot |
Rebuilds the GUI after KEditToolBar changes the toolbar layout.
- See also
- configureToolbars()
Definition at line 274 of file kxmlguiwindow.cpp.
◆ setCommandBarEnabled()
void KXmlGuiWindow::setCommandBarEnabled | ( | bool | showCommandBar | ) |
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.
- Parameters
-
showCommandBar Whether to show the command bar. true
by default.
- Since
- 5.83
- See also
- KCommandBar
- KCommandBar::setActions()
- isCommandBarEnabled()
Unset the shortcut
Definition at line 546 of file kxmlguiwindow.cpp.
◆ setHelpMenuEnabled()
Creates a standard help menu when calling createGUI() or setupGUI().
- Parameters
-
showHelpMenu Whether to create a Help Menu. true
by default.
- See also
- isHelpMenuEnabled()
Definition at line 237 of file kxmlguiwindow.cpp.
◆ setStandardToolBarMenuEnabled()
void KXmlGuiWindow::setStandardToolBarMenuEnabled | ( | bool | showToolBarMenu | ) |
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 <Merge name="StandardToolBarMenuHandler" /> line to the settings menu section of your resource file ( usually appname.rc ).
- Parameters
-
showToolBarMenu Whether to show the standard toolbar menu. false
by default.
- Note
- This function only makes sense before calling createGUI(). Using setupGUI(ToolBar) overrides this function.
- See also
- createGUI()
- setupGUI()
- KToggleBarAction
- StandardWindowOption
- KMainWindow::toolBar()
- KMainWindow::toolBars()
- QMainWindow::addToolBar()
- QMainWindow::removeToolBar()
- createStandardStatusBarAction()
Definition at line 420 of file kxmlguiwindow.cpp.
◆ setupGUI() [1/2]
void KXmlGuiWindow::setupGUI | ( | const QSize & | defaultSize, |
StandardWindowOptions | options = Default, | ||
const QString & | xmlfile = QString() ) |
This is an overloaded function.
- Parameters
-
defaultSize A manually specified window size that overrides the saved size. options A combination of StandardWindowOptions to specify UI elements to be present in your application window. xmlfile The relative or absolute path to the local xmlfile.
- See also
- setupGUI()
Definition at line 290 of file kxmlguiwindow.cpp.
◆ setupGUI() [2/2]
void KXmlGuiWindow::setupGUI | ( | StandardWindowOptions | options = Default, |
const QString & | xmlfile = QString() ) |
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 options
, see the StandardWindowOptions enum for more details.
Use a bitwise OR (|) to select multiple enum choices for setupGUI() (except when using StandardWindowOption::Default).
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 StandardWindowOption::Create. Prefer using only setupGUI().
- Note
- When 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.
- Parameters
-
options A combination of StandardWindowOptions to specify UI elements to be present in your application window. 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 also
- StandardWindowOption
Definition at line 285 of file kxmlguiwindow.cpp.
◆ setupToolbarMenuActions()
void KXmlGuiWindow::setupToolbarMenuActions | ( | ) |
for KToolBar
Definition at line 205 of file kxmlguiwindow.cpp.
◆ slotStateChanged [1/2]
Applies a state change.
Reimplement this to enable and disable actions as defined in the XmlGui rc file.
- Parameters
-
newstate The state change to be applied.
Definition at line 410 of file kxmlguiwindow.cpp.
◆ slotStateChanged [2/2]
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.
- Parameters
-
newstate The state change to be applied. reverse Whether to reverse newstate
or not.
Definition at line 415 of file kxmlguiwindow.cpp.
◆ toolBarMenuAction()
QAction * KXmlGuiWindow::toolBarMenuAction | ( | ) |
- Returns
- A pointer to the main window's action responsible for the toolbar's menu.
Definition at line 195 of file kxmlguiwindow.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:47:50 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.