1/* This file is part of the KDE libraries
2
3 Copyright (C) 2008 Michael Jansen <kde@michael-jansen.biz>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KACTIONCATEGORY_H
22#define KACTIONCATEGORY_H
23
24#include <QtCore/QObject>
25#include <QtCore/QString>
26#include <QtCore/QList>
27
28#include "kstandardaction.h"
29#include "kactioncollection.h"
30
31
32class KAction;
33struct KActionCategoryPrivate;
34
35class QAction;
36
37
38
39/**
40 * Categorize actions for KShortcutsEditor.
41 *
42 * KActionCategory provides a second level to organize the actions in
43 * KShortcutsEditor.
44 *
45 * The first possibility is using more than one action collection. Each
46 * actions collection becomes a top level node.
47 *
48 * + action collection 1
49 * + first action
50 * + second action
51 * + third action
52 * + action collection 2
53 * + first action
54 * + second action
55 * + third action
56 *
57 * Using KActionCategory it's possible to group the actions of one collection.
58 * + action collection 1
59 * + first action
60 * + first category
61 * + action 1 in category
62 * + action 2 in category
63 * + second action
64 *
65 * \section Usage
66 *
67 * The usage is analog to action collections. Just create a category and use
68 * it instead of the collection to create the actions.
69 *
70 * The synchronization between KActionCollection and KActionCategory is done
71 * internally. There is for example no need to remove actions from a category.
72 * It is done implicitely if the action is removed from the associated
73 * collection.
74 *
75 * \code
76 *
77 * KActionCategory *file = new KActionCategory(i18n("File"), actionCollection());
78 * file->addAction(
79 * KStandardAction::New, //< see KStandardAction
80 * this, //< Receiver
81 * SLOT(fileNew())); //< SLOT
82 *
83 * ... more actions added to file ...
84 *
85 * KActionCategory *edit = new KActionCategory(i18n("Edit"), actionCollection());
86 * edit->addAction(
87 * KStandardAction::Copy, //< see KStandardAction
88 * this, //< Receiver
89 * SLOT(fileNew())); //< SLOT
90 *
91 * ...
92 *
93 * \endcode
94 */
95class KDEUI_EXPORT KActionCategory : public QObject
96 {
97 Q_OBJECT
98
99 Q_PROPERTY( QString text READ text WRITE setText )
100
101public:
102
103 /**
104 * Default constructor
105 */
106 explicit KActionCategory(const QString &text, KActionCollection *parent=NULL);
107
108 /**
109 * Destructor
110 */
111 virtual ~KActionCategory();
112
113 /**
114 * \name Adding Actions
115 *
116 * Add a action to the category.
117 *
118 * This methods are provided for your convenience. They call the
119 * corresponding method of KActionCollection.
120 */
121 //@{
122 QAction * addAction(const QString &name, QAction *action);
123
124 KAction * addAction(const QString &name, KAction *action);
125
126 KAction * addAction(
127 KStandardAction::StandardAction actionType,
128 const QObject *receiver = NULL,
129 const char *member = NULL);
130
131 KAction * addAction(
132 KStandardAction::StandardAction actionType,
133 const QString &name,
134 const QObject *receiver = NULL,
135 const char *member = NULL);
136
137 KAction *addAction(
138 const QString &name,
139 const QObject *receiver = NULL,
140 const char *member = NULL);
141
142 template<class ActionType>
143 ActionType *add(
144 const QString &name,
145 const QObject *receiver = NULL,
146 const char *member = NULL)
147 {
148 ActionType *action = collection()->add<ActionType>(name, receiver, member);
149 addAction(action);
150 return action;
151 }
152
153 //@}
154
155 /**
156 * Returns the actions belonging to this category
157 */
158 const QList<QAction*> actions() const;
159
160 /**
161 * The action collection this category is associated with.
162 */
163 KActionCollection * collection() const;
164
165 /**
166 * The action categorys descriptive text
167 */
168 QString text() const;
169
170 /**
171 * Set the action categorys descriptive text.
172 */
173 void setText(const QString& text);
174
175private:
176
177 /**
178 * Remove \action from this category if found.
179 */
180 void unlistAction(QAction *action);
181
182 /**
183 * Add action to category
184 */
185 void addAction(QAction *action);
186
187 //! KActionCollection needs access to some of our helper methods
188 friend class KActionCollectionPrivate;
189
190 //! Implementation details
191 KActionCategoryPrivate *const d;
192};
193
194
195#endif /* #ifndef KACTIONCATEGORY_H */
196