KXmlGui

kactioncategory.h
1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KACTIONCATEGORY_H
9#define KACTIONCATEGORY_H
10
11#include <kxmlgui_export.h>
12
13#include <QList>
14#include <QObject>
15#include <QString>
16#include <memory>
17
18#include <KStandardAction>
19
20#include "kactioncollection.h"
21
22struct KActionCategoryPrivate;
23
24class QAction;
25
26/**
27 * @class KActionCategory kactioncategory.h KActionCategory
28 *
29 * Categorize actions for KShortcutsEditor.
30 *
31 * KActionCategory provides a second level to organize the actions in
32 * KShortcutsEditor.
33 *
34 * The first possibility is using more than one action collection. Each
35 * actions collection becomes a top level node.
36 *
37 * + action collection 1
38 * + first action
39 * + second action
40 * + third action
41 * + action collection 2
42 * + first action
43 * + second action
44 * + third action
45 *
46 * Using KActionCategory it's possible to group the actions of one collection.
47 * + action collection 1
48 * + first action
49 * + first category
50 * + action 1 in category
51 * + action 2 in category
52 * + second action
53 *
54 * \section Usage
55 *
56 * The usage is analog to action collections. Just create a category and use
57 * it instead of the collection to create the actions.
58 *
59 * The synchronization between KActionCollection and KActionCategory is done
60 * internally. There is for example no need to remove actions from a category.
61 * It is done implicitly if the action is removed from the associated
62 * collection.
63 *
64 * \code
65 *
66 * KActionCategory *file = new KActionCategory(i18n("File"), actionCollection());
67 * file->addAction(
68 * KStandardActions::New, //< see KStandardAction
69 * this, //< Receiver
70 * &MyApp::fileNew); //< Slot
71 *
72 * ... more actions added to file ...
73 *
74 * KActionCategory *edit = new KActionCategory(i18n("Edit"), actionCollection());
75 * edit->addAction(
76 * KStandardActions::Copy, //< see KStandardAction
77 * this, //< Receiver
78 * &MyApp::fileNew); //< Slot
79 *
80 * ...
81 *
82 * \endcode
83 */
84class KXMLGUI_EXPORT KActionCategory : public QObject
85{
86 Q_OBJECT
87
88 Q_PROPERTY(QString text READ text WRITE setText)
89
90public:
91 /**
92 * Default constructor
93 */
94 explicit KActionCategory(const QString &text, KActionCollection *parent = nullptr);
95
96 /**
97 * Destructor
98 */
99 ~KActionCategory() override;
100
101 /**
102 * \name Adding Actions
103 *
104 * Add a action to the category.
105 *
106 * This methods are provided for your convenience. They call the
107 * corresponding method of KActionCollection.
108 */
109 //@{
110 QAction *addAction(const QString &name, QAction *action);
111
112#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
113 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use KStandardActions overload")
114 QAction *addAction(KStandardAction::StandardAction actionType, const QObject *receiver = nullptr, const char *member = nullptr);
115#endif
116
117#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
118 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use KStandardActions overload")
119 QAction *addAction(KStandardAction::StandardAction actionType, const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
120#endif
121
122#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
123 // not marked with KXMLGUI_DEPRECATED_VERSION, otherwise addAction("bla") generates a warning, but we don't want that
124 /*!
125 * @deprecated since 6.9, use PMF overload
126 */
127 QAction *addAction(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
128#else
129 // this is only enabled when
130 // addAction(KStandardAction::StandardAction actionType, const QObject *receiver = nullptr, const char *member = nullptr
131 // is not built, otherwise there is ambiguity
132 inline QAction *addAction(const QString &name)
133 {
134 QAction *action = collection()->addAction(name);
135 addAction(action);
136 return action;
137 }
138#endif
139
140#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
141 template<class ActionType>
142 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use PMF-based overload")
143 ActionType *add(const QString &name, const QObject *receiver, const char *member)
144 {
145 ActionType *action = collection()->add<ActionType>(name, receiver, member);
146 addAction(action);
147 return action;
148 }
149#endif
150
151 /**
152 * Creates a new standard action, adds it to the collection and connects the
153 * action's triggered(bool) signal to the specified receiver/member. The
154 * newly created action is also returned.
155 *
156 * The KActionCollection takes ownership of the action object.
157 *
158 * @param actionType The standard action type of the action to create.
159 * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
160 * connection is desired.
161 * @param slot The slot or lambda to connect the triggered(bool) signal to.
162 * @return the created action.
163 *
164 * @since 6.9
165 */
166#ifdef K_DOXYGEN
167 inline QAction *addAction(KStandardActions::StandardAction actionType, const Receiver *receiver, Func slot)
168#else
169 template<class Receiver, class Func>
170 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
171 addAction(KStandardActions::StandardAction actionType, const Receiver *receiver, Func slot)
172#endif
173 {
174 QAction *action = collection()->addAction(actionType, receiver, slot);
175 addAction(action);
176 return action;
177 }
178
179 /**
180 * Creates a new standard action and adds it to the collection.
181 * The newly created action is also returned.
182 *
183 * The KActionCollection takes ownership of the action object.
184 *
185 * @param actionType The standard action type of the action to create.
186 * @return the created action.
187 *
188 * @since 6.9
189 */
190 QAction *addAction(KStandardActions::StandardAction actionType);
191
192 /**
193 * Creates a new standard action, adds it to the collection and connects the
194 * action's triggered(bool) signal to the specified receiver/member. The
195 * newly created action is also returned.
196 *
197 * The KActionCollection takes ownership of the action object.
198 *
199 * @param actionType The standard action type of the action to create.
200 * @param name The name by which the action be retrieved again from the collection.
201 * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
202 * connection is desired.
203 * @param slot The slot or lambda to connect the triggered(bool) signal to.
204 * @return the created action.
205 *
206 * @since 6.9
207 */
208#ifdef K_DOXYGEN
209 inline QAction *addAction(KStandardActions::StandardAction actionType, const Receiver *receiver, Func slot)
210#else
211 template<class Receiver, class Func>
212 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
213 addAction(KStandardActions::StandardAction actionType, const QString &name, const Receiver *receiver, Func slot)
214#endif
215 {
216 QAction *action = collection()->addAction(actionType, name, receiver, slot);
217 addAction(action);
218 return action;
219 }
220
221 /**
222 * Creates a new action, adds it to the collection and connects the
223 * action's triggered(bool) signal to the specified receiver/member. The
224 * newly created action is also returned.
225 *
226 * The KActionCollection takes ownership of the action object.
227 *
228 * @param name The name by which the action be retrieved again from the collection.
229 * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
230 * connection is desired.
231 * @param slot The slot or lambda to connect the triggered(bool) signal to.
232 * @return the created action.
233 *
234 * @since 6.9
235 */
236#ifdef K_DOXYGEN
237 inline QAction *addAction(const Receiver *receiver, Func slot)
238#else
239 template<class Receiver, class Func>
240 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
241 addAction(const QString &name, const Receiver *receiver, Func slot)
242#endif
243 {
244 QAction *action = collection()->addAction(name, receiver, slot);
245 addAction(action);
246 return action;
247 }
248
249 /**
250 * Creates a new action, adds it to the collection and connects the
251 * action's triggered(bool) signal to the specified receiver/member. The
252 * newly created action is also returned.
253 *
254 * The KActionCollection takes ownership of the action object.
255 *
256 * @param name The name by which the action be retrieved again from the collection.
257 * @param receiver The QObject to connect the triggered(bool) signal to. Leave nullptr if no
258 * connection is desired.
259 * @param slot The slot or lambda to connect the triggered(bool) signal to.
260 * @return the created action.
261 *
262 * @since 6.9
263 */
264#ifdef K_DOXYGEN
265 inline QAction *add(const Receiver *receiver, Func slot)
266#else
267 template<class ActionType, class Receiver, class Func>
268 inline typename std::enable_if<!std::is_convertible<Func, const char *>::value, QAction>::type *
269 add(const QString &name, const Receiver *receiver, Func slot)
270#endif
271 {
272 QAction *action = collection()->add<ActionType>(name, receiver, slot);
273 addAction(action);
274 return action;
275 }
276
277 /**
278 * Creates a new action and adds it to the collection.
279 * The newly created action is also returned.
280 *
281 * The KActionCollection takes ownership of the action object.
282 *
283 * @param name The name by which the action be retrieved again from the collection.
284 * @return the created action.
285 *
286 * @since 6.9
287 */
288 template<class ActionType>
289 ActionType *add(const QString &name)
290 {
291 ActionType *action = collection()->add<ActionType>(name);
292 addAction(action);
293 return action;
294 }
295
296 //@}
297
298 /**
299 * Returns the actions belonging to this category
300 */
301 const QList<QAction *> actions() const;
302
303 /**
304 * The action collection this category is associated with.
305 */
306 KActionCollection *collection() const;
307
308 /**
309 * The action categorys descriptive text
310 */
311 QString text() const;
312
313 /**
314 * Set the action categorys descriptive text.
315 */
316 void setText(const QString &text);
317
318private:
319 /**
320 * Remove \action from this category if found.
321 */
322 KXMLGUI_NO_EXPORT void unlistAction(QAction *action);
323
324 /**
325 * Add action to category
326 */
327 void addAction(QAction *action); // exported because called from template method ActionType *add<ActionType>(...)
328
329private:
330 //! KActionCollection needs access to some of our helper methods
331 friend class KActionCollectionPrivate;
332
333 //! Implementation details
334 std::unique_ptr<KActionCategoryPrivate> const d;
335};
336
337#endif /* #ifndef KACTIONCATEGORY_H */
Categorize actions for KShortcutsEditor.
ActionType * add(const QString &name)
Creates a new action and adds it to the collection.
QAction * addAction(KStandardActions::StandardAction actionType, const Receiver *receiver, Func slot)
Creates a new standard action, adds it to the collection and connects the action's triggered(bool) si...
~KActionCategory() override
Destructor.
QAction * add(const Receiver *receiver, Func slot)
Creates a new action, adds it to the collection and connects the action's triggered(bool) signal to t...
QAction * addAction(const Receiver *receiver, Func slot)
Creates a new action, adds it to the collection and connects the action's triggered(bool) signal to t...
A container for a set of QAction objects.
Q_PROPERTY(...)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:56:26 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.