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 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 <granroth@kde.org>
60 * @maintainer David Faure <faure@kde.org>
61 */
62class KXMLGUI_EXPORT KEditToolBar : public QDialog
63{
64 Q_OBJECT
65public:
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 * @since 6.0
137 */
138 static void setGlobalDefaultToolBar(const QString &toolBarName);
139
140Q_SIGNALS:
141 /**
142 * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset.
143 * Connect to it, to plug action lists and to call applyMainWindowSettings
144 * (see sample code in this class's documentation)
145 */
146 void newToolBarConfig();
147
148protected:
149 void showEvent(QShowEvent *event) override;
150 void hideEvent(QHideEvent *event) override;
151
152private:
153 friend class KEditToolBarPrivate;
154 std::unique_ptr<KEditToolBarPrivate> const d;
155
156 Q_DISABLE_COPY(KEditToolBar)
157};
158
159#endif // _KEDITTOOLBAR_H
160

source code of kxmlgui/src/kedittoolbar.h