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])
42  * @author Stephan Kulow ([email protected])
43  * @author Matthias Ettrich ([email protected])
44  * @author Chris Schlaeger ([email protected])
45  * @author Sven Radej ([email protected])
46  * Maintained by Sven Radej ([email protected])
47  */
48 
49 class KXMLGUI_EXPORT KXmlGuiWindow : public KMainWindow, public KXMLGUIBuilder, virtual public KXMLGUIClient
50 {
51  Q_OBJECT
52  Q_PROPERTY(bool hasMenuBar READ hasMenuBar)
53  Q_PROPERTY(bool autoSaveSettings READ autoSaveSettings)
54  Q_PROPERTY(QString autoSaveGroup READ autoSaveGroup)
55  Q_PROPERTY(bool standardToolBarMenuEnabled READ isStandardToolBarMenuEnabled WRITE setStandardToolBarMenuEnabled)
56 
57 public:
58  /**
59  * Construct a main window.
60  *
61  * @param parent The widget parent. This is usually 0 but it may also be the window
62  * group leader. In that case, the KXmlGuiWindow becomes sort of a
63  * secondary window.
64  *
65  * @param f Specify the window flags. The default is none.
66  *
67  * Note that a KXmlGuiWindow per-default is created with the
68  * Qt::WA_DeleteOnClose attribute set, i.e. it is automatically destroyed
69  * when the window is closed. If you do not want this behavior, call
70  * \code
71  * window->setAttribute(Qt::WA_DeleteOnClose, false);
72  * \endcode
73  *
74  * KXmlGuiWindows must be created on the heap with 'new', like:
75  * \code
76  * KXmlGuiWindow *kmw = new KXmlGuiWindow(...);
77  * kmw->setObjectName(...);
78  * \endcode
79  *
80  * IMPORTANT: For session management and window management to work
81  * properly, all main windows in the application should have a
82  * different name. If you don't do it, the base class KMainWindow will create
83  * a unique name, but it's recommended to explicitly pass a window name that will
84  * also describe the type of the window. If there can be several windows of the same
85  * type, append '#' (hash) to the name, and KMainWindow will replace it with numbers to make
86  * the names unique. For example, for a mail client which has one main window showing
87  * the mails and folders, and which can also have one or more windows for composing
88  * mails, the name for the folders window should be e.g. "mainwindow" and
89  * for the composer windows "composer#".
90  *
91  */
92  explicit KXmlGuiWindow(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags());
93 
94  /**
95  * \brief Destructor.
96  *
97  * Will also destroy the toolbars, and menubar if
98  * needed.
99  */
100  ~KXmlGuiWindow() override;
101 
102  /**
103  * Enables the build of a standard help menu when calling @ref createGUI()
104  * or @ref setupGUI().
105  *
106  * The default behavior is to create a help menu, you must call this
107  * function with @c false to disable that.
108  */
109  void setHelpMenuEnabled(bool showHelpMenu = true);
110 
111  /**
112  * Returns @c true if the help menu is enabled, @c false otherwise.
113  */
114  bool isHelpMenuEnabled() const;
115 
116  virtual KXMLGUIFactory *guiFactory();
117 
118  /**
119  * Creates a GUI based on a local XML file.
120  *
121  * Typically, i.e. in a regular application, you should use @ref setupGUI()
122  * instead, since it runs some extra code, like setting up the toolbar/shortcut
123  * edit actions ...etc.
124  *
125  * If @p xmlfile is an empty string, this method will try to construct
126  * a local XML filename like appnameui.rc where 'appname' is your app's
127  * name. Typically that app name is what @ref KXMLGUIClient::componentName()
128  * returns. If that file does not exist, then the XML UI code will only use
129  * the global (standard) XML file for the layout purposes.
130  *
131  * @param xmlfile the path (relative or absolute) to the local xmlfile
132  */
133  void createGUI(const QString &xmlfile = QString());
134 
135  /**
136  * Sets whether @ref KMainWindow should provide a menu that allows
137  * showing/hiding the available toolbars (using KToggleToolBarAction).
138  *
139  * If there is only one toolbar configured, a simple 'Show <toolbar name>'
140  * menu item is shown; if more than one toolbar are configured, a "Shown Toolbars"
141  * menu is created instead, with 'Show <toolbar1 name>', 'Show <toolbar2 name>'
142  * ...etc sub-menu actions.
143  *
144  * The menu / menu item is implemented using xmlgui. It will be inserted in your
145  * menu structure in the 'Settings' menu.
146  *
147  * If your application uses a non-standard xmlgui resource file then you can
148  * specify the exact position of the menu / menu item by adding a
149  * &lt;Merge name="StandardToolBarMenuHandler" /&gt;
150  * line to the settings menu section of your resource file ( usually appname.rc ).
151  *
152  * @note You should enable this feature before calling createGUI() ( or similar ).
153  */
154  void setStandardToolBarMenuEnabled(bool enable);
155 
156  /**
157  * Returns @c true if the toolbar menu is enabled, @c false otherwise.
158  */
159  bool isStandardToolBarMenuEnabled() const;
160 
161  /**
162  * Sets whether KMainWindow should provide a menu that allows showing/hiding
163  * of the statusbar (using KStandardAction::showStatusbar()). Note that calling
164  * this method will create a statusbar if one doesn't already exist.
165  *
166  * The menu / menu item is implemented using xmlgui. It will be inserted
167  * in your menu structure in the 'Settings' menu.
168  *
169  * @note You should enable this feature before calling createGUI() (or similar).
170  *
171  * If an application maintains the action on its own (i.e. never calls
172  * this function) a connection needs to be made to let KMainWindow
173  * know when that status (hidden/shown) of the statusbar has changed.
174  * For example:
175  * @code
176  * connect(action, &QAction::triggered,
177  * kmainwindow, &KMainWindow::setSettingsDirty);
178  * @endcode
179  * Otherwise the status (hidden/show) of the statusbar might not be saved
180  * by KMainWindow.
181  */
182  void createStandardStatusBarAction();
183 
184  /**
185  * @see setupGUI()
186  * @see StandardWindowOptions
187  */
189  /**
190  * Adds action(s) to show/hide the toolbar(s) and adds a menu
191  * action to configure the toolbar(s).
192  *
193  * @see setStandardToolBarMenuEnabled
194  */
195  ToolBar = 1,
196 
197  /**
198  * Adds an action to open the configure keyboard shortcuts dialog.
199  */
200  Keys = 2,
201 
202  /**
203  * Adds action to show/hide the statusbar. Note that setting this
204  * value will create a statusbar if one doesn't already exist.
205  *
206  * @see createStandardStatusBarAction
207  */
208  StatusBar = 4,
209 
210  /**
211  * Auto-saves (and loads) the toolbar/menubar/statusbar settings and
212  * window size using the default name.
213  *
214  * Typically you want to let the default window size be determined by
215  * the widgets size hints. Make sure that setupGUI() is called after
216  * all the widgets are created (including setCentralWidget) so that the
217  * default size will be correct.
218  *
219  * @see setAutoSaveSettings
220  */
221  Save = 8,
222 
223  /**
224  * calls createGUI() once ToolBar, Keys and Statusbar have been
225  * taken care of.
226  *
227  * @note When using @ref KParts::MainWindow, remove this flag from
228  * the @ref setupGUI() call, since you'll be using @c createGUI(part)
229  * instead.
230  *
231  * @code
232  * setupGUI(ToolBar | Keys | StatusBar | Save);
233  * @endcode
234  *
235  * @see createGUI
236  */
237  Create = 16,
238 
239  /**
240  * All the above option
241  * (this is the default)
242  */
243  Default = ToolBar | Keys | StatusBar | Save | Create,
244  };
245  Q_FLAG(StandardWindowOption)
246  /**
247  * Stores a combination of #StandardWindowOption values.
248  */
250 
251  /**
252  * Configures the current window and its actions in the typical KDE
253  * fashion.
254  *
255  * You can specify which window options/features are going to be set up using
256  * @p options, @see the @ref StandardWindowOption enum for more details.
257  *
258  * Typically this function replaces @ref createGUI().
259  *
260  * @warning If you are calling @ref createGUI() yourself, remember to
261  * remove the @ref StandardWindowOption::Create flag from @p options.
262  *
263  * @see @ref StandardWindowOptions
264  *
265  * @note Since this method will restore the state of the application
266  * window (toolbar, dockwindows positions ...etc), you need to have
267  * added all your actions to your toolbars ...etc before calling this
268  * method. (This note is only applicable if you are using the
269  * @c StandardWindowOption::Default or @c StandardWindowOption::Save flags).
270  *
271  * @param options an OR'ed combination of StandardWindowOption to specify
272  * which options are going to be set up for your application window, the
273  * default is @ref StandardWindowOption::Default
274  * @param xmlfile the path (relative or absolute) to the local xmlfile,
275  * if this is an empty string the code will look for a local XML file
276  * appnameui.rc, where 'appname' is the name of your app, see the note
277  * about the xmlfile argument in the @ref createGUI() docs.
278  */
279  void setupGUI(StandardWindowOptions options = Default, const QString &xmlfile = QString());
280 
281  /**
282  * This is an overloaded method.
283  *
284  * You can use @p defaultSize to override the saved window size (e.g.
285  * the window size is saved to the config file if the @ref StandardWindowOption::Save
286  * flag was set previously).
287  */
288  void setupGUI(const QSize &defaultSize, StandardWindowOptions options = Default, const QString &xmlfile = QString());
289 
290  /**
291  * Returns a pointer to the mainwindows action responsible for the toolbars menu
292  */
293  QAction *toolBarMenuAction();
294 
295  /**
296  * @internal for KToolBar
297  */
298  void setupToolbarMenuActions();
299 
300  // TODO KF6 change it to "using KXMLGUIBuilder::finalizeGUI;"
301  void finalizeGUI(KXMLGUIClient *client) override;
302 
303  /**
304  * @internal
305  */
306  void finalizeGUI(bool force);
307 
308  // reimplemented for internal reasons
309  void applyMainWindowSettings(const KConfigGroup &config) override;
310 
311  /**
312  * Enable a hud style menu which allows listing and executing actions
313  *
314  * The menu is launchable with the shortcut Alt+Ctrl+I
315  *
316  * @since 5.83
317  */
318  void setCommandBarEnabled(bool enable);
319 
320  /**
321  * @since 5.83
322  */
323  bool isCommandBarEnabled() const;
324 
325 public Q_SLOTS:
326  /**
327  * Show a standard configure toolbar dialog.
328  *
329  * This slot can be connected directly to the action to configure toolbar.
330  * This is very simple to do that by adding a single line
331  * \code
332  * KStandardAction::configureToolbars( this, SLOT( configureToolbars() ),
333  * actionCollection() );
334  * \endcode
335  */
336  virtual void configureToolbars();
337 
338  /**
339  * Apply a state change
340  *
341  * Enable and disable actions as defined in the XML rc file
342  */
343  virtual void slotStateChanged(const QString &newstate);
344 
345  /**
346  * Apply a state change
347  *
348  * Enable and disable actions as defined in the XML rc file,
349  * can "reverse" the state (disable the actions which should be
350  * enabled, and vice-versa) if specified.
351  */
352  void slotStateChanged(const QString &newstate, bool reverse);
353 
354 protected:
355  /**
356  * Reimplemented to catch QEvent::Polish in order to adjust the object name
357  * if needed, once all constructor code for the main window has run.
358  * Also reimplemented to catch when a QDockWidget is added or removed.
359  */
360  bool event(QEvent *event) override;
361 
362  /**
363  * Checks if there are actions using the same shortcut. This is called
364  * automatically from createGUI.
365  * @since 5.30
366  */
367  void checkAmbiguousShortcuts();
368 
369 protected Q_SLOTS:
370  /**
371  * Rebuilds the GUI after KEditToolBar changed the toolbar layout.
372  * @see configureToolbars()
373  */
374  virtual void saveNewToolbarConfig();
375 
376 private:
377  Q_DECLARE_PRIVATE_D(k_ptr, KXmlGuiWindow)
378 };
379 
380 Q_DECLARE_OPERATORS_FOR_FLAGS(KXmlGuiWindow::StandardWindowOptions)
381 
382 #endif
Q_PROPERTY(...)
Floatable toolbar with auto resize.
Definition: ktoolbar.h:67
typedef WindowFlags
Top level main window with predefined action layout.
Definition: kxmlguiwindow.h:49
Top level main window.
Definition: kmainwindow.h:96
Q_FLAG(...)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:10:05 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.