1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Reginald Stadlbauer (reggie@kde.org)
3 (C) 1997, 1998 Stephan Kulow (coolo@kde.org)
4 (C) 1997, 1998 Sven Radej (radej@kde.org)
5 (C) 1997, 1998 Mark Donohoe (donohoe@kde.org)
6 (C) 1997, 1998 Matthias Ettrich (ettrich@kde.org)
7 (C) 1999, 2000 Kurt Granroth (granroth@kde.org)
8 (C) 2005-2006 Hamish Rodda (rodda@kde.org)
9
10 This library is free software; you can redistribute it and/or
11 modify it under the terms of the GNU Library General Public
12 License version 2 as published by the Free Software Foundation.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Library General Public License
20 along with this library; see the file COPYING.LIB. If not, write to
21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02110-1301, USA.
23 */
24
25#ifndef KTOOLBAR_H
26#define KTOOLBAR_H
27
28#include <kdeui_export.h>
29
30#include <QtGui/QToolBar>
31
32class QDomElement;
33
34class KConfigGroup;
35class KConfig;
36class KMainWindow;
37class KXMLGUIClient;
38
39 /**
40 * @short Floatable toolbar with auto resize.
41 *
42 * A KDE-style toolbar.
43 *
44 * KToolBar can be used as a standalone widget, but KMainWindow
45 * provides easy factories and management of one or more toolbars.
46 *
47 * KToolBar uses a global config group to load toolbar settings on
48 * construction. It will reread this config group on a
49 * KApplication::appearanceChanged() signal.
50 *
51 * @author Reginald Stadlbauer <reggie@kde.org>, Stephan Kulow <coolo@kde.org>, Sven Radej <radej@kde.org>, Hamish Rodda <rodda@kde.org>.
52 */
53class KDEUI_EXPORT KToolBar : public QToolBar
54{
55 Q_OBJECT
56
57public:
58 /**
59 * Constructor.
60 *
61 * This constructor takes care of adding the toolbar to the mainwindow,
62 * if @p parent is a QMainWindow.
63 *
64 * Normally KDE applications do not call this directly, they either
65 * call KMainWindow::toolBar(name), or they use XML-GUI and specify
66 * toolbars using XML.
67 *
68 * @param parent The standard toolbar parent (usually a KMainWindow)
69 * @param isMainToolBar True for the "main toolbar", false for other toolbars. Different settings apply.
70 * @param readConfig whether to apply the configuration (global and application-specific)
71 */
72 explicit KToolBar(QWidget *parent, bool isMainToolBar = false, bool readConfig = true);
73 // KDE5: remove. The one below is preferred so that all debug output from init() shows the right objectName already,
74 // and so that isMainToolBar() and iconSizeDefault() return correct values during loading too.
75
76 /**
77 * Constructor.
78 *
79 * This constructor takes care of adding the toolbar to the mainwindow,
80 * if @p parent is a QMainWindow.
81 *
82 * Normally KDE applications do not call this directly, they either
83 * call KMainWindow::toolBar(name), or they use XML-GUI and specify
84 * toolbars using XML.
85 *
86 * @param objectName The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position,
87 * and so that KToolBar can find out if it's the main toolbar.
88 * @param parent The standard toolbar parent (usually a KMainWindow)
89 * @param readConfig whether to apply the configuration (global and application-specific)
90 */
91 explicit KToolBar(const QString& objectName, QWidget* parent, bool readConfig = true);
92
93 /**
94 * Alternate constructor with additional arguments, e.g. to choose in which area
95 * the toolbar should be auto-added. This is rarely used in KDE. When using XMLGUI
96 * you can specify this as an xml attribute instead.
97 *
98 * @param objectName The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position
99 * @param parentWindow The window that should be the parent of this toolbar
100 * @param area The position of the toolbar. Usually Qt::TopToolBarArea.
101 * @param newLine If true, start a new line in the dock for this toolbar.
102 * @param isMainToolBar True for the "main toolbar", false for other toolbars. Different settings apply.
103 * @param readConfig whether to apply the configuration (global and application-specific)
104 */
105 KToolBar(const QString& objectName, QMainWindow* parentWindow, Qt::ToolBarArea area, bool newLine = false,
106 bool isMainToolBar = false, bool readConfig = true); // KDE5: remove, I don't think anyone is using this.
107
108 /**
109 * Destroys the toolbar.
110 */
111 virtual ~KToolBar();
112
113 /**
114 * Returns the main window that this toolbar is docked with.
115 */
116 KMainWindow* mainWindow() const;
117
118 /**
119 * Convenience function to set icon size
120 */
121 void setIconDimensions( int size );
122
123 /**
124 * Returns the default size for this type of toolbar.
125 *
126 * @return the default size for this type of toolbar.
127 */
128 int iconSizeDefault() const; // KDE5: hide from public API. Doesn't make sense to export this, and it isn't used.
129
130 /**
131 * This allows you to enable or disable the context menu.
132 *
133 * @param enable If false, then the context menu will be disabled
134 * @deprecated use setContextMenuPolicy
135 */
136#ifndef KDE_NO_DEPRECATED
137 KDE_DEPRECATED void setContextMenuEnabled( bool enable = true );
138#endif
139
140 /**
141 * Returns the context menu enabled flag
142 * @return true if the context menu is disabled
143 * @deprecated use contextMenuPolicy
144 */
145#ifndef KDE_NO_DEPRECATED
146 KDE_DEPRECATED bool contextMenuEnabled() const;
147#endif
148
149 /**
150 * Save the toolbar settings to group @p configGroup in @p config.
151 */
152 void saveSettings( KConfigGroup &cg );
153
154 /**
155 * Read the toolbar settings from group @p configGroup in @p config
156 * and apply them.
157 *
158 * @param forceGlobal is deprecated. In kde3 it used to mean
159 * "force global settings, i.e. ignore @p cg", but only for visibility/position/index,
160 * not for icon size etc. Only visibility is still controlled by this.
161 */
162 void applySettings( const KConfigGroup &cg, bool forceGlobal = false );
163
164 /**
165 * Sets the XML gui client.
166 * @deprecated use addXMLGUIClient.
167 */
168#ifndef KDE_NO_DEPRECATED
169 KDE_DEPRECATED void setXMLGUIClient( KXMLGUIClient *client );
170#endif
171
172 /**
173 * Adds an XML gui client that uses this toolbar
174 * @since 4.8.1
175 */
176 void addXMLGUIClient( KXMLGUIClient *client );
177
178 /**
179 * Removes an XML gui client that uses this toolbar
180 * @since 4.8.5
181 */
182 void removeXMLGUIClient( KXMLGUIClient *client );
183
184 /**
185 * Load state from an XML @param element, called by KXMLGUIBuilder.
186 */
187 void loadState( const QDomElement &element );
188
189 /**
190 * Save state into an XML @param element, called by KXMLGUIBuilder.
191 */
192 void saveState( QDomElement &element ) const;
193
194 /**
195 * Reimplemented to support context menu activation on disabled tool buttons.
196 */
197 bool eventFilter( QObject* watched, QEvent* event );
198
199 /**
200 * Returns the global setting for "Icon Text" for the main toolbar
201 * @return global setting for "Icon Text" for the main toolbar
202 */
203 static Qt::ToolButtonStyle toolButtonStyleSetting(); // KDE5: make private and file-static, nobody is calling this
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 protected Q_SLOTS:
228 virtual void slotMovableChanged(bool movable);
229
230 protected:
231 virtual void contextMenuEvent( QContextMenuEvent* );
232 virtual void actionEvent( QActionEvent* );
233
234 // Draggable toolbar configuration
235 virtual void dragEnterEvent( QDragEnterEvent* );
236 virtual void dragMoveEvent( QDragMoveEvent* );
237 virtual void dragLeaveEvent( QDragLeaveEvent* );
238 virtual void dropEvent( QDropEvent* );
239 virtual void mousePressEvent( QMouseEvent* );
240 virtual void mouseMoveEvent( QMouseEvent* );
241 virtual void mouseReleaseEvent( QMouseEvent* );
242
243 private:
244 class Private;
245 Private* const d;
246
247 Q_PRIVATE_SLOT( d, void slotAppearanceChanged() )
248 Q_PRIVATE_SLOT( d, void slotContextAboutToShow() )
249 Q_PRIVATE_SLOT( d, void slotContextAboutToHide() )
250 Q_PRIVATE_SLOT( d, void slotContextLeft() )
251 Q_PRIVATE_SLOT( d, void slotContextRight() )
252 Q_PRIVATE_SLOT( d, void slotContextShowText() )
253 Q_PRIVATE_SLOT( d, void slotContextTop() )
254 Q_PRIVATE_SLOT( d, void slotContextBottom() )
255 Q_PRIVATE_SLOT( d, void slotContextIcons() )
256 Q_PRIVATE_SLOT( d, void slotContextText() )
257 Q_PRIVATE_SLOT( d, void slotContextTextRight() )
258 Q_PRIVATE_SLOT( d, void slotContextTextUnder() )
259 Q_PRIVATE_SLOT( d, void slotContextIconSize() )
260 Q_PRIVATE_SLOT( d, void slotLockToolBars( bool ) )
261};
262
263#endif
264