1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Reginald Stadlbauer <reggie@kde.org>
4 SPDX-FileCopyrightText: 1997, 1998 Stephan Kulow <coolo@kde.org>
5 SPDX-FileCopyrightText: 1997, 1998 Sven Radej <radej@kde.org>
6 SPDX-FileCopyrightText: 1997, 1998 Mark Donohoe <donohoe@kde.org>
7 SPDX-FileCopyrightText: 1997, 1998 Matthias Ettrich <ettrich@kde.org>
8 SPDX-FileCopyrightText: 1999, 2000 Kurt Granroth <granroth@kde.org>
9 SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org>
10
11 SPDX-License-Identifier: LGPL-2.0-only
12*/
13
14#ifndef KTOOLBAR_H
15#define KTOOLBAR_H
16
17#include <kxmlgui_export.h>
18
19#include <QToolBar>
20#include <memory>
21
22class QDomElement;
23
24class KConfigGroup;
25class KConfig;
26class KMainWindow;
27class KXMLGUIClient;
28
29/*!
30 * \class KToolBar
31 * \inmodule KXmlGui
32 *
33 * \brief Floatable toolbar with auto resize.
34 *
35 * A KDE-style toolbar.
36 *
37 * KToolBar can be used as a standalone widget, but KMainWindow
38 * provides easy factories and management of one or more toolbars.
39 *
40 * KToolBar uses a global config group to load toolbar settings on
41 * construction. It will reread this config group on a
42 * KApplication::appearanceChanged() signal.
43 *
44 * KToolBar respects Kiosk settings (see the KAuthorized namespace in the
45 * KConfig framework). In particular, system administrators can prevent users
46 * from moving toolbars with the "movable_toolbars" action, and from showing or
47 * hiding toolbars with the "options_show_toolbar" action. For example, to
48 * disable both, add the following the application or global configuration:
49 * \badcode
50 * [KDE Action Restrictions][$i]
51 * movable_toolbars=false
52 * options_show_toolbar=false
53 * \endcode
54 *
55 * If you can't depend on KXmlGui but still want to integrate better with KDE,
56 * you can use QToolBar and:
57 * \list
58 * \li Set ToolButtonStyle to Qt::ToolButtonFollowStyle,
59 * this will make QToolBar use the settings for "Main Toolbar".
60 * \li Additionally set QToolBar::setProperty("otherToolbar", true)
61 * to use settings for "Other toolbars"; settings from "Other toolbars"
62 * will only work on widget styles derived from KStyle.
63 * \endlist
64 */
65class KXMLGUI_EXPORT KToolBar : public QToolBar
66{
67 Q_OBJECT
68
69public:
70 /*!
71 * \brief Constructor.
72 *
73 * This constructor takes care of adding the toolbar to the mainwindow,
74 * if \a parent is a QMainWindow.
75 *
76 * Normally KDE applications do not call this directly, they either
77 * call KMainWindow::toolBar(), or they use XML-GUI and specify
78 * toolbars using XML.
79 *
80 * \a parent The standard toolbar parent (usually a KMainWindow).
81 *
82 * \a isMainToolBar True for the "main toolbar", false for other toolbars.
83 * Different settings apply.
84 *
85 * \a readConfig Whether to apply the configuration (global and application-specific)
86 */
87 explicit KToolBar(QWidget *parent, bool isMainToolBar = false, bool readConfig = true);
88 // KDE5: remove. The one below is preferred so that all debug output from init() shows the right objectName already,
89 // and so that isMainToolBar() and iconSizeDefault() return correct values during loading too.
90
91 /*!
92 * \brief Constructor.
93 *
94 * This constructor takes care of adding the toolbar to the mainwindow,
95 * if \a parent is a QMainWindow.
96 *
97 * Normally KDE applications do not call this directly, they either
98 * call KMainWindow::toolBar(), or they use XML-GUI and specify
99 * toolbars using XML.
100 *
101 * \a objectName The QObject name of this toolbar, required
102 * so that QMainWindow can save and load the toolbar position,
103 * and so that KToolBar can find out if it's the main toolbar.
104 *
105 * \a parent The standard toolbar parent (usually a KMainWindow).
106 *
107 * \a readConfig Whether to apply the configuration (global and application-specific).
108 */
109 explicit KToolBar(const QString &objectName, QWidget *parent, bool readConfig = true);
110
111 /*!
112 * \brief Alternate constructor with additional arguments,
113 * e.g. to choose in which area the toolbar should be auto-added.
114 * This is rarely used in KDE. When using XMLGUI
115 * you can specify this as an xml attribute instead.
116 *
117 * \a objectName The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position.
118 *
119 * \a parentWindow The window that should be the parent of this toolbar.
120 *
121 * \a area The position of the toolbar. Usually Qt::TopToolBarArea.
122 *
123 * \a newLine If true, start a new line in the dock for this toolbar.
124 *
125 * \a isMainToolBar True for the "main toolbar", false for other toolbars.
126 * Different settings apply.
127 * \a readConfig whether to apply the configuration (global and application-specific)
128 */
129 KToolBar(const QString &objectName,
130 QMainWindow *parentWindow,
131 Qt::ToolBarArea area,
132 bool newLine = false,
133 bool isMainToolBar = false,
134 bool readConfig = true); // KDE5: remove, I don't think anyone is using this.
135
136 /*!
137 * \brief Destroys the toolbar.
138 */
139 ~KToolBar() override;
140
141 /*!
142 * \brief Returns the main window that this toolbar is docked with.
143 */
144 KMainWindow *mainWindow() const;
145
146 /*!
147 * \brief Convenience function to set icon \a size.
148 */
149 void setIconDimensions(int size);
150
151 /*!
152 * \brief Returns the default size for this type of toolbar.
153 */
154 int iconSizeDefault() const; // KDE5: hide from public API. Doesn't make sense to export this, and it isn't used.
155
156 /*!
157 * \brief Save the toolbar settings to group \a cg.
158 */
159 void saveSettings(KConfigGroup &cg);
160
161 /*!
162 * \brief Read the toolbar settings from group \a cg and apply them.
163 */
164 void applySettings(const KConfigGroup &cg);
165
166 /*!
167 * \brief Adds an XML gui \a client that uses this toolbar.
168 * \since 4.8.1
169 */
170 void addXMLGUIClient(KXMLGUIClient *client);
171
172 /*!
173 * \brief Removes an XML gui \a client that uses this toolbar.
174 * \since 4.8.5
175 */
176 void removeXMLGUIClient(KXMLGUIClient *client);
177
178 /*!
179 * \brief Load state from an XML \a element, called by KXMLGUIBuilder.
180 */
181 void loadState(const QDomElement &element);
182
183 /*!
184 * \brief Save state into an XML \a element, called by KXMLGUIBuilder.
185 */
186 void saveState(QDomElement &element) const;
187
188 /*!
189 * \brief Filters then returns the specified \a event
190 * for a given \a watched object.
191 *
192 * Reimplemented to support context menu activation on disabled tool buttons.
193 */
194 bool eventFilter(QObject *watched, QEvent *event) override;
195
196 /*!
197 * \brief Returns whether the toolbars are currently editable (drag & drop of actions).
198 */
199 static bool toolBarsEditable();
200
201 /*!
202 * \brief Makes all toolbars \a editable via drag & drop of actions.
203 *
204 * This is called by KEditToolBar and should generally be set to disabled
205 * whenever KEditToolBar is not active.
206 */
207 static void setToolBarsEditable(bool editable);
208
209 /*!
210 * \brief Returns whether the toolbars are locked
211 * (that is, disallow moving of the toolbars).
212 */
213 static bool toolBarsLocked();
214
215 /*!
216 * \brief Makes all toolbars \a locked
217 * (that is, disallow/allow moving of the toolbars).
218 */
219 static void setToolBarsLocked(bool locked);
220
221 /*!
222 * \brief Emits a D-Bus signal to tell all toolbars in all applications
223 * that the user settings have changed.
224 * \since 5.0
225 */
226 static void emitToolbarStyleChanged();
227
228protected Q_SLOTS:
229 virtual void slotMovableChanged(bool movable);
230
231protected:
232 void contextMenuEvent(QContextMenuEvent *) override;
233 void actionEvent(QActionEvent *) override;
234
235 // Draggable toolbar configuration
236 void dragEnterEvent(QDragEnterEvent *) override;
237 void dragMoveEvent(QDragMoveEvent *) override;
238 void dragLeaveEvent(QDragLeaveEvent *) override;
239 void dropEvent(QDropEvent *) override;
240 void mousePressEvent(QMouseEvent *) override;
241 void mouseMoveEvent(QMouseEvent *) override;
242 void mouseReleaseEvent(QMouseEvent *) override;
243
244private:
245 friend class KToolBarPrivate;
246 std::unique_ptr<class KToolBarPrivate> const d;
247
248 Q_PRIVATE_SLOT(d, void slotAppearanceChanged())
249 Q_PRIVATE_SLOT(d, void slotContextRight())
250 Q_PRIVATE_SLOT(d, void slotContextTextRight())
251};
252
253#endif
254

source code of kxmlgui/src/ktoolbar.h