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
35class QAction;
36class KXMLGUIClient;
37
38class QActionGroup;
39class 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 */
56class 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
65public:
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
254Q_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
282protected 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
294private Q_SLOTS:
295 void slotActionHovered();
296
297
298public:
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
421private:
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