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, QMainWindow *parentWindow, Qt::ToolBarArea area, bool newLine = false,
113  bool isMainToolBar = false, bool readConfig = true); // KDE5: remove, I don't think anyone is using this.
114 
115  /**
116  * Destroys the toolbar.
117  */
118  virtual ~KToolBar();
119 
120  /**
121  * Returns the main window that this toolbar is docked with.
122  */
123  KMainWindow *mainWindow() const;
124 
125  /**
126  * Convenience function to set icon size
127  */
128  void setIconDimensions(int size);
129 
130  /**
131  * Returns the default size for this type of toolbar.
132  *
133  * @return the default size for this type of toolbar.
134  */
135  int iconSizeDefault() const; // KDE5: hide from public API. Doesn't make sense to export this, and it isn't used.
136 
137 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
138  /**
139  * This allows you to enable or disable the context menu.
140  *
141  * @param enable If false, then the context menu will be disabled
142  * @deprecated Since 5.0, use setContextMenuPolicy()
143  */
144  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::setContextMenuPolicy(Qt::ContextMenuPolicy)")
145  void setContextMenuEnabled(bool enable = true);
146 #endif
147 
148 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
149  /**
150  * Returns the context menu enabled flag
151  * @return true if the context menu is disabled
152  * @deprecated Since 5.0, use contextMenuPolicy()
153  */
154  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::contextMenuPolicy()")
155  bool contextMenuEnabled() const;
156 #endif
157 
158  /**
159  * Save the toolbar settings to group @p cg.
160  */
161  void saveSettings(KConfigGroup &cg);
162 
163  /**
164  * Read the toolbar settings from group @p cg
165  * and apply them.
166  */
167  void applySettings(const KConfigGroup &cg);
168 
169 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
170  /**
171  * Sets the XML gui client.
172  * @deprecated Since 5.0, use addXMLGUIClient()
173  */
174  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use KToolBar::addXMLGUIClient(KXMLGUIClient *)")
175  void setXMLGUIClient(KXMLGUIClient *client);
176 #endif
177 
178  /**
179  * Adds an XML gui client that uses this toolbar
180  * @since 4.8.1
181  */
182  void addXMLGUIClient(KXMLGUIClient *client);
183 
184  /**
185  * Removes an XML gui client that uses this toolbar
186  * @since 4.8.5
187  */
188  void removeXMLGUIClient(KXMLGUIClient *client);
189 
190  /**
191  * Load state from an XML @param element, called by KXMLGUIBuilder.
192  */
193  void loadState(const QDomElement &element);
194 
195  /**
196  * Save state into an XML @param element, called by KXMLGUIBuilder.
197  */
198  void saveState(QDomElement &element) const;
199 
200  /**
201  * Reimplemented to support context menu activation on disabled tool buttons.
202  */
203  bool eventFilter(QObject *watched, QEvent *event) override;
204 
205  /**
206  * Returns whether the toolbars are currently editable (drag & drop of actions).
207  */
208  static bool toolBarsEditable();
209 
210  /**
211  * Enable or disable toolbar editing via drag & drop of actions. This is
212  * called by KEditToolBar and should generally be set to disabled whenever
213  * KEditToolBar is not active.
214  */
215  static void setToolBarsEditable(bool editable);
216 
217  /**
218  * Returns whether the toolbars are locked (i.e., moving of the toobars disallowed).
219  */
220  static bool toolBarsLocked();
221 
222  /**
223  * Allows you to lock and unlock all toolbars (i.e., disallow/allow moving of the toobars).
224  */
225  static void setToolBarsLocked(bool locked);
226 
227  /**
228  * Emits a D-Bus signal to tell all toolbars in all applications, that the user settings have
229  * changed.
230  * @since 5.0
231  */
232  static void emitToolbarStyleChanged();
233 
234 protected Q_SLOTS:
235  virtual void slotMovableChanged(bool movable);
236 
237 protected:
238  void contextMenuEvent(QContextMenuEvent *) override;
239  void actionEvent(QActionEvent *) override;
240 
241  // Draggable toolbar configuration
242  void dragEnterEvent(QDragEnterEvent *) override;
243  void dragMoveEvent(QDragMoveEvent *) override;
244  void dragLeaveEvent(QDragLeaveEvent *) override;
245  void dropEvent(QDropEvent *) override;
246  void mousePressEvent(QMouseEvent *) override;
247  void mouseMoveEvent(QMouseEvent *) override;
248  void mouseReleaseEvent(QMouseEvent *) override;
249 
250 private:
251  friend class KToolBarPrivate;
252  std::unique_ptr<class KToolBarPrivate> const d;
253 
254  Q_PRIVATE_SLOT(d, void slotAppearanceChanged())
255  Q_PRIVATE_SLOT(d, void slotContextAboutToShow())
256  Q_PRIVATE_SLOT(d, void slotContextAboutToHide())
257  Q_PRIVATE_SLOT(d, void slotContextLeft())
258  Q_PRIVATE_SLOT(d, void slotContextRight())
259  Q_PRIVATE_SLOT(d, void slotContextShowText())
260  Q_PRIVATE_SLOT(d, void slotContextTop())
261  Q_PRIVATE_SLOT(d, void slotContextBottom())
262  Q_PRIVATE_SLOT(d, void slotContextIcons())
263  Q_PRIVATE_SLOT(d, void slotContextText())
264  Q_PRIVATE_SLOT(d, void slotContextTextRight())
265  Q_PRIVATE_SLOT(d, void slotContextTextUnder())
266  Q_PRIVATE_SLOT(d, void slotContextIconSize())
267  Q_PRIVATE_SLOT(d, void slotLockToolBars(bool))
268 };
269 
270 #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:91
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 Mon Mar 8 2021 22:50:30 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.