KXmlGui

kxmlguiwindow.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Reginald Stadlbauer <[email protected]>
4  SPDX-FileCopyrightText: 1997 Stephan Kulow <[email protected]>
5  SPDX-FileCopyrightText: 1997-2000 Sven Radej <[email protected]>
6  SPDX-FileCopyrightText: 1997-2000 Matthias Ettrich <[email protected]>
7  SPDX-FileCopyrightText: 1999 Chris Schlaeger <[email protected]>
8  SPDX-FileCopyrightText: 2002 Joseph Wenninger <[email protected]>
9  SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <[email protected]>
10 
11  SPDX-License-Identifier: LGPL-2.0-only
12 */
13 
14 #ifndef KXMLGUIWINDOW_H
15 #define KXMLGUIWINDOW_H
16 
17 #include "kmainwindow.h"
18 #include "kxmlguibuilder.h"
19 #include "kxmlguiclient.h"
20 
21 class KMenu;
22 class KXMLGUIFactory;
23 class KConfig;
24 class KConfigGroup;
25 class KToolBar;
26 class KXmlGuiWindowPrivate;
27 
28 /**
29  * @class KXmlGuiWindow kxmlguiwindow.h KXmlGuiWindow
30  *
31  * @short Top level main window with predefined action layout
32  *
33  * Instead of creating a KMainWindow manually and assigning menus, menu entries,
34  * toolbar buttons and actions to it by hand, this class can be used to load an
35  * rc file to manage the main window's actions.
36  *
37  * See https://techbase.kde.org/Development/Tutorials/Using_KActions#XMLGUI
38  * for essential information on the XML file format and usage of this class.
39  *
40  * @see KMainWindow
41  * @author Reginald Stadlbauer ([email protected]) Stephan Kulow ([email protected]), Matthias Ettrich ([email protected]), Chris Schlaeger ([email protected]), Sven Radej
42  ([email protected]). Maintained by Sven Radej ([email protected])
43 
44  */
45 
46 class KXMLGUI_EXPORT KXmlGuiWindow : public KMainWindow, public KXMLGUIBuilder, virtual public KXMLGUIClient
47 {
48  Q_OBJECT
49  Q_PROPERTY(bool hasMenuBar READ hasMenuBar)
50  Q_PROPERTY(bool autoSaveSettings READ autoSaveSettings)
51  Q_PROPERTY(QString autoSaveGroup READ autoSaveGroup)
52  Q_PROPERTY(bool standardToolBarMenuEnabled READ isStandardToolBarMenuEnabled WRITE setStandardToolBarMenuEnabled)
53 
54 public:
55  /**
56  * Construct a main window.
57  *
58  * @param parent The widget parent. This is usually 0 but it may also be the window
59  * group leader. In that case, the KXmlGuiWindow becomes sort of a
60  * secondary window.
61  *
62  * @param f Specify the window flags. The default is none.
63  *
64  * Note that a KXmlGuiWindow per-default is created with the
65  * Qt::WA_DeleteOnClose attribute set, i.e. it is automatically destroyed
66  * when the window is closed. If you do not want this behavior, call
67  * \code
68  * window->setAttribute(Qt::WA_DeleteOnClose, false);
69  * \endcode
70  *
71  * KXmlGuiWindows must be created on the heap with 'new', like:
72  * \code
73  * KXmlGuiWindow *kmw = new KXmlGuiWindow(...);
74  * kmw->setObjectName(...);
75  * \endcode
76  *
77  * IMPORTANT: For session management and window management to work
78  * properly, all main windows in the application should have a
79  * different name. If you don't do it, the base class KMainWindow will create
80  * a unique name, but it's recommended to explicitly pass a window name that will
81  * also describe the type of the window. If there can be several windows of the same
82  * type, append '#' (hash) to the name, and KMainWindow will replace it with numbers to make
83  * the names unique. For example, for a mail client which has one main window showing
84  * the mails and folders, and which can also have one or more windows for composing
85  * mails, the name for the folders window should be e.g. "mainwindow" and
86  * for the composer windows "composer#".
87  *
88  */
89  explicit KXmlGuiWindow(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags());
90 
91  /**
92  * \brief Destructor.
93  *
94  * Will also destroy the toolbars, and menubar if
95  * needed.
96  */
97  ~KXmlGuiWindow() override;
98 
99  /**
100  * Enables the build of a standard help menu when calling createGUI() or setupGUI().
101  *
102  * The default behavior is to build one, you must call this function
103  * to disable it
104  */
105  void setHelpMenuEnabled(bool showHelpMenu = true);
106 
107  /**
108  * Return @c true when the help menu is enabled
109  */
110  bool isHelpMenuEnabled() const;
111 
112  virtual KXMLGUIFactory *guiFactory();
113 
114  /**
115  * Create a GUI given a local XML file. In a regular app you usually want to use
116  * setupGUI() instead of this one since it does more things for free
117  * like setting up the toolbar/shortcut edit actions, etc.
118  *
119  * If @p xmlfile is an empty string,
120  * then it will try to construct a local XML filename like
121  * appnameui.rc where 'appname' is your app's name. If that file
122  * does not exist, then the XML UI code will only use the global
123  * (standard) XML file for the layout purposes.
124  *
125  * @param xmlfile The local xmlfile (relative or absolute)
126  */
127  void createGUI(const QString &xmlfile = QString());
128 
129  /**
130  * Sets whether KMainWindow should provide a menu that allows showing/hiding
131  * the available toolbars ( using KToggleToolBarAction ) . In case there
132  * is only one toolbar configured a simple 'Show <toolbar name here>' menu item
133  * is shown.
134  *
135  * The menu / menu item is implemented using xmlgui. It will be inserted in your
136  * menu structure in the 'Settings' menu.
137  *
138  * If your application uses a non-standard xmlgui resource file then you can
139  * specify the exact position of the menu / menu item by adding a
140  * &lt;Merge name="StandardToolBarMenuHandler" /&gt;
141  * line to the settings menu section of your resource file ( usually appname.rc ).
142  *
143  * @note You should enable this feature before calling createGUI() ( or similar ).
144  */
145  void setStandardToolBarMenuEnabled(bool enable);
146  bool isStandardToolBarMenuEnabled() const;
147 
148  /**
149  * Sets whether KMainWindow should provide a menu that allows showing/hiding
150  * of the statusbar ( using KStandardAction::showStatusbar()).
151  *
152  * The menu / menu item is implemented using xmlgui. It will be inserted
153  * in your menu structure in the 'Settings' menu.
154  *
155  * @note You should enable this feature before calling createGUI() ( or similar ).
156  *
157  * If an application maintains the action on its own (i.e. never calls
158  * this function) a connection needs to be made to let KMainWindow
159  * know when that status (hidden/shown) of the statusbar has changed.
160  * For example:
161  * @code
162  * connect(action, &QAction::triggered,
163  * kmainwindow, &KMainWindow::setSettingsDirty);
164  * @endcode
165  * Otherwise the status (hidden/show) of the statusbar might not be saved
166  * by KMainWindow.
167  */
168  void createStandardStatusBarAction();
169 
170  /**
171  * @see setupGUI()
172  * @see StandardWindowOptions
173  */
175  /**
176  * adds action to show/hide the toolbar(s) and adds
177  * action to configure the toolbar(s).
178  * @see setStandardToolBarMenuEnabled
179  */
180  ToolBar = 1,
181 
182  /**
183  * adds action to show the key configure action.
184  */
185  Keys = 2,
186 
187  /**
188  * adds action to show/hide the statusbar if the
189  * statusbar exists.
190  * @see createStandardStatusBarAction
191  */
192  StatusBar = 4,
193 
194  /**
195  * auto-saves (and loads) the toolbar/menubar/statusbar settings and
196  * window size using the default name.
197  *
198  * Typically you want to let the default window size be determined by
199  * the widgets size hints. Make sure that setupGUI() is called after
200  * all the widgets are created ( including setCentralWidget ) so the
201  * default size's will be correct.
202  * @see setAutoSaveSettings
203  */
204  Save = 8,
205 
206  /**
207  * calls createGUI() once ToolBar, Keys and Statusbar have been
208  * taken care of.
209  *
210  * @note When using KParts::MainWindow, remove this flag from the
211  * setupGUI call, since you'll be using createGUI(part) instead.
212  * @code
213  * setupGUI(ToolBar | Keys | StatusBar | Save);
214  * @endcode
215  * @see createGUI
216  */
217  Create = 16,
218 
219  /**
220  * All the above option
221  * (this is the default)
222  */
223  Default = ToolBar | Keys | StatusBar | Save | Create,
224  };
226  /**
227  * Stores a combination of #StandardWindowOption values.
228  */
230 
231  /**
232  * Configures the current windows and its actions in the typical KDE
233  * fashion. The options are all enabled by default but can be turned
234  * off if desired through the params or if the prereqs don't exists.
235  *
236  * Typically this function replaces createGUI().
237  *
238  * @see StandardWindowOptions
239  * @note Since this method will restore the state of the application (toolbar, dockwindows
240  * positions...), you need to have added all your actions to your toolbars etc before
241  * calling to this method. (This note is only applicable if you are using the @c Default or
242  * @c Save flag).
243  * @warning If you are calling createGUI yourself, remember to remove the @c Create flag from
244  * the @p options parameter.
245  *
246  */
247  void setupGUI(StandardWindowOptions options = Default, const QString &xmlfile = QString());
248 
249  /**
250  * Configures the current windows and its actions in the typical KDE
251  * fashion. The options are all enabled by default but can be turned
252  * off if desired through the params or if the prereqs don't exists.
253  *
254  * @param defaultSize The default size of the window
255  *
256  * Typically this function replaces createGUI().
257  *
258  * @see StandardWindowOptions
259  * @note Since this method will restore the state of the application (toolbar, dockwindows
260  * positions...), you need to have added all your actions to your toolbars etc before
261  * calling to this method. (This note is only applicable if you are using the @c Default or
262  * @c Save flag).
263  * @warning If you are calling createGUI yourself, remember to remove the @c Create flag from
264  * the @p options parameter. Also, call setupGUI always after you call createGUI.
265  */
266  void setupGUI(const QSize &defaultSize, StandardWindowOptions options = Default, const QString &xmlfile = QString());
267 
268  /**
269  * Returns a pointer to the mainwindows action responsible for the toolbars menu
270  */
271  QAction *toolBarMenuAction();
272 
273  /**
274  * @internal for KToolBar
275  */
276  void setupToolbarMenuActions();
277 
278  // TODO KF6 change it to "using KXMLGUIBuilder::finalizeGUI;"
279  void finalizeGUI(KXMLGUIClient *client) override;
280 
281  /**
282  * @internal
283  */
284  void finalizeGUI(bool force);
285 
286  // reimplemented for internal reasons
287  void applyMainWindowSettings(const KConfigGroup &config) override;
288 
289 public Q_SLOTS:
290  /**
291  * Show a standard configure toolbar dialog.
292  *
293  * This slot can be connected directly to the action to configure toolbar.
294  * This is very simple to do that by adding a single line
295  * \code
296  * KStandardAction::configureToolbars( this, SLOT( configureToolbars() ),
297  * actionCollection() );
298  * \endcode
299  */
300  virtual void configureToolbars();
301 
302  /**
303  * Apply a state change
304  *
305  * Enable and disable actions as defined in the XML rc file
306  */
307  virtual void slotStateChanged(const QString &newstate);
308 
309  /**
310  * Apply a state change
311  *
312  * Enable and disable actions as defined in the XML rc file,
313  * can "reverse" the state (disable the actions which should be
314  * enabled, and vice-versa) if specified.
315  */
316  void slotStateChanged(const QString &newstate, bool reverse);
317 
318 protected:
319  /**
320  * Reimplemented to catch QEvent::Polish in order to adjust the object name
321  * if needed, once all constructor code for the main window has run.
322  * Also reimplemented to catch when a QDockWidget is added or removed.
323  */
324  bool event(QEvent *event) override;
325 
326  /**
327  * Checks if there are actions using the same shortcut. This is called
328  * automatically from createGUI.
329  * @since 5.30
330  */
331  void checkAmbiguousShortcuts();
332 
333 protected Q_SLOTS:
334  /**
335  * Rebuilds the GUI after KEditToolBar changed the toolbar layout.
336  * @see configureToolbars()
337  */
338  virtual void saveNewToolbarConfig();
339 
340 private:
341  Q_DECLARE_PRIVATE_D(k_ptr, KXmlGuiWindow)
342 };
343 
344 Q_DECLARE_OPERATORS_FOR_FLAGS(KXmlGuiWindow::StandardWindowOptions)
345 
346 #endif
A KXMLGUIClient can be used with KXMLGUIFactory to create a GUI from actions and an XML document...
Definition: kxmlguiclient.h:39
Top level main window with predefined action layout.
Definition: kxmlguiwindow.h:46
Top level main window.
Definition: kmainwindow.h:92
Implements the creation of the GUI (menubar, menus and toolbars) as requested by the GUI factory...
Q_FLAG(...)
Q_PROPERTY(...)
KXMLGUIFactory, together with KXMLGUIClient objects, can be used to create a GUI of container widgets...
Floatable toolbar with auto resize.
Definition: ktoolbar.h:60
typedef WindowFlags
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu May 13 2021 22:50:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.