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

source code of kxmlgui/src/ktoolbar.h