KXmlGui

kedittoolbar.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Kurt Granroth <[email protected]>
4  SPDX-FileCopyrightText: 2006 Hamish Rodda <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef KEDITTOOLBAR_H
10 #define KEDITTOOLBAR_H
11 
12 #include <QDialog>
13 #include <memory>
14 
15 #include <kxmlgui_export.h>
16 
17 class KActionCollection;
18 
19 class KEditToolBarPrivate;
20 class KXMLGUIFactory;
21 /**
22  * @class KEditToolBar kedittoolbar.h KEditToolBar
23  *
24  * @short A dialog used to customize or configure toolbars.
25  *
26  * This dialog only works if your application uses the XML UI
27  * framework for creating menus and toolbars. It depends on the XML
28  * files to describe the toolbar layouts and it requires the actions
29  * to determine which buttons are active.
30  *
31  * Typically you do not need to use it directly as KXmlGuiWindow::setupGUI
32  * takes care of it.
33  *
34  * If you use KXMLGUIClient::plugActionList() you need to overload
35  * KXmlGuiWindow::saveNewToolbarConfig() to plug actions again:
36  *
37  * \code
38  * void MyClass::saveNewToolbarConfig()
39  * {
40  * KXmlGuiWindow::saveNewToolbarConfig();
41  * plugActionList( "list1", list1Actions );
42  * plugActionList( "list2", list2Actions );
43  * }
44  * \endcode
45  *
46  * When created, KEditToolBar takes a KXMLGUIFactory object, and uses it to
47  * find all of the action collections and XML files (there is one of each for the
48  * mainwindow, but there could be more, when adding other XMLGUI clients like
49  * KParts or plugins). The editor aims to be semi-intelligent about where it
50  * assigns any modifications. In other words, it will not write out part specific
51  * changes to your application's main XML file.
52  *
53  * KXmlGuiWindow and KParts::MainWindow take care of creating KEditToolBar correctly
54  * and connecting to its newToolBarConfig slot, but if you really really want to do it
55  * yourself, see the KXmlGuiWindow::configureToolbars() and KXmlGuiWindow::saveNewToolbarConfig() code.
56  *
57  * \image html kedittoolbar.png "KEditToolBar (example: usage in KWrite)"
58  *
59  * @author Kurt Granroth <[email protected]>
60  * @maintainer David Faure <[email protected]>
61  */
62 class KXMLGUI_EXPORT KEditToolBar : public QDialog
63 {
64  Q_OBJECT
65 public:
66  /**
67  * Old constructor for apps that do not use components.
68  * This constructor is somewhat deprecated, since it doesn't work
69  * with any KXMLGuiClient being added to the mainwindow.
70  * You really want to use the other constructor.
71  *
72  * You @em must pass along your collection of actions (some of which appear in your toolbars).
73  *
74  * @param collection The collection of actions to work on.
75  * @param parent The parent of the dialog.
76  */
77  explicit KEditToolBar(KActionCollection *collection, QWidget *parent = nullptr);
78 
79  /**
80  * Main constructor.
81  *
82  * The main parameter, @p factory, is a pointer to the
83  * XML GUI factory object for your application. It contains a list
84  * of all of the GUI clients (along with the action collections and
85  * xml files) and the toolbar editor uses that.
86  *
87  * Use this like so:
88  * \code
89  * KEditToolBar edit(factory());
90  * if (edit.exec())
91  * ...
92  * \endcode
93  *
94  * @param factory Your application's factory object
95  * @param parent The usual parent for the dialog.
96  */
97  explicit KEditToolBar(KXMLGUIFactory *factory, QWidget *parent = nullptr);
98 
99  /// destructor
100  ~KEditToolBar() override;
101 
102  /**
103  * Sets the default toolbar that will be selected when the dialog is shown.
104  * If not set, or QString() is passed in, the global default tool bar name
105  * will be used.
106  * @param toolBarName the name of the tool bar
107  * @see setGlobalDefaultToolBar
108  */
109  void setDefaultToolBar(const QString &toolBarName);
110 
111  /**
112  * The name (absolute or relative) of your application's UI resource file
113  * is assumed to be share/apps/appname/appnameui.rc though this can be
114  * overridden by calling this method.
115  *
116  * The global parameter controls whether or not the
117  * global resource file is used. If this is @c true, then you may
118  * edit all of the actions in your toolbars -- global ones and
119  * local one. If it is @c false, then you may edit only your
120  * application's entries. The only time you should set this to
121  * false is if your application does not use the global resource
122  * file at all (very rare).
123  *
124  * @param file The application's local resource file.
125  * @param global If @c true, then the global resource file will also
126  * be parsed.
127  */
128  void setResourceFile(const QString &file, bool global = true);
129 
130  /**
131  * Sets the default toolbar which will be auto-selected for all
132  * KEditToolBar instances. Can be overridden on a per-dialog basis
133  * by calling setDefaultToolBar( const QString& ) on the dialog.
134  *
135  * @param toolBarName the name of the tool bar
136  */
137  static void setGlobalDefaultToolBar(const char *toolBarName); // TODO should be const QString&
138 
139 Q_SIGNALS:
140  /**
141  * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset.
142  * Connect to it, to plug action lists and to call applyMainWindowSettings
143  * (see sample code in this class's documentation)
144  */
145  void newToolBarConfig();
146 
147 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(4, 0)
148  /**
149  * @deprecated Since 4.0, use newToolBarConfig()
150  */
151  KXMLGUI_DEPRECATED_VERSION(4, 0, "Use KEditToolBar::newToolBarConfig()")
152  QT_MOC_COMPAT void newToolbarConfig();
153 #endif
154 
155 protected:
156  void showEvent(QShowEvent *event) override;
157  void hideEvent(QHideEvent *event) override;
158 
159 private:
160  friend class KEditToolBarPrivate;
161  std::unique_ptr<KEditToolBarPrivate> const d;
162 
164 };
165 
166 #endif // _KEDITTOOLBAR_H
A container for a set of QAction objects.
virtual void hideEvent(QHideEvent *event)
A dialog used to customize or configure toolbars.
Definition: kedittoolbar.h:62
KXMLGUIFactory, together with KXMLGUIClient objects, can be used to create a GUI of container widgets...
Q_DISABLE_COPY(Class)
virtual void showEvent(QShowEvent *event) override
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Jun 20 2021 22:50:34 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.