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 | |
32 | class KAction; |
33 | struct KActionCategoryPrivate; |
34 | |
35 | class 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 | */ |
95 | class KDEUI_EXPORT KActionCategory : public QObject |
96 | { |
97 | Q_OBJECT |
98 | |
99 | Q_PROPERTY( QString text READ text WRITE setText ) |
100 | |
101 | public: |
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 | |
175 | private: |
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 | |