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 * KStandardAction::New, //< see KStandardAction
69 * this, //< Receiver
70 * SLOT(fileNew())); //< SLOT
71 *
72 * ... more actions added to file ...
73 *
74 * KActionCategory *edit = new KActionCategory(i18n("Edit"), actionCollection());
75 * edit->addAction(
76 * KStandardAction::Copy, //< see KStandardAction
77 * this, //< Receiver
78 * SLOT(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 QAction *addAction(KStandardAction::StandardAction actionType, const QObject *receiver = nullptr, const char *member = nullptr);
113
114 QAction *addAction(KStandardAction::StandardAction actionType, const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
115
116 QAction *addAction(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
117
118 template<class ActionType>
119 ActionType *add(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr)
120 {
121 ActionType *action = collection()->add<ActionType>(name, receiver, member);
122 addAction(action);
123 return action;
124 }
125
126 //@}
127
128 /**
129 * Returns the actions belonging to this category
130 */
131 const QList<QAction *> actions() const;
132
133 /**
134 * The action collection this category is associated with.
135 */
136 KActionCollection *collection() const;
137
138 /**
139 * The action categorys descriptive text
140 */
141 QString text() const;
142
143 /**
144 * Set the action categorys descriptive text.
145 */
146 void setText(const QString &text);
147
148private:
149 /**
150 * Remove \action from this category if found.
151 */
152 KXMLGUI_NO_EXPORT void unlistAction(QAction *action);
153
154 /**
155 * Add action to category
156 */
157 void addAction(QAction *action); // exported because called from template method ActionType *add<ActionType>(...)
158
159private:
160 //! KActionCollection needs access to some of our helper methods
161 friend class KActionCollectionPrivate;
162
163 //! Implementation details
164 std::unique_ptr<KActionCategoryPrivate> const d;
165};
166
167#endif /* #ifndef KACTIONCATEGORY_H */
168

source code of kxmlgui/src/kactioncategory.h