1 | // -*- mode: c++; c-basic-offset: 2 -*- |
2 | /* This file is part of the KDE libraries |
3 | Copyright (C) 2000 Kurt Granroth <granroth@kde.org> |
4 | Copyright (C) 2006 Hamish Rodda <rodda@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License version 2 as published by the Free Software Foundation. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | #ifndef KEDITTOOLBAR_H |
21 | #define KEDITTOOLBAR_H |
22 | |
23 | #include <kdialog.h> |
24 | |
25 | class KActionCollection; |
26 | |
27 | class KEditToolBarPrivate; |
28 | class KXMLGUIFactory; |
29 | /** |
30 | * @short A dialog used to customize or configure toolbars. |
31 | * |
32 | * This dialog only works if your application uses the XML UI |
33 | * framework for creating menus and toolbars. It depends on the XML |
34 | * files to describe the toolbar layouts and it requires the actions |
35 | * to determine which buttons are active. |
36 | * |
37 | * Typically you do not need to use it directly as KXmlGuiWindow::setupGUI |
38 | * takes care of it. |
39 | * |
40 | * If you use plugListAction you need to overload saveNewToolbarConfig() |
41 | * to plug actions again: |
42 | * |
43 | * \code |
44 | * void MyClass::saveNewToolbarConfig() |
45 | * { |
46 | * KXmlGuiWindow::saveNewToolbarConfig(); |
47 | * plugActionList( "list1", list1Actions ); |
48 | * plugActionList( "list2", list2Actions ); |
49 | * } |
50 | * \endcode |
51 | * |
52 | * When created, KEditToolBar takes a KXMLGUIFactory object, and uses it to |
53 | * find all of the action collections and XML files (there is one of each for the |
54 | * mainwindow, but there could be more, when adding other XMLGUI clients like |
55 | * KParts or plugins). The editor aims to be semi-intelligent about where it |
56 | * assigns any modifications. In other words, it will not write out part specific |
57 | * changes to your application's main XML file. |
58 | * |
59 | * KXmlGuiWindow and KParts::MainWindow take care of creating KEditToolBar correctly |
60 | * and connecting to its newToolBarConfig slot, but if you really really want to do it |
61 | * yourself, see the KXmlGuiWindow::configureToolbars() and KXmlGuiWindow::saveNewToolbarConfig() code. |
62 | * |
63 | * \image html kedittoolbar.png "KDE Toolbar Editor (KWrite)" |
64 | * |
65 | * @author Kurt Granroth <granroth@kde.org> |
66 | * @maintainer David Faure <faure@kde.org> |
67 | */ |
68 | class KDEUI_EXPORT KEditToolBar : public KDialog |
69 | { |
70 | Q_OBJECT |
71 | public: |
72 | /** |
73 | * Old constructor for apps that do not use components. |
74 | * This constructor is somewhat deprecated, since it doesn't work |
75 | * with any KXMLGuiClient being added to the mainwindow. |
76 | * You really want to use the other constructor. |
77 | * |
78 | * You @em must pass along your collection of actions (some of which appear in your toolbars). |
79 | * |
80 | * @param collection The collection of actions to work on. |
81 | * @param parent The parent of the dialog. |
82 | */ |
83 | explicit KEditToolBar(KActionCollection *collection, |
84 | QWidget* parent = 0); |
85 | |
86 | /** |
87 | * Main constructor. |
88 | * |
89 | * The main parameter, @p factory, is a pointer to the |
90 | * XML GUI factory object for your application. It contains a list |
91 | * of all of the GUI clients (along with the action collections and |
92 | * xml files) and the toolbar editor uses that. |
93 | * |
94 | * Use this like so: |
95 | * \code |
96 | * KEditToolBar edit(factory()); |
97 | * if (edit.exec()) |
98 | * ... |
99 | * \endcode |
100 | * |
101 | * @param factory Your application's factory object |
102 | * @param parent The usual parent for the dialog. |
103 | */ |
104 | explicit KEditToolBar( KXMLGUIFactory* factory, |
105 | QWidget* parent = 0 ); |
106 | |
107 | /// destructor |
108 | ~KEditToolBar(); |
109 | |
110 | /** |
111 | * Sets the default toolbar that will be selected when the dialog is shown. |
112 | * If not set, or QString() is passed in, the global default tool bar name |
113 | * will be used. |
114 | * @param toolBarName the name of the tool bar |
115 | * @see setGlobalDefaultToolBar |
116 | */ |
117 | void setDefaultToolBar( const QString& toolBarName ); |
118 | |
119 | /** |
120 | * The name (absolute or relative) of your application's UI resource file |
121 | * is assumed to be share/apps/appname/appnameui.rc though this can be |
122 | * overridden by calling this method. |
123 | * |
124 | * The global parameter controls whether or not the |
125 | * global resource file is used. If this is @p true, then you may |
126 | * edit all of the actions in your toolbars -- global ones and |
127 | * local one. If it is @p false, then you may edit only your |
128 | * application's entries. The only time you should set this to |
129 | * false is if your application does not use the global resource |
130 | * file at all (very rare). |
131 | * |
132 | * @param xmlfile The application's local resource file. |
133 | * @param global If @p true, then the global resource file will also |
134 | * be parsed. |
135 | */ |
136 | void setResourceFile( const QString& file, bool global = true ); |
137 | |
138 | /** |
139 | * Sets the default toolbar which will be auto-selected for all |
140 | * KEditToolBar instances. Can be overridden on a per-dialog basis |
141 | * by calling setDefaultToolBar( const QString& ) on the dialog. |
142 | * @param toolbarName the name of the tool bar |
143 | */ |
144 | static void setGlobalDefaultToolBar(const char *toolBarName); // TODO should be const QString& |
145 | |
146 | Q_SIGNALS: |
147 | /** |
148 | * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset. |
149 | * Connect to it, to plug action lists and to call applyMainWindowSettings |
150 | * (see sample code in this class's documentation) |
151 | */ |
152 | void newToolBarConfig(); |
153 | |
154 | QT_MOC_COMPAT void newToolbarConfig(); |
155 | |
156 | protected: |
157 | virtual void showEvent(QShowEvent* event); |
158 | virtual void hideEvent(QHideEvent* event); |
159 | |
160 | private: |
161 | friend class KEditToolBarPrivate; |
162 | KEditToolBarPrivate *const d; |
163 | |
164 | Q_PRIVATE_SLOT( d, void _k_slotOk() ) |
165 | Q_PRIVATE_SLOT( d, void _k_slotApply() ) |
166 | Q_PRIVATE_SLOT( d, void _k_acceptOK(bool) ) |
167 | Q_PRIVATE_SLOT( d, void _k_slotDefault() ) |
168 | |
169 | Q_DISABLE_COPY(KEditToolBar) |
170 | }; |
171 | |
172 | #endif // _KEDITTOOLBAR_H |
173 | |