KXmlGui

ktoolbar.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Reginald Stadlbauer <[email protected]>
4  SPDX-FileCopyrightText: 1997, 1998 Stephan Kulow <[email protected]>
5  SPDX-FileCopyrightText: 1997, 1998 Sven Radej <[email protected]>
6  SPDX-FileCopyrightText: 1997, 1998 Mark Donohoe <[email protected]>
7  SPDX-FileCopyrightText: 1997, 1998 Matthias Ettrich <[email protected]>
8  SPDX-FileCopyrightText: 1999, 2000 Kurt Granroth <[email protected]>
9  SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <[email protected]>
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 
22 class QDomElement;
23 
24 class KConfigGroup;
25 class KConfig;
26 class KMainWindow;
27 class 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  * @note If you can't depend on KXmlGui but you want to integrate with KDE, you can use QToolBar with:
55  * Set ToolButtonStyle to Qt::ToolButtonFollowStyle, this will make QToolBar use the settings for "Main Toolbar"
56  * Additionally set QToolBar::setProperty("otherToolbar", true) to use settings for "Other toolbars"
57  * Settings from "Other toolbars" will only work on widget styles derived from KStyle
58  * @author Reginald Stadlbauer <[email protected]>, Stephan Kulow <[email protected]>, Sven Radej <[email protected]>, Hamish Rodda <[email protected]>.
59  */
60 class KXMLGUI_EXPORT KToolBar : public QToolBar
61 {
62  Q_OBJECT
63 
64 public:
65  /**
66  * Constructor.
67  *
68  * This constructor takes care of adding the toolbar to the mainwindow,
69  * if @p parent is a QMainWindow.
70  *
71  * Normally KDE applications do not call this directly, they either
72  * call KMainWindow::toolBar(), or they use XML-GUI and specify
73  * toolbars using XML.
74  *
75  * @param parent The standard toolbar parent (usually a KMainWindow)
76  * @param isMainToolBar True for the "main toolbar", false for other toolbars. Different settings apply.
77  * @param readConfig whether to apply the configuration (global and application-specific)
78  */
79  explicit KToolBar(QWidget *parent, bool isMainToolBar = false, bool readConfig = true);
80  // KDE5: remove. The one below is preferred so that all debug output from init() shows the right objectName already,
81  // and so that isMainToolBar() and iconSizeDefault() return correct values during loading too.
82 
83  /**
84  * Constructor.
85  *
86  * This constructor takes care of adding the toolbar to the mainwindow,
87  * if @p parent is a QMainWindow.
88  *
89  * Normally KDE applications do not call this directly, they either
90  * call KMainWindow::toolBar(), or they use XML-GUI and specify
91  * toolbars using XML.
92  *
93  * @param objectName The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position,
94  * and so that KToolBar can find out if it's the main toolbar.
95  * @param parent The standard toolbar parent (usually a KMainWindow)
96  * @param readConfig whether to apply the configuration (global and application-specific)
97  */
98  explicit KToolBar(const QString &objectName, QWidget *parent, bool readConfig = true);
99 
100  /**
101  * Alternate constructor with additional arguments, e.g. to choose in which area
102  * the toolbar should be auto-added. This is rarely used in KDE. When using XMLGUI
103  * you can specify this as an xml attribute instead.
104  *
105  * @param objectName The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position
106  * @param parentWindow The window that should be the parent of this toolbar
107  * @param area The position of the toolbar. Usually Qt::TopToolBarArea.
108  * @param newLine If true, start a new line in the dock for this toolbar.
109  * @param isMainToolBar True for the "main toolbar", false for other toolbars. Different settings apply.
110  * @param readConfig whether to apply the configuration (global and application-specific)
111  */
112  KToolBar(const QString &objectName,
113  QMainWindow *parentWindow,
114  Qt::ToolBarArea area,
115  bool newLine = false,
116  bool isMainToolBar = false,
117  bool readConfig = true); // KDE5: remove, I don't think anyone is using this.
118 
119  /**
120  * Destroys the toolbar.
121  */
122  ~KToolBar() override;
123 
124  /**
125  * Returns the main window that this toolbar is docked with.
126  */
127  KMainWindow *mainWindow() const;
128 
129  /**
130  * Convenience function to set icon size
131  */
132  void setIconDimensions(int size);
133 
134  /**
135  * Returns the default size for this type of toolbar.
136  *
137  * @return the default size for this type of toolbar.
138  */
139  int iconSizeDefault() const; // KDE5: hide from public API. Doesn't make sense to export this, and it isn't used.
140 
141 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
142  /**
143  * This allows you to enable or disable the context menu.
144  *
145  * @param enable If false, then the context menu will be disabled
146  * @deprecated Since 5.0, use setContextMenuPolicy()
147  */
148  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::setContextMenuPolicy(Qt::ContextMenuPolicy)")
149  void setContextMenuEnabled(bool enable = true);
150 #endif
151 
152 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
153  /**
154  * Returns the context menu enabled flag
155  * @return true if the context menu is disabled
156  * @deprecated Since 5.0, use contextMenuPolicy()
157  */
158  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::contextMenuPolicy()")
159  bool contextMenuEnabled() const;
160 #endif
161 
162  /**
163  * Save the toolbar settings to group @p cg.
164  */
165  void saveSettings(KConfigGroup &cg);
166 
167  /**
168  * Read the toolbar settings from group @p cg
169  * and apply them.
170  */
171  void applySettings(const KConfigGroup &cg);
172 
173 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
174  /**
175  * Sets the XML gui client.
176  * @deprecated Since 5.0, use addXMLGUIClient()
177  */
178  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use KToolBar::addXMLGUIClient(KXMLGUIClient *)")
179  void setXMLGUIClient(KXMLGUIClient *client);
180 #endif
181 
182  /**
183  * Adds an XML gui client that uses this toolbar
184  * @since 4.8.1
185  */
186  void addXMLGUIClient(KXMLGUIClient *client);
187 
188  /**
189  * Removes an XML gui client that uses this toolbar
190  * @since 4.8.5
191  */
192  void removeXMLGUIClient(KXMLGUIClient *client);
193 
194  /**
195  * Load state from an XML @param element, called by KXMLGUIBuilder.
196  */
197  void loadState(const QDomElement &element);
198 
199  /**
200  * Save state into an XML @param element, called by KXMLGUIBuilder.
201  */
202  void saveState(QDomElement &element) const;
203 
204  /**
205  * Reimplemented to support context menu activation on disabled tool buttons.
206  */
207  bool eventFilter(QObject *watched, QEvent *event) override;
208 
209  /**
210  * Returns whether the toolbars are currently editable (drag & drop of actions).
211  */
212  static bool toolBarsEditable();
213 
214  /**
215  * Enable or disable toolbar editing via drag & drop of actions. This is
216  * called by KEditToolBar and should generally be set to disabled whenever
217  * KEditToolBar is not active.
218  */
219  static void setToolBarsEditable(bool editable);
220 
221  /**
222  * Returns whether the toolbars are locked (i.e., moving of the toobars disallowed).
223  */
224  static bool toolBarsLocked();
225 
226  /**
227  * Allows you to lock and unlock all toolbars (i.e., disallow/allow moving of the toobars).
228  */
229  static void setToolBarsLocked(bool locked);
230 
231  /**
232  * Emits a D-Bus signal to tell all toolbars in all applications, that the user settings have
233  * changed.
234  * @since 5.0
235  */
236  static void emitToolbarStyleChanged();
237 
238 protected Q_SLOTS:
239  virtual void slotMovableChanged(bool movable);
240 
241 protected:
242  void contextMenuEvent(QContextMenuEvent *) override;
243  void actionEvent(QActionEvent *) override;
244 
245  // Draggable toolbar configuration
246  void dragEnterEvent(QDragEnterEvent *) override;
247  void dragMoveEvent(QDragMoveEvent *) override;
248  void dragLeaveEvent(QDragLeaveEvent *) override;
249  void dropEvent(QDropEvent *) override;
250  void mousePressEvent(QMouseEvent *) override;
251  void mouseMoveEvent(QMouseEvent *) override;
252  void mouseReleaseEvent(QMouseEvent *) override;
253 
254 private:
255  friend class KToolBarPrivate;
256  std::unique_ptr<class KToolBarPrivate> const d;
257 
258  Q_PRIVATE_SLOT(d, void slotAppearanceChanged())
259  Q_PRIVATE_SLOT(d, void slotContextRight())
260  Q_PRIVATE_SLOT(d, void slotContextTextRight())
261 };
262 
263 #endif
virtual void dropEvent(QDropEvent *event)
A KXMLGUIClient can be used with KXMLGUIFactory to create a GUI from actions and an XML document...
Definition: kxmlguiclient.h:39
virtual void dragLeaveEvent(QDragLeaveEvent *event)
virtual void dragEnterEvent(QDragEnterEvent *event)
virtual void dragMoveEvent(QDragMoveEvent *event)
virtual void mouseReleaseEvent(QMouseEvent *event)
ToolBarArea
virtual void contextMenuEvent(QContextMenuEvent *event)
virtual void mousePressEvent(QMouseEvent *event)
Top level main window.
Definition: kmainwindow.h:92
virtual void mouseMoveEvent(QMouseEvent *event)
virtual bool eventFilter(QObject *watched, QEvent *event)
Floatable toolbar with auto resize.
Definition: ktoolbar.h:60
virtual void actionEvent(QActionEvent *event) override
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 22:54:06 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.