1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org> |
3 | (C) 1999 Simon Hausmann <hausmann@kde.org> |
4 | (C) 2000 Nicolas Hadacek <haadcek@kde.org> |
5 | (C) 2000 Kurt Granroth <granroth@kde.org> |
6 | (C) 2000 Michael Koch <koch@kde.org> |
7 | (C) 2001 Holger Freyther <freyther@kde.org> |
8 | (C) 2002 Ellis Whitehead <ellis@kde.org> |
9 | (C) 2005-2006 Hamish Rodda <rodda@kde.org> |
10 | |
11 | This library is free software; you can redistribute it and/or |
12 | modify it under the terms of the GNU Library General Public |
13 | License version 2 as published by the Free Software Foundation. |
14 | |
15 | This library is distributed in the hope that it will be useful, |
16 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
18 | Library General Public License for more details. |
19 | |
20 | You should have received a copy of the GNU Library General Public License |
21 | along with this library; see the file COPYING.LIB. If not, write to |
22 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
23 | Boston, MA 02110-1301, USA. |
24 | */ |
25 | |
26 | #ifndef KACTIONCOLLECTION_H |
27 | #define KACTIONCOLLECTION_H |
28 | |
29 | #include <kdeui_export.h> |
30 | #include <kstandardaction.h> |
31 | #include <kcomponentdata.h> |
32 | |
33 | #include <QtCore/QObject> |
34 | |
35 | class QAction; |
36 | class KXMLGUIClient; |
37 | |
38 | class QActionGroup; |
39 | class QString; |
40 | |
41 | /** |
42 | * \short A container for a set of QAction objects. |
43 | * |
44 | * KActionCollection manages a set of QAction objects. It |
45 | * allows them to be grouped for organized presentation of configuration to the user, |
46 | * saving + loading of configuration, and optionally for automatic plugging into |
47 | * specified widget(s). |
48 | * |
49 | * Additionally, KActionCollection provides several convenience functions for locating |
50 | * named actions, and actions grouped by QActionGroup. |
51 | * |
52 | * \note If you create your own action collection and need to assign shortcuts |
53 | * to the actions within, you have to call associateWidget() or |
54 | * addAssociatedWidget() to have them working. |
55 | */ |
56 | class KDEUI_EXPORT KActionCollection : public QObject |
57 | { |
58 | friend class KXMLGUIClient; |
59 | |
60 | Q_OBJECT |
61 | |
62 | Q_PROPERTY( QString configGroup READ configGroup WRITE setConfigGroup ) |
63 | Q_PROPERTY( bool configIsGlobal READ configIsGlobal WRITE setConfigGlobal ) |
64 | |
65 | public: |
66 | /** |
67 | * Constructor. Allows specification of a KComponentData other than the default |
68 | * global KComponentData, where needed. |
69 | */ |
70 | explicit KActionCollection(QObject *parent, const KComponentData &cData = KComponentData()); |
71 | |
72 | /** |
73 | * Destructor. |
74 | */ |
75 | virtual ~KActionCollection(); |
76 | |
77 | /** |
78 | * Access the list of all action collections in existence for this app |
79 | */ |
80 | static const QList<KActionCollection*>& allCollections(); |
81 | |
82 | /** |
83 | * Clears the entire action collection, deleting all actions. |
84 | */ |
85 | void clear(); |
86 | |
87 | /** |
88 | * Associate all actions in this collection to the given \a widget. |
89 | * Unlike addAssociatedWidget, this method only adds all current actions |
90 | * in the collection to the given widget. Any action added after this call |
91 | * will not be added to the given widget automatically. |
92 | * So this is just a shortcut for a foreach loop and a widget->addAction call. |
93 | */ |
94 | void associateWidget(QWidget* widget) const; |
95 | |
96 | /** |
97 | * Associate all actions in this collection to the given \a widget, including any actions |
98 | * added after this association is made. |
99 | * |
100 | * This does not change the action's shortcut context, so if you need to have the actions only |
101 | * trigger when the widget has focus, you'll need to set the shortcut context on each action |
102 | * to Qt::WidgetShortcut (or better still, Qt::WidgetWithChildrenShortcut with Qt 4.4+) |
103 | */ |
104 | void addAssociatedWidget(QWidget* widget); |
105 | |
106 | /** |
107 | * Remove an association between all actions in this collection and the given \a widget, i.e. |
108 | * remove those actions from the widget, and stop associating newly added actions as well. |
109 | */ |
110 | void removeAssociatedWidget(QWidget* widget); |
111 | |
112 | /** |
113 | * Return a list of all associated widgets. |
114 | */ |
115 | QList<QWidget*> associatedWidgets() const; |
116 | |
117 | /** |
118 | * Clear all associated widgets and remove the actions from those widgets. |
119 | */ |
120 | void clearAssociatedWidgets(); |
121 | |
122 | /** |
123 | * Returns the KConfig group with which settings will be loaded and saved. |
124 | */ |
125 | QString configGroup() const; |
126 | |
127 | /** |
128 | * Returns whether this action collection's configuration should be global to KDE ( \e true ), |
129 | * or specific to the application ( \e false ). |
130 | */ |
131 | bool configIsGlobal() const; |
132 | |
133 | /** |
134 | * Sets \a group as the KConfig group with which settings will be loaded and saved. |
135 | */ |
136 | void setConfigGroup( const QString& group ); |
137 | |
138 | /** |
139 | * Set whether this action collection's configuration should be global to KDE ( \e true ), |
140 | * or specific to the application ( \e false ). |
141 | */ |
142 | void setConfigGlobal( bool global ); |
143 | |
144 | /** |
145 | * Read all key associations from @p config. |
146 | * |
147 | * If @p config is zero, read all key associations from the |
148 | * application's configuration file KGlobal::config(), |
149 | * in the group set by setConfigGroup(). |
150 | */ |
151 | void readSettings( KConfigGroup* config = 0 ); |
152 | |
153 | /** |
154 | * Import from @p config all configurable global key associations. |
155 | * |
156 | * \since 4.1 |
157 | * |
158 | * \param config Config object to read from |
159 | */ |
160 | void importGlobalShortcuts( KConfigGroup* config ); |
161 | |
162 | /** |
163 | * Export the current configurable global key associations to @p config. |
164 | * |
165 | * \since 4.1 |
166 | * |
167 | * \param config Config object to save to |
168 | * \param writeDefaults set to true to write settings which are already at defaults. |
169 | */ |
170 | void exportGlobalShortcuts( KConfigGroup* config, bool writeDefaults = false ) const; |
171 | |
172 | /** |
173 | * Write the current configurable key associations to @a config. What the |
174 | * function does if @a config is zero depends. If this action collection |
175 | * belongs to a KXMLGuiClient the setting are saved to the kxmlgui |
176 | * definition file. If not the settings are written to the applications |
177 | * config file. |
178 | * |
179 | * \note oneAction() and writeDefaults() have no meaning for the kxmlgui |
180 | * configuration file. |
181 | * |
182 | * \param config Config object to save to, or null (see above) |
183 | * \param writeDefaults set to true to write settings which are already at defaults. |
184 | * \param oneAction pass an action here if you just want to save the values for one action, eg. |
185 | * if you know that action is the only one which has changed. |
186 | */ |
187 | void writeSettings( KConfigGroup* config = 0, bool writeDefaults = false, QAction* oneAction = 0 ) const; |
188 | |
189 | /** |
190 | * Returns the number of actions in the collection. |
191 | * |
192 | * This is equivalent to actions().count(). |
193 | */ |
194 | int count() const; |
195 | |
196 | /** |
197 | * Returns whether the action collection is empty or not. |
198 | */ |
199 | bool isEmpty() const; |
200 | |
201 | /** |
202 | * Return the QAction* at position "index" in the action collection. |
203 | * |
204 | * This is equivalent to actions().value(index); |
205 | */ |
206 | QAction *action(int index) const; |
207 | |
208 | /** |
209 | * Get the action with the given \a name from the action collection. |
210 | * |
211 | * @param name Name of the KAction |
212 | * @return A pointer to the KAction in the collection which matches the parameters or |
213 | * null if nothing matches. |
214 | */ |
215 | QAction* action( const QString& name ) const; |
216 | |
217 | /** |
218 | * Returns the list of KActions which belong to this action collection. |
219 | * |
220 | * The list is guaranteed to be in the same order the action were put into |
221 | * the collection. |
222 | */ |
223 | QList<QAction*> actions() const; |
224 | |
225 | /** |
226 | * Returns the list of KActions without an QAction::actionGroup() which belong to this action collection. |
227 | */ |
228 | const QList<QAction*> actionsWithoutGroup() const; |
229 | |
230 | /** |
231 | * Returns the list of all QActionGroups associated with actions in this action collection. |
232 | */ |
233 | const QList<QActionGroup*> actionGroups() const; |
234 | |
235 | /** |
236 | * Set the \a componentData associated with this action collection. |
237 | * |
238 | * \warning Don't call this method on a KActionCollection that contains |
239 | * actions. This is not supported. |
240 | * |
241 | * \param componentData the KComponentData which is to be associated with this action collection, |
242 | * or an invalid KComponentData instance to indicate the default KComponentData. |
243 | */ |
244 | void setComponentData(const KComponentData &componentData); |
245 | |
246 | /** The KComponentData with which this class is associated. */ |
247 | KComponentData componentData() const; |
248 | |
249 | /** |
250 | * The parent KXMLGUIClient, or null if not available. |
251 | */ |
252 | const KXMLGUIClient *parentGUIClient() const; |
253 | |
254 | Q_SIGNALS: |
255 | /** |
256 | * Indicates that \a action was inserted into this action collection. |
257 | */ |
258 | void inserted( QAction* action ); |
259 | |
260 | /** |
261 | * Indicates that \a action was removed from this action collection. |
262 | * @deprecated |
263 | */ |
264 | QT_MOC_COMPAT void removed( QAction* action ); |
265 | |
266 | /** |
267 | * Indicates that \a action was highlighted (hovered over). |
268 | * @deprecated Replaced by actionHovered(QAction* action); |
269 | */ |
270 | QT_MOC_COMPAT void actionHighlighted(QAction* action); |
271 | |
272 | /** |
273 | * Indicates that \a action was hovered. |
274 | */ |
275 | void actionHovered(QAction* action); |
276 | |
277 | /** |
278 | * Indicates that \a action was triggered |
279 | */ |
280 | void actionTriggered(QAction* action); |
281 | |
282 | protected Q_SLOTS: |
283 | /// Overridden to perform connections when someone wants to know whether an action was highlighted or triggered |
284 | virtual void connectNotify ( const char * signal ); |
285 | |
286 | virtual void slotActionTriggered(); |
287 | |
288 | /** |
289 | * @internal |
290 | * @deprecated Replaced by slotActionHovered(); |
291 | */ |
292 | QT_MOC_COMPAT virtual void slotActionHighlighted(); |
293 | |
294 | private Q_SLOTS: |
295 | void slotActionHovered(); |
296 | |
297 | |
298 | public: |
299 | /** |
300 | * Add an action under the given name to the collection. |
301 | * |
302 | * Inserting an action that was previously inserted under a different name will replace the |
303 | * old entry, i.e. the action will not be available under the old name anymore but only under |
304 | * the new one. |
305 | * |
306 | * Inserting an action under a name that is already used for another action will replace |
307 | * the other action in the collection (but will not delete it). |
308 | * |
309 | * @param name The name by which the action be retrieved again from the collection. |
310 | * @param action The action to add. |
311 | * @return the same as the action given as parameter. This is just for convenience |
312 | * (chaining calls) and consistency with the other addAction methods, you can also |
313 | * simply ignore the return value. |
314 | */ |
315 | QAction *addAction(const QString &name, QAction *action); |
316 | KAction *addAction(const QString &name, KAction *action); |
317 | |
318 | /** |
319 | * Removes an action from the collection and deletes it. |
320 | * @param action The action to remove. |
321 | */ |
322 | void removeAction(QAction *action); |
323 | |
324 | /** |
325 | * Removes an action from the collection. |
326 | * @param action the action to remove. |
327 | */ |
328 | QAction* takeAction(QAction *action); |
329 | |
330 | /** |
331 | * Creates a new standard action, adds it to the collection and connects the |
332 | * action's triggered(bool) signal to the specified receiver/member. The |
333 | * newly created action is also returned. |
334 | * |
335 | * Note: Using KStandardAction::OpenRecent will cause a different signal than |
336 | * triggered(bool) to be used, see KStandardAction for more information. |
337 | * |
338 | * The action can be retrieved later from the collection by its standard name as per |
339 | * KStandardAction::stdName. |
340 | * |
341 | * @param actionType The standard action type of the action to create. |
342 | * @param receiver The QObject to connect the triggered(bool) signal to. Leave 0 if no |
343 | * connection is desired. |
344 | * @param member The SLOT to connect the triggered(bool) signal to. Leave 0 if no |
345 | * connection is desired. |
346 | * @return new action of the given type ActionType. |
347 | */ |
348 | KAction *addAction(KStandardAction::StandardAction actionType, const QObject *receiver = 0, const char *member = 0); |
349 | |
350 | /** |
351 | * Creates a new standard action, adds to the collection under the given name |
352 | * and connects the action's triggered(bool) signal to the specified |
353 | * receiver/member. The newly created action is also returned. |
354 | * |
355 | * Note: Using KStandardAction::OpenRecent will cause a different signal than |
356 | * triggered(bool) to be used, see KStandardAction for more information. |
357 | * |
358 | * The action can be retrieved later from the collection by the specified name. |
359 | * |
360 | * @param actionType The standard action type of the action to create. |
361 | * @param name The name by which the action be retrieved again from the collection. |
362 | * @param receiver The QObject to connect the triggered(bool) signal to. Leave 0 if no |
363 | * connection is desired. |
364 | * @param member The SLOT to connect the triggered(bool) signal to. Leave 0 if no |
365 | * connection is desired. |
366 | * @return new action of the given type ActionType. |
367 | */ |
368 | KAction *addAction(KStandardAction::StandardAction actionType, const QString &name, |
369 | const QObject *receiver = 0, const char *member = 0); |
370 | |
371 | /** |
372 | * Creates a new action under the given name to the collection and connects |
373 | * the action's triggered(bool) signal to the specified receiver/member. The |
374 | * newly created action is returned. |
375 | * |
376 | * NOTE: KDE prior to 4.2 used the triggered() signal instead of the triggered(bool) |
377 | * signal. |
378 | * |
379 | * Inserting an action that was previously inserted under a different name will replace the |
380 | * old entry, i.e. the action will not be available under the old name anymore but only under |
381 | * the new one. |
382 | * |
383 | * Inserting an action under a name that is already used for another action will replace |
384 | * the other action in the collection. |
385 | * |
386 | * @param name The name by which the action be retrieved again from the collection. |
387 | * @param receiver The QObject to connect the triggered(bool) signal to. Leave 0 if no |
388 | * connection is desired. |
389 | * @param member The SLOT to connect the triggered(bool) signal to. Leave 0 if no |
390 | * connection is desired. |
391 | * @return new action of the given type ActionType. |
392 | */ |
393 | KAction *addAction(const QString &name, const QObject *receiver = 0, const char *member = 0); |
394 | |
395 | /** |
396 | * Creates a new action under the given name, adds it to the collection and connects the action's triggered(bool) |
397 | * signal to the specified receiver/member. The receiver slot may accept either a bool or no |
398 | * parameters at all (i.e. slotTriggered(bool) or slotTriggered() ). |
399 | * The type of the action is specified by the template parameter ActionType. |
400 | * |
401 | * NOTE: KDE prior to 4.2 connected the triggered() signal instead of the triggered(bool) |
402 | * signal. |
403 | * |
404 | * @param name The internal name of the action (e.g. "file-open"). |
405 | * @param receiver The QObject to connect the triggered(bool) signal to. Leave 0 if no |
406 | * connection is desired. |
407 | * @param member The SLOT to connect the triggered(bool) signal to. Leave 0 if no |
408 | * connection is desired. |
409 | * @return new action of the given type ActionType. |
410 | */ |
411 | template<class ActionType> |
412 | ActionType *add(const QString &name, const QObject *receiver = 0, const char *member = 0) |
413 | { |
414 | ActionType *a = new ActionType(this); |
415 | if (receiver && member) |
416 | connect(a, SIGNAL(triggered(bool)), receiver, member); |
417 | addAction(name, a); |
418 | return a; |
419 | } |
420 | |
421 | private: |
422 | Q_PRIVATE_SLOT(d, void _k_actionDestroyed(QObject *)) |
423 | Q_PRIVATE_SLOT(d, void _k_associatedWidgetDestroyed(QObject*)) |
424 | |
425 | KActionCollection( const KXMLGUIClient* parent ); // used by KXMLGUIClient |
426 | |
427 | friend class KActionCollectionPrivate; |
428 | class KActionCollectionPrivate* const d; |
429 | }; |
430 | |
431 | #endif |
432 | |