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

source code of kxmlgui/src/kedittoolbar.h