Kirigami-addons

kirigamiactioncollection.h
1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org>
4 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org>
5 SPDX-FileCopyrightText: 2000 Nicolas Hadacek <haadcek@kde.org>
6 SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
7 SPDX-FileCopyrightText: 2000 Michael Koch <koch@kde.org>
8 SPDX-FileCopyrightText: 2001 Holger Freyther <freyther@kde.org>
9 SPDX-FileCopyrightText: 2002 Ellis Whitehead <ellis@kde.org>
10 SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org>
11
12 SPDX-License-Identifier: LGPL-2.0-only
13*/
14
15#pragma once
16
17#include <kirigamiaddonsstatefulapp_export.h>
18#include <KStandardActions>
19
20#include <QAction>
21#include <QObject>
22#include <memory>
23
24class KConfigGroup;
25class QActionGroup;
26class QString;
27
28/**
29 * @class KirigamiActionCollection kirigamiactioncollection.h KirigamiActionCollection
30 *
31 * \short A container for a set of QAction objects.
32 *
33 * KirigamiActionCollection manages a set of QAction objects. It
34 * allows them to be grouped for organized presentation of configuration to the user,
35 * saving + loading of configuration, and optionally for automatic plugging into
36 * specified widget(s).
37 *
38 * Additionally, KirigamiActionCollection provides several convenience functions for locating
39 * named actions, and actions grouped by QActionGroup.
40 *
41 * @since KirigamiAddons 1.4.0
42 */
43class KIRIGAMIADDONSSTATEFULAPP_EXPORT KirigamiActionCollection : public QObject
44{
45 Q_OBJECT
46
47 Q_PROPERTY(QString configGroup READ configGroup WRITE setConfigGroup)
48 Q_PROPERTY(bool configIsGlobal READ configIsGlobal WRITE setConfigGlobal)
49
50public:
51 /**
52 * Constructor. Allows specification of a component name other than the default
53 * application name, where needed (remember to call setComponentDisplayName() too).
54 */
55 explicit KirigamiActionCollection(QObject *parent, const QString &cName = QString());
56
57 /**
58 * Destructor.
59 */
61
62 /**
63 * Access the list of all action collections in existence for this app
64 */
65 static const QList<KirigamiActionCollection *> &allCollections();
66
67 /**
68 * Clears the entire action collection, deleting all actions.
69 */
70 void clear();
71
72 /**
73 * Returns the KConfig group with which settings will be loaded and saved.
74 */
75 QString configGroup() const;
76
77 /**
78 * Returns whether this action collection's configuration should be global to KDE ( @c true ),
79 * or specific to the application ( @c false ).
80 */
81 bool configIsGlobal() const;
82
83 /**
84 * Sets @p group as the KConfig group with which settings will be loaded and saved.
85 */
86 void setConfigGroup(const QString &group);
87
88 /**
89 * Set whether this action collection's configuration should be global to KDE ( @c true ),
90 * or specific to the application ( @c false ).
91 */
92 void setConfigGlobal(bool global);
93
94 /**
95 * Read all key associations from @p config.
96 *
97 * If @p config is zero, read all key associations from the
98 * application's configuration file KSharedConfig::openConfig(),
99 * in the group set by setConfigGroup().
100 */
101 void readSettings(KConfigGroup *config = nullptr);
102
103 /**
104 * Write the current configurable key associations to @p config. What the
105 * function does if @p config is zero depends. If this action collection
106 * belongs to a KXMLGUIClient the setting are saved to the kxmlgui
107 * definition file. If not the settings are written to the applications
108 * config file.
109 *
110 * \note @p oneAction and @p writeDefaults have no meaning for the kxmlgui
111 * configuration file.
112 *
113 * \param config Config object to save to, or null (see above)
114 * \param writeDefaults set to true to write settings which are already at defaults.
115 * \param oneAction pass an action here if you just want to save the values for one action, eg.
116 * if you know that action is the only one which has changed.
117 */
118 void writeSettings(KConfigGroup *config = nullptr, bool writeDefaults = false, QAction *oneAction = nullptr) const;
119
120 /**
121 * Returns the number of actions in the collection.
122 *
123 * This is equivalent to actions().count().
124 */
125 int count() const;
126
127 /**
128 * Returns whether the action collection is empty or not.
129 */
130 bool isEmpty() const;
131
132 /**
133 * Return the QAction* at position @p index in the action collection.
134 *
135 * This is equivalent to actions().value(index);
136 */
137 QAction *action(int index) const;
138
139 /**
140 * Get the action with the given \p name from the action collection.
141 *
142 * This won't return the action for the menus defined using a "<Menu>" tag
143 * in XMLGUI files (e.g. "<Menu name="menuId">" in "applicationNameui.rc").
144 * To access menu actions defined like this, use e.g.
145 * \code
146 * qobject_cast<QMenu *>(guiFactory()->container("menuId", this));
147 * \endcode
148 * after having called setupGUI() or createGUI().
149 *
150 * @param name Name of the QAction
151 * @return A pointer to the QAction in the collection which matches the parameters or
152 * null if nothing matches.
153 */
154 Q_INVOKABLE QAction *action(const QString &name) const;
155
156 /**
157 * Returns the list of QActions which belong to this action collection.
158 *
159 * The list is guaranteed to be in the same order the action were put into
160 * the collection.
161 */
162 QList<QAction *> actions() const;
163
164 /**
165 * Returns the list of QActions without an QAction::actionGroup() which belong to this action collection.
166 */
167 const QList<QAction *> actionsWithoutGroup() const;
168
169 /**
170 * Returns the list of all QActionGroups associated with actions in this action collection.
171 */
172 const QList<QActionGroup *> actionGroups() const;
173
174 /**
175 * Set the @p componentName associated with this action collection.
176 *
177 * \warning Don't call this method on a KirigamiActionCollection that contains
178 * actions. This is not supported.
179 *
180 * \param componentData the name which is to be associated with this action collection,
181 * or QString() to indicate the app name. This is used to load/save settings into XML files.
182 * KXMLGUIClient::setComponentName takes care of calling this.
183 */
184 void setComponentName(const QString &componentName);
185
186 /** The component name with which this class is associated. */
187 QString componentName() const;
188
189 /**
190 * Set the component display name associated with this action collection.
191 * (e.g. for the toolbar editor)
192 * KXMLGUIClient::setComponentName takes care of calling this.
193 */
194 void setComponentDisplayName(const QString &displayName);
195
196 /** The display name for the associated component. */
197 QString componentDisplayName() const;
198
200 /**
201 * Indicates that @p action was inserted into this action collection.
202 */
203 void inserted(QAction *action);
204
205 /**
206 * Emitted when an action has been inserted into, or removed from, this action collection.
207 */
208 void changed();
209
210 /**
211 * Indicates that @p action was hovered.
212 */
213 void actionHovered(QAction *action);
214
215 /**
216 * Indicates that @p action was triggered
217 */
219
220protected:
221 /// Overridden to perform connections when someone wants to know whether an action was highlighted or triggered
222 void connectNotify(const QMetaMethod &signal) override;
223
224protected Q_SLOTS:
225 virtual void slotActionTriggered();
226
227private Q_SLOTS:
228 KIRIGAMIADDONSSTATEFULAPP_NO_EXPORT void slotActionHovered();
229
230public:
231 /**
232 * Add an action under the given name to the collection.
233 *
234 * Inserting an action that was previously inserted under a different name will replace the
235 * old entry, i.e. the action will not be available under the old name anymore but only under
236 * the new one.
237 *
238 * Inserting an action under a name that is already used for another action will replace
239 * the other action in the collection (but will not delete it).
240 *
241 * If KAuthorized::authorizeAction() reports that the action is not
242 * authorized, it will be disabled and hidden.
243 *
244 * The ownership of the action object is not transferred.
245 * If the action is destroyed it will be removed automatically from the KirigamiActionCollection.
246 *
247 * @param name The name by which the action be retrieved again from the collection.
248 * @param action The action to add.
249 * @return the same as the action given as parameter. This is just for convenience
250 * (chaining calls) and consistency with the other addAction methods, you can also
251 * simply ignore the return value.
252 */
253 Q_INVOKABLE QAction *addAction(const QString &name, QAction *action);
254
255 /**
256 * Adds a list of actions to the collection.
257 *
258 * The objectName of the actions is used as their internal name in the collection.
259 *
260 * The ownership of the action objects is not transferred.
261 * If the action is destroyed it will be removed automatically from the KirigamiActionCollection.
262 *
263 * Uses addAction(const QString&, QAction*).
264 *
265 * @param actions the list of the actions to add.
266 *
267 * @see addAction()
268 */
269 void addActions(const QList<QAction *> &actions);
270
271 /**
272 * Removes an action from the collection and deletes it.
273 * @param action The action to remove.
274 */
275 void removeAction(QAction *action);
276
277 /**
278 * Removes an action from the collection.
279 *
280 * The ownership of the action object is not changed.
281 *
282 * @param action the action to remove.
283 */
284 QAction *takeAction(QAction *action);
285
286#ifdef K_DOXYGEN
287 /**
288 * Creates a new standard action, adds it to the collection and connects the
289 * action's triggered(bool) signal to the specified receiver/member. The
290 * newly created action is also returned.
291 *
292 * The action can be retrieved later from the collection by its standard name as per
293 * KStandardActions::stdName.
294 *
295 * The KirigamiActionCollection takes ownership of the action object.
296 *
297 * @param actionType The standard action type of the action to create.
298 * @param name The name by which the action be retrieved again from the collection.
299 * @param receiver The QObject to connect the triggered(bool) signal to.
300 * @param slot The slot or lambda to connect the triggered(bool) signal to.
301 * @return new action of the given type ActionType.
302 */
303 inline QAction *addAction(KStandardActions::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
304#else
305 template<class Receiver, class Func>
306 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
307 addAction(KStandardActions::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
308#endif
309 {
310 QAction *action = KStandardActions::create(actionType, receiver, slot, nullptr);
311 action->setParent(this);
312 action->setObjectName(name);
313 return addAction(name, action);
314 }
315
316#ifdef K_DOXYGEN
317 /**
318 * Creates a new action under the given name, adds it to the collection and
319 * connects the action's triggered(bool) signal to the specified
320 * receiver/member.
321 *
322 * The type of the action is specified by the template parameter ActionType.
323 *
324 * The KirigamiActionCollection takes ownership of the action object.
325 *
326 * @param name The internal name of the action (e.g. "file-open").
327 * @param receiver The QObject to connect the triggered(bool) signal to.
328 * @param slot The slot or lambda to connect the triggered(bool) signal to.
329 * @return new action of the given type ActionType.
330 *
331 * @see add(const QString &, const QObject *, const char *)
332 */
333 template<class ActionType>
334 inline ActionType *add(const QString &name, const Receiver *receiver, Func slot)
335#else
336 template<class ActionType, class Receiver, class Func>
337 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, ActionType>::type *
338 add(const QString &name, const Receiver *receiver, Func slot)
339#endif
340 {
341 ActionType *a = new ActionType(this);
342 connect(a, &QAction::triggered, receiver, slot);
343 addAction(name, a);
344 return a;
345 }
346
347#ifdef K_DOXYGEN
348 /**
349 * Creates a new action under the given name to the collection and connects
350 * the action's triggered(bool) signal to the specified receiver/member. The
351 * newly created action is returned.
352 *
353 * @param name The internal name of the action (e.g. "file-open").
354 * @param receiver The QObject to connect the triggered(bool) signal to.
355 * @param slot The slot or lambda to connect the triggered(bool) signal to.
356 * @return new action of the given type ActionType.
357 */
358 inline QAction *addAction(const QString &name, const Receiver *receiver, Func slot)
359#else
360 template<class Receiver, class Func>
361 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
362 addAction(const QString &name, const Receiver *receiver, Func slot)
363#endif
364 {
365 return add<QAction>(name, receiver, slot);
366 }
367
368 /**
369 * Get the default primary shortcut for the given action.
370 *
371 * @param action the action for which the default primary shortcut should be returned.
372 * @return the default primary shortcut of the given action
373 */
374 static QKeySequence defaultShortcut(QAction *action);
375
376 /**
377 * Get the default shortcuts for the given action.
378 *
379 * @param action the action for which the default shortcuts should be returned.
380 * @return the default shortcuts of the given action
381 */
382 static QList<QKeySequence> defaultShortcuts(QAction *action);
383
384 /**
385 * Set the default shortcut for the given action.
386 *
387 * @param action the action for which the default shortcut should be set.
388 * @param shortcut the shortcut to use for the given action in its specified shortcutContext()
389 */
390 static void setDefaultShortcut(QAction *action, const QKeySequence &shortcut);
391
392 /**
393 * Set the default shortcuts for the given action.
394 *
395 * @param action the action for which the default shortcut should be set.
396 * @param shortcuts the shortcuts to use for the given action in its specified shortcutContext()
397 */
398 Q_INVOKABLE static void setDefaultShortcuts(QAction *action, const QList<QKeySequence> &shortcuts);
399
400 /**
401 * Returns true if the given action's shortcuts may be configured by the user.
402 *
403 * @param action the action for the hint should be verified.
404 */
405 static bool isShortcutsConfigurable(QAction *action);
406
407 /**
408 * Indicate whether the user may configure the action's shortcuts.
409 *
410 * @param action the action for the hint should be verified.
411 * @param configurable set to true if the shortcuts of the given action may be configured by the user, otherwise false.
412 */
413 static void setShortcutsConfigurable(QAction *action, bool configurable);
414
415private:
416 friend class KirigamiActionCollectionPrivate;
417 std::unique_ptr<class KirigamiActionCollectionPrivate> const d;
418};
A container for a set of QAction objects.
void changed()
Emitted when an action has been inserted into, or removed from, this action collection.
void inserted(QAction *action)
Indicates that action was inserted into this action collection.
void actionTriggered(QAction *action)
Indicates that action was triggered.
void actionHovered(QAction *action)
Indicates that action was hovered.
ActionType * add(const QString &name, const Receiver *receiver, Func slot)
Creates a new action under the given name, adds it to the collection and connects the action's trigge...
QAction * addAction(const QString &name, const Receiver *receiver, Func slot)
Creates a new action under the given name to the collection and connects the action's triggered(bool)...
QAction * addAction(KStandardActions::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
Creates a new standard action, adds it to the collection and connects the action's triggered(bool) si...
QAction * create(StandardAction id, const Receiver *recvr, Func slot, QObject *parent, std::optional< Qt::ConnectionType > connectionType=std::nullopt)
void triggered(bool checked)
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QMetaObject::Connection connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)
virtual void connectNotify(const QMetaMethod &signal)
void setObjectName(QAnyStringView name)
void setParent(QObject *parent)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:33:45 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.