KXmlGui

kactioncollection.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <[email protected]>
4  SPDX-FileCopyrightText: 1999 Simon Hausmann <[email protected]>
5  SPDX-FileCopyrightText: 2000 Nicolas Hadacek <[email protected]>
6  SPDX-FileCopyrightText: 2000 Kurt Granroth <[email protected]>
7  SPDX-FileCopyrightText: 2000 Michael Koch <[email protected]>
8  SPDX-FileCopyrightText: 2001 Holger Freyther <[email protected]>
9  SPDX-FileCopyrightText: 2002 Ellis Whitehead <[email protected]>
10  SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <[email protected]>
11 
12  SPDX-License-Identifier: LGPL-2.0-only
13 */
14 
15 #ifndef KACTIONCOLLECTION_H
16 #define KACTIONCOLLECTION_H
17 
18 #include <KStandardAction>
19 #include <kxmlgui_export.h>
20 
21 #include <QAction>
22 #include <QObject>
23 #include <memory>
24 
25 class KXMLGUIClient;
26 class KConfigGroup;
27 class QActionGroup;
28 class QString;
29 
30 /**
31  * @class KActionCollection kactioncollection.h KActionCollection
32  *
33  * \short A container for a set of QAction objects.
34  *
35  * KActionCollection manages a set of QAction objects. It
36  * allows them to be grouped for organized presentation of configuration to the user,
37  * saving + loading of configuration, and optionally for automatic plugging into
38  * specified widget(s).
39  *
40  * Additionally, KActionCollection provides several convenience functions for locating
41  * named actions, and actions grouped by QActionGroup.
42  *
43  * \note If you create your own action collection and need to assign shortcuts
44  * to the actions within, you have to call associateWidget() or
45  * addAssociatedWidget() to have them working.
46  */
47 class KXMLGUI_EXPORT KActionCollection : public QObject
48 {
49  friend class KXMLGUIClient;
50 
51  Q_OBJECT
52 
53  Q_PROPERTY(QString configGroup READ configGroup WRITE setConfigGroup)
54  Q_PROPERTY(bool configIsGlobal READ configIsGlobal WRITE setConfigGlobal)
55 
56 public:
57  /**
58  * Constructor. Allows specification of a component name other than the default
59  * application name, where needed (remember to call setComponentDisplayName() too).
60  */
61  explicit KActionCollection(QObject *parent, const QString &cName = QString());
62 
63  /**
64  * Destructor.
65  */
66  ~KActionCollection() override;
67 
68  /**
69  * Access the list of all action collections in existence for this app
70  */
71  static const QList<KActionCollection *> &allCollections();
72 
73  /**
74  * Clears the entire action collection, deleting all actions.
75  */
76  void clear();
77 
78  /**
79  * Associate all actions in this collection to the given @p widget.
80  * Unlike addAssociatedWidget(), this method only adds all current actions
81  * in the collection to the given widget. Any action added after this call
82  * will not be added to the given widget automatically.
83  * So this is just a shortcut for a foreach loop and a widget->addAction call.
84  */
85  void associateWidget(QWidget *widget) const;
86 
87  /**
88  * Associate all actions in this collection to the given @p widget, including any actions
89  * added after this association is made.
90  *
91  * This does not change the action's shortcut context, so if you need to have the actions only
92  * trigger when the widget has focus, you'll need to set the shortcut context on each action
93  * to Qt::WidgetShortcut (or better still, Qt::WidgetWithChildrenShortcut with Qt 4.4+)
94  */
95  void addAssociatedWidget(QWidget *widget);
96 
97  /**
98  * Remove an association between all actions in this collection and the given @p widget, i.e.
99  * remove those actions from the widget, and stop associating newly added actions as well.
100  */
101  void removeAssociatedWidget(QWidget *widget);
102 
103  /**
104  * Return a list of all associated widgets.
105  */
106  QList<QWidget *> associatedWidgets() const;
107 
108  /**
109  * Clear all associated widgets and remove the actions from those widgets.
110  */
111  void clearAssociatedWidgets();
112 
113  /**
114  * Returns the KConfig group with which settings will be loaded and saved.
115  */
116  QString configGroup() const;
117 
118  /**
119  * Returns whether this action collection's configuration should be global to KDE ( @c true ),
120  * or specific to the application ( @c false ).
121  */
122  bool configIsGlobal() const;
123 
124  /**
125  * Sets @p group as the KConfig group with which settings will be loaded and saved.
126  */
127  void setConfigGroup(const QString &group);
128 
129  /**
130  * Set whether this action collection's configuration should be global to KDE ( @c true ),
131  * or specific to the application ( @c false ).
132  */
133  void setConfigGlobal(bool global);
134 
135  /**
136  * Read all key associations from @p config.
137  *
138  * If @p config is zero, read all key associations from the
139  * application's configuration file KSharedConfig::openConfig(),
140  * in the group set by setConfigGroup().
141  */
142  void readSettings(KConfigGroup *config = nullptr);
143 
144  /**
145  * Import from @p config all configurable global key associations.
146  *
147  * \since 4.1
148  *
149  * \param config Config object to read from
150  */
151  void importGlobalShortcuts(KConfigGroup *config);
152 
153  /**
154  * Export the current configurable global key associations to @p config.
155  *
156  * \since 4.1
157  *
158  * \param config Config object to save to
159  * \param writeDefaults set to true to write settings which are already at defaults.
160  */
161  void exportGlobalShortcuts(KConfigGroup *config, bool writeDefaults = false) const;
162 
163  /**
164  * Write the current configurable key associations to @p config. What the
165  * function does if @p config is zero depends. If this action collection
166  * belongs to a KXMLGUIClient the setting are saved to the kxmlgui
167  * definition file. If not the settings are written to the applications
168  * config file.
169  *
170  * \note @p oneAction and @p writeDefaults have no meaning for the kxmlgui
171  * configuration file.
172  *
173  * \param config Config object to save to, or null (see above)
174  * \param writeDefaults set to true to write settings which are already at defaults.
175  * \param oneAction pass an action here if you just want to save the values for one action, eg.
176  * if you know that action is the only one which has changed.
177  */
178  void writeSettings(KConfigGroup *config = nullptr, bool writeDefaults = false, QAction *oneAction = nullptr) const;
179 
180  /**
181  * Returns the number of actions in the collection.
182  *
183  * This is equivalent to actions().count().
184  */
185  int count() const;
186 
187  /**
188  * Returns whether the action collection is empty or not.
189  */
190  bool isEmpty() const;
191 
192  /**
193  * Return the QAction* at position @p index in the action collection.
194  *
195  * This is equivalent to actions().value(index);
196  */
197  QAction *action(int index) const;
198 
199  /**
200  * Get the action with the given \p name from the action collection.
201  *
202  * This won't return the action for the menus defined using a "<Menu>" tag
203  * in XMLGUI files (e.g. "<Menu name="menuId">" in "applicationNameui.rc").
204  * To access menu actions defined like this, use e.g.
205  * \code
206  * qobject_cast<QMenu *>(guiFactory()->container("menuId", this));
207  * \endcode
208  * after having called setupGUI() or createGUI().
209  *
210  * @param name Name of the QAction
211  * @return A pointer to the QAction in the collection which matches the parameters or
212  * null if nothing matches.
213  */
214  QAction *action(const QString &name) const;
215 
216  /**
217  * Returns the list of QActions which belong to this action collection.
218  *
219  * The list is guaranteed to be in the same order the action were put into
220  * the collection.
221  */
222  QList<QAction *> actions() const;
223 
224  /**
225  * Returns the list of QActions without an QAction::actionGroup() which belong to this action collection.
226  */
227  const QList<QAction *> actionsWithoutGroup() const;
228 
229  /**
230  * Returns the list of all QActionGroups associated with actions in this action collection.
231  */
232  const QList<QActionGroup *> actionGroups() const;
233 
234  /**
235  * Set the @p componentName associated with this action collection.
236  *
237  * \warning Don't call this method on a KActionCollection that contains
238  * actions. This is not supported.
239  *
240  * \param componentData the name which is to be associated with this action collection,
241  * or QString() to indicate the app name. This is used to load/save settings into XML files.
242  * KXMLGUIClient::setComponentName takes care of calling this.
243  */
245 
246  /** The component name with which this class is associated. */
247  QString componentName() const;
248 
249  /**
250  * Set the component display name associated with this action collection.
251  * (e.g. for the toolbar editor)
252  * KXMLGUIClient::setComponentName takes care of calling this.
253  */
254  void setComponentDisplayName(const QString &displayName);
255 
256  /** The display name for the associated component. */
257  QString componentDisplayName() const;
258 
259  /**
260  * The parent KXMLGUIClient, or null if not available.
261  */
262  const KXMLGUIClient *parentGUIClient() const;
263 
264 Q_SIGNALS:
265  /**
266  * Indicates that @p action was inserted into this action collection.
267  */
268  void inserted(QAction *action);
269 
270 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
271  /**
272  * Indicates that @p action was removed from this action collection.
273  * @deprecated Since 5.0, use changed() (added in 5.66) instead.
274  */
275  KXMLGUI_DEPRECATED_VERSION(5, 0, "removed() is sometimes emitted with partially destroyed objects; use changed() instead (added in 5.66)")
276  QT_MOC_COMPAT void removed(QAction *action);
277 #endif
278 
279  /**
280  * Emitted when an action has been inserted into, or removed from, this action collection.
281  * @since 5.66
282  */
283  void changed();
284 
285 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
286  /**
287  * Indicates that @p action was highlighted (hovered over).
288  * @deprecated Since 5.0. Replaced by actionHovered(QAction* action);
289  */
290  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use KActionCollection::actionHovered(QAction* action)")
291  QT_MOC_COMPAT void actionHighlighted(QAction *action);
292 #endif
293 
294  /**
295  * Indicates that @p action was hovered.
296  */
297  void actionHovered(QAction *action);
298 
299  /**
300  * Indicates that @p action was triggered
301  */
302  void actionTriggered(QAction *action);
303 
304 protected:
305  /// Overridden to perform connections when someone wants to know whether an action was highlighted or triggered
306  void connectNotify(const QMetaMethod &signal) override;
307 
308 protected Q_SLOTS:
309  virtual void slotActionTriggered();
310 
311 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
312  /**
313  * @internal
314  * @deprecated Since 5.0. Replaced by slotActionHovered();
315  */
316  KXMLGUI_DEPRECATED_VERSION(5, 0, "Use KActionCollection::slotActionHovered()")
317  QT_MOC_COMPAT virtual void slotActionHighlighted();
318 #endif
319 
320 private Q_SLOTS:
321  KXMLGUI_NO_EXPORT void slotActionHovered();
322 
323 public:
324  /**
325  * Add an action under the given name to the collection.
326  *
327  * Inserting an action that was previously inserted under a different name will replace the
328  * old entry, i.e. the action will not be available under the old name anymore but only under
329  * the new one.
330  *
331  * Inserting an action under a name that is already used for another action will replace
332  * the other action in the collection (but will not delete it).
333  *
334  * If KAuthorized::authorizeAction() reports that the action is not
335  * authorized, it will be disabled and hidden.
336  *
337  * The ownership of the action object is not transferred.
338  * If the action is destroyed it will be removed automatically from the KActionCollection.
339  *
340  * @param name The name by which the action be retrieved again from the collection.
341  * @param action The action to add.
342  * @return the same as the action given as parameter. This is just for convenience
343  * (chaining calls) and consistency with the other addAction methods, you can also
344  * simply ignore the return value.
345  */
346  Q_INVOKABLE QAction *addAction(const QString &name, QAction *action);
347 
348  /**
349  * Adds a list of actions to the collection.
350  *
351  * The objectName of the actions is used as their internal name in the collection.
352  *
353  * The ownership of the action objects is not transferred.
354  * If the action is destroyed it will be removed automatically from the KActionCollection.
355  *
356  * Uses addAction(const QString&, QAction*).
357  *
358  * @param actions the list of the actions to add.
359  *
360  * @see addAction()
361  * @since 5.0
362  */
363  void addActions(const QList<QAction *> &actions);
364 
365  /**
366  * Removes an action from the collection and deletes it.
367  * @param action The action to remove.
368  */
369  void removeAction(QAction *action);
370 
371  /**
372  * Removes an action from the collection.
373  *
374  * The ownership of the action object is not changed.
375  *
376  * @param action the action to remove.
377  */
378  QAction *takeAction(QAction *action);
379 
380  /**
381  * Creates a new standard action, adds it to the collection and connects the
382  * action's triggered(bool) signal to the specified receiver/member. The
383  * newly created action is also returned.
384  *
385  * @note Using KStandardAction::OpenRecent will cause a different signal than
386  * triggered(bool) to be used, see KStandardAction for more information.
387  *
388  * The action can be retrieved later from the collection by its standard name as per
389  * KStandardAction::stdName.
390  *
391  * The KActionCollection takes ownership of the action object.
392  *
393  * @param actionType The standard action type of the action to create.
394  * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
395  * connection is desired.
396  * @param member The SLOT to connect the triggered(bool) signal to. Leave nullptr if no
397  * connection is desired.
398  * @return new action of the given type ActionType.
399  */
400  QAction *addAction(KStandardAction::StandardAction actionType, const QObject *receiver = nullptr, const char *member = nullptr);
401 
402  /**
403  * Creates a new standard action, adds to the collection under the given name
404  * and connects the action's triggered(bool) signal to the specified
405  * receiver/member. The newly created action is also returned.
406  *
407  * @note Using KStandardAction::OpenRecent will cause a different signal than
408  * triggered(bool) to be used, see KStandardAction for more information.
409  *
410  * The action can be retrieved later from the collection by the specified name.
411  *
412  * The KActionCollection takes ownership of the action object.
413  *
414  * @param actionType The standard action type of the action to create.
415  * @param name The name by which the action be retrieved again from the collection.
416  * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
417  * connection is desired.
418  * @param member The SLOT to connect the triggered(bool) signal to. Leave nullptr if no
419  * connection is desired.
420  * @return new action of the given type ActionType.
421  */
422  QAction *addAction(KStandardAction::StandardAction actionType, const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
423 
424 /**
425  * This is the same as addAction(KStandardAction::StandardAction actionType, const QString &name, const QObject *receiver, const char *member) using
426  * new style connect syntax.
427  *
428  * @param actionType The standard action type of the action to create.
429  * @param name The name by which the action be retrieved again from the collection.
430  * @param receiver The QObject to connect the triggered(bool) signal to.
431  * @param slot The slot or lambda to connect the triggered(bool) signal to.
432  * @return new action of the given type ActionType.
433  *
434  * @see addAction(KStandardAction::StandardAction, const QString &, const QObject *, const char *)
435  * @since 5.80
436  */
437 #ifdef K_DOXYGEN
438  inline QAction *addAction(KStandardAction::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
439 #else
440  template<class Receiver, class Func>
441  inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
442  addAction(KStandardAction::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
443 #endif
444  {
445  QAction *action = KStandardAction::create(actionType, receiver, slot, nullptr);
446  action->setParent(this);
447  action->setObjectName(name);
448  return addAction(name, action);
449  }
450 
451  /**
452  * Creates a new action under the given name to the collection and connects
453  * the action's triggered(bool) signal to the specified receiver/member. The
454  * newly created action is returned.
455  *
456  * NOTE: KDE prior to 4.2 used the triggered() signal instead of the triggered(bool)
457  * signal.
458  *
459  * Inserting an action that was previously inserted under a different name will replace the
460  * old entry, i.e. the action will not be available under the old name anymore but only under
461  * the new one.
462  *
463  * Inserting an action under a name that is already used for another action will replace
464  * the other action in the collection.
465  *
466  * The KActionCollection takes ownership of the action object.
467  *
468  * @param name The name by which the action be retrieved again from the collection.
469  * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
470  * connection is desired.
471  * @param member The SLOT to connect the triggered(bool) signal to. Leave nullptr if no
472  * connection is desired.
473  * @return new action of the given type ActionType.
474  */
475  QAction *addAction(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
476 
477  /**
478  * Creates a new action under the given name, adds it to the collection and connects the action's triggered(bool)
479  * signal to the specified receiver/member. The receiver slot may accept either a bool or no
480  * parameters at all (i.e. slotTriggered(bool) or slotTriggered() ).
481  * The type of the action is specified by the template parameter ActionType.
482  *
483  * NOTE: KDE prior to 4.2 connected the triggered() signal instead of the triggered(bool)
484  * signal.
485  *
486  * The KActionCollection takes ownership of the action object.
487  *
488  * @param name The internal name of the action (e.g. "file-open").
489  * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
490  * connection is desired.
491  * @param member The SLOT to connect the triggered(bool) signal to. Leave nullptr if no
492  * connection is desired.
493  * @return new action of the given type ActionType.
494  *
495  * @see addAction()
496  */
497  template<class ActionType>
498  ActionType *add(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr)
499  {
500  ActionType *a = new ActionType(this);
501  if (receiver && member) {
502  connect(a, SIGNAL(triggered(bool)), receiver, member);
503  }
504  addAction(name, a);
505  return a;
506  }
507 
508 /**
509  * This is the same as add(const QString &name, const QObject *receiver, const char *member) using
510  * new style connect syntax.
511  *
512  * @param name The internal name of the action (e.g. "file-open").
513  * @param receiver The QObject to connect the triggered(bool) signal to.
514  * @param slot The slot or lambda to connect the triggered(bool) signal to.
515  * @return new action of the given type ActionType.
516  *
517  * @see add(const QString &, const QObject *, const char *)
518  * @since 5.28
519  */
520 #ifdef K_DOXYGEN
521  template<class ActionType>
522  inline ActionType *add(const QString &name, const Receiver *receiver, Func slot)
523 #else
524  template<class ActionType, class Receiver, class Func>
525  inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, ActionType>::type *
526  add(const QString &name, const Receiver *receiver, Func slot)
527 #endif
528  {
529  ActionType *a = new ActionType(this);
530  connect(a, &QAction::triggered, receiver, slot);
531  addAction(name, a);
532  return a;
533  }
534 
535 /**
536  * This is the same as addAction(const QString &name, const QObject *receiver, const char *member) using
537  * new style connect syntax.
538  *
539  * @param name The internal name of the action (e.g. "file-open").
540  * @param receiver The QObject to connect the triggered(bool) signal to.
541  * @param slot The slot or lambda to connect the triggered(bool) signal to.
542  * @return new action of the given type ActionType.
543  *
544  * @see addAction(const QString &, const QObject *, const char *)
545  * @since 5.28
546  */
547 #ifdef K_DOXYGEN
548  inline QAction *addAction(const QString &name, const Receiver *receiver, Func slot)
549 #else
550  template<class Receiver, class Func>
551  inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
552  addAction(const QString &name, const Receiver *receiver, Func slot)
553 #endif
554  {
555  return add<QAction>(name, receiver, slot);
556  }
557 
558  /**
559  * Get the default primary shortcut for the given action.
560  *
561  * @param action the action for which the default primary shortcut should be returned.
562  * @return the default primary shortcut of the given action
563  * @since 5.0
564  */
565  QKeySequence defaultShortcut(QAction *action) const;
566 
567  /**
568  * Get the default shortcuts for the given action.
569  *
570  * @param action the action for which the default shortcuts should be returned.
571  * @return the default shortcuts of the given action
572  * @since 5.0
573  */
574  QList<QKeySequence> defaultShortcuts(QAction *action) const;
575 
576  // TODO KF6: Make setDefaultShortcut static
577  /**
578  * Set the default shortcut for the given action.
579  * Since 5.2, this also calls action->setShortcut(shortcut), i.e. the default shortcut is
580  * made active initially.
581  *
582  * @param action the action for which the default shortcut should be set.
583  * @param shortcut the shortcut to use for the given action in its specified shortcutContext()
584  * @since 5.0
585  */
586  void setDefaultShortcut(QAction *action, const QKeySequence &shortcut);
587 
588  /**
589  * Set the default shortcuts for the given action.
590  * Since 5.2, this also calls action->setShortcuts(shortcuts), i.e. the default shortcut is
591  * made active initially.
592  *
593  * @param action the action for which the default shortcut should be set.
594  * @param shortcuts the shortcuts to use for the given action in its specified shortcutContext()
595  * @since 5.0
596  */
597  Q_INVOKABLE void setDefaultShortcuts(QAction *action, const QList<QKeySequence> &shortcuts);
598 
599  /**
600  * Returns true if the given action's shortcuts may be configured by the user.
601  *
602  * @param action the action for the hint should be verified.
603  * @since 5.0
604  */
605  bool isShortcutsConfigurable(QAction *action) const;
606 
607  /**
608  * Indicate whether the user may configure the action's shortcuts.
609  *
610  * @param action the action for the hint should be verified.
611  * @param configurable set to true if the shortcuts of the given action may be configured by the user, otherwise false.
612  * @since 5.0
613  */
614  void setShortcutsConfigurable(QAction *action, bool configurable);
615 
616 private:
617  KXMLGUI_NO_EXPORT explicit KActionCollection(const KXMLGUIClient *parent); // used by KXMLGUIClient
618 
619  friend class KActionCollectionPrivate;
620  std::unique_ptr<class KActionCollectionPrivate> const d;
621 };
622 
623 #endif
Q_PROPERTY(...)
Q_SLOTSQ_SLOTS
QMetaObject::Connection connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
A container for a set of QAction objects.
QAction * create(StandardAction id, const QObject *recvr, const char *slot, QObject *parent)
ActionType * add(const QString &name, const QObject *receiver=nullptr, const char *member=nullptr)
Creates a new action under the given name, adds it to the collection and connects the action's trigge...
virtual void setComponentName(const QString &componentName, const QString &componentDisplayName)
Sets the component name for this part.
KSharedConfigPtr config()
Q_SIGNALSQ_SIGNALS
ActionType * add(const QString &name, const Receiver *receiver, Func slot)
This is the same as add(const QString &name, const QObject *receiver, const char *member) using new s...
void triggered(bool checked)
QAction * action(const char *name) const
Retrieves an action of the client by name.
void setObjectName(const QString &name)
void setParent(QObject *parent)
QAction * addAction(KStandardAction::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
This is the same as addAction(KStandardAction::StandardAction actionType, const QString &name,...
virtual void connectNotify(const QMetaMethod &signal)
QAction * addAction(const QString &name, const Receiver *receiver, Func slot)
This is the same as addAction(const QString &name, const QObject *receiver, const char *member) using...
virtual QString componentName() const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:59:26 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.