-rw-r--r-- | microkde/kdeui/kaction.h | 26 |
1 files changed, 14 insertions, 12 deletions
diff --git a/microkde/kdeui/kaction.h b/microkde/kdeui/kaction.h index 13e2e1e..5c690ec 100644 --- a/microkde/kdeui/kaction.h +++ b/microkde/kdeui/kaction.h | |||
@@ -1,142 +1,144 @@ | |||
1 | /* This file is part of the KDE libraries | 1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org> | 2 | Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org> |
3 | (C) 1999 Simon Hausmann <hausmann@kde.org> | 3 | (C) 1999 Simon Hausmann <hausmann@kde.org> |
4 | (C) 2000 Nicolas Hadacek <haadcek@kde.org> | 4 | (C) 2000 Nicolas Hadacek <haadcek@kde.org> |
5 | (C) 2000 Kurt Granroth <granroth@kde.org> | 5 | (C) 2000 Kurt Granroth <granroth@kde.org> |
6 | (C) 2000 Michael Koch <koch@kde.org> | 6 | (C) 2000 Michael Koch <koch@kde.org> |
7 | (C) 2001 Holger Freyther <freyther@kde.org> | 7 | (C) 2001 Holger Freyther <freyther@kde.org> |
8 | (C) 2002 Ellis Whitehead <ellis@kde.org> | 8 | (C) 2002 Ellis Whitehead <ellis@kde.org> |
9 | 9 | ||
10 | This library is free software; you can redistribute it and/or | 10 | This library is free software; you can redistribute it and/or |
11 | modify it under the terms of the GNU Library General Public | 11 | modify it under the terms of the GNU Library General Public |
12 | License version 2 as published by the Free Software Foundation. | 12 | License version 2 as published by the Free Software Foundation. |
13 | 13 | ||
14 | This library is distributed in the hope that it will be useful, | 14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of | 15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | 16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | Library General Public License for more details. | 17 | Library General Public License for more details. |
18 | 18 | ||
19 | You should have received a copy of the GNU Library General Public License | 19 | You should have received a copy of the GNU Library General Public License |
20 | along with this library; see the file COPYING.LIB. If not, write to | 20 | along with this library; see the file COPYING.LIB. If not, write to |
21 | the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | 21 | the Free Software Foundation, Inc., 59 Temple Place - Suite 330, |
22 | Boston, MA 02111-1307, USA. | 22 | Boston, MA 02111-1307, USA. |
23 | */ | 23 | */ |
24 | //$Id$ | 24 | //$Id$ |
25 | 25 | ||
26 | #ifndef __kaction_h__ | 26 | #ifndef __kaction_h__ |
27 | #define __kaction_h__ | 27 | #define __kaction_h__ |
28 | 28 | ||
29 | 29 | ||
30 | //US #include <qkeysequence.h> | 30 | //US #include <qkeysequence.h> |
31 | #include <qobject.h> | 31 | #include <qobject.h> |
32 | #include <qvaluelist.h> | 32 | #include <q3valuelist.h> |
33 | #include <qguardedptr.h> | 33 | #include <qpointer.h> |
34 | //Added by qt3to4: | ||
35 | #include <Q3PopupMenu> | ||
34 | #include <kguiitem.h> | 36 | #include <kguiitem.h> |
35 | #include <kshortcut.h> | 37 | #include <kshortcut.h> |
36 | #include <kstdaction.h> | 38 | #include <kstdaction.h> |
37 | //US#include <kicontheme.h> | 39 | //US#include <kicontheme.h> |
38 | 40 | ||
39 | //US added the following files | 41 | //US added the following files |
40 | #include <kiconloader.h> | 42 | #include <kiconloader.h> |
41 | 43 | ||
42 | class QMenuBar; | 44 | class QMenuBar; |
43 | class QPopupMenu; | 45 | class Q3PopupMenu; |
44 | //USclass QComboBox; | 46 | //USclass QComboBox; |
45 | //USclass QPoint; | 47 | //USclass QPoint; |
46 | class QIconSet; | 48 | class QIcon; |
47 | class QString; | 49 | class QString; |
48 | class KToolBar; | 50 | class KToolBar; |
49 | 51 | ||
50 | class KAccel; | 52 | class KAccel; |
51 | //USclass KAccelActions; | 53 | //USclass KAccelActions; |
52 | //USclass KConfig; | 54 | //USclass KConfig; |
53 | //USclass KConfigBase; | 55 | //USclass KConfigBase; |
54 | //USclass KURL; | 56 | //USclass KURL; |
55 | //USclass KInstance; | 57 | //USclass KInstance; |
56 | //USclass KToolBar; | 58 | //USclass KToolBar; |
57 | class KActionCollection; | 59 | class KActionCollection; |
58 | //USclass KPopupMenu; | 60 | //USclass KPopupMenu; |
59 | class KMainWindow; | 61 | class KMainWindow; |
60 | 62 | ||
61 | /** | 63 | /** |
62 | * The KAction class (and derived and super classes) provides a way to | 64 | * The KAction class (and derived and super classes) provides a way to |
63 | * easily encapsulate a "real" user-selected action or event in your | 65 | * easily encapsulate a "real" user-selected action or event in your |
64 | * program. | 66 | * program. |
65 | * | 67 | * |
66 | * For instance, a user may want to @p paste the contents of | 68 | * For instance, a user may want to @p paste the contents of |
67 | * the clipboard or @p scroll @p down a document or @p quit the | 69 | * the clipboard or @p scroll @p down a document or @p quit the |
68 | * application. These are all @p actions -- events that the | 70 | * application. These are all @p actions -- events that the |
69 | * user causes to happen. The KAction class allows the developer to | 71 | * user causes to happen. The KAction class allows the developer to |
70 | * deal with these actions in an easy and intuitive manner. | 72 | * deal with these actions in an easy and intuitive manner. |
71 | * | 73 | * |
72 | * Specifically, the KAction class encapsulated the various attributes | 74 | * Specifically, the KAction class encapsulated the various attributes |
73 | * to an event/action. For instance, an action might have an icon | 75 | * to an event/action. For instance, an action might have an icon |
74 | * that goes along with it (a clipboard for a "paste" action or | 76 | * that goes along with it (a clipboard for a "paste" action or |
75 | * scissors for a "cut" action). The action might have some text to | 77 | * scissors for a "cut" action). The action might have some text to |
76 | * describe the action. It will certainly have a method or function | 78 | * describe the action. It will certainly have a method or function |
77 | * that actually @p executes the action! All these attributes | 79 | * that actually @p executes the action! All these attributes |
78 | * are contained within the KAction object. | 80 | * are contained within the KAction object. |
79 | * | 81 | * |
80 | * The advantage of dealing with Actions is that you can manipulate | 82 | * The advantage of dealing with Actions is that you can manipulate |
81 | * the Action without regard to the GUI representation of it. For | 83 | * the Action without regard to the GUI representation of it. For |
82 | * instance, in the "normal" way of dealing with actions like "cut", | 84 | * instance, in the "normal" way of dealing with actions like "cut", |
83 | * you would manually insert a item for Cut into a menu and a button | 85 | * you would manually insert a item for Cut into a menu and a button |
84 | * into a toolbar. If you want to disable the cut action for a moment | 86 | * into a toolbar. If you want to disable the cut action for a moment |
85 | * (maybe nothing is selected), you woud have to hunt down the pointer | 87 | * (maybe nothing is selected), you woud have to hunt down the pointer |
86 | * to the menu item and the toolbar button and disable both | 88 | * to the menu item and the toolbar button and disable both |
87 | * individually. Setting the menu item and toolbar item up uses very | 89 | * individually. Setting the menu item and toolbar item up uses very |
88 | * similar code - but has to be done twice! | 90 | * similar code - but has to be done twice! |
89 | * | 91 | * |
90 | * With the Action concept, you simply "plug" the Action into whatever | 92 | * With the Action concept, you simply "plug" the Action into whatever |
91 | * GUI element you want. The KAction class will then take care of | 93 | * GUI element you want. The KAction class will then take care of |
92 | * correctly defining the menu item (with icons, accelerators, text, | 94 | * correctly defining the menu item (with icons, accelerators, text, |
93 | * etc) or toolbar button.. or whatever. From then on, if you | 95 | * etc) or toolbar button.. or whatever. From then on, if you |
94 | * manipulate the Action at all, the effect will propogate through all | 96 | * manipulate the Action at all, the effect will propogate through all |
95 | * GUI representations of it. Back to the "cut" example: if you want | 97 | * GUI representations of it. Back to the "cut" example: if you want |
96 | * to disable the Cut Action, you would simply do | 98 | * to disable the Cut Action, you would simply do |
97 | * 'cutAction->setEnabled(false)' and the menuitem and button would | 99 | * 'cutAction->setEnabled(false)' and the menuitem and button would |
98 | * instantly be disabled! | 100 | * instantly be disabled! |
99 | * | 101 | * |
100 | * This is the biggest advantage to the Action concept -- there is a | 102 | * This is the biggest advantage to the Action concept -- there is a |
101 | * one-to-one relationship between the "real" action and @p all | 103 | * one-to-one relationship between the "real" action and @p all |
102 | * GUI representations of it. | 104 | * GUI representations of it. |
103 | * | 105 | * |
104 | * KAction emits the activated() signal if the user activated the | 106 | * KAction emits the activated() signal if the user activated the |
105 | * corresponding GUI element ( menu item, toolbar button, etc. ) | 107 | * corresponding GUI element ( menu item, toolbar button, etc. ) |
106 | * | 108 | * |
107 | * If you are in the situation of wanting to map the activated() | 109 | * If you are in the situation of wanting to map the activated() |
108 | * signal of multiple action objects to one slot, with a special | 110 | * signal of multiple action objects to one slot, with a special |
109 | * argument bound to each action, then you might consider using | 111 | * argument bound to each action, then you might consider using |
110 | * @ref QSignalMapper . A tiny example: | 112 | * @ref QSignalMapper . A tiny example: |
111 | * | 113 | * |
112 | * <PRE> | 114 | * <PRE> |
113 | * QSignalMapper *desktopNumberMapper = new QSignalMapper( this ); | 115 | * QSignalMapper *desktopNumberMapper = new QSignalMapper( this ); |
114 | * connect( desktopNumberMapper, SIGNAL( mapped( int ) ), | 116 | * connect( desktopNumberMapper, SIGNAL( mapped( int ) ), |
115 | * this, SLOT( moveWindowToDesktop( int ) ) ); | 117 | * this, SLOT( moveWindowToDesktop( int ) ) ); |
116 | * | 118 | * |
117 | * for ( uint i = 0; i < numberOfDesktops; ++i ) { | 119 | * for ( uint i = 0; i < numberOfDesktops; ++i ) { |
118 | * KAction *desktopAction = new KAction( i18n( "Move Window to Desktop %i" ).arg( i ), ... ); | 120 | * KAction *desktopAction = new KAction( i18n( "Move Window to Desktop %i" ).arg( i ), ... ); |
119 | * connect( desktopAction, SIGNAL( activated() ), desktopNumberMapper, SLOT( map() ) ); | 121 | * connect( desktopAction, SIGNAL( activated() ), desktopNumberMapper, SLOT( map() ) ); |
120 | * desktopNumberMapper->setMapping( desktopAction, i ); | 122 | * desktopNumberMapper->setMapping( desktopAction, i ); |
121 | * } | 123 | * } |
122 | * </PRE> | 124 | * </PRE> |
123 | * | 125 | * |
124 | * @sect General Usage: | 126 | * @sect General Usage: |
125 | * | 127 | * |
126 | * The steps to using actions are roughly as follows | 128 | * The steps to using actions are roughly as follows |
127 | * | 129 | * |
128 | * @li Decide which attributes you want to associate with a given | 130 | * @li Decide which attributes you want to associate with a given |
129 | * action (icons, text, keyboard shortcut, etc) | 131 | * action (icons, text, keyboard shortcut, etc) |
130 | * @li Create the action using KAction (or derived or super class). | 132 | * @li Create the action using KAction (or derived or super class). |
131 | * @li "Plug" the Action into whatever GUI element you want. Typically, | 133 | * @li "Plug" the Action into whatever GUI element you want. Typically, |
132 | * this will be a menu or toolbar. | 134 | * this will be a menu or toolbar. |
133 | * | 135 | * |
134 | * @sect Detailed Example: | 136 | * @sect Detailed Example: |
135 | * | 137 | * |
136 | * Here is an example of enabling a "New [document]" action | 138 | * Here is an example of enabling a "New [document]" action |
137 | * <PRE> | 139 | * <PRE> |
138 | * KAction *newAct = new KAction(i18n("&New"), "filenew", | 140 | * KAction *newAct = new KAction(i18n("&New"), "filenew", |
139 | * KStdAccel::shortcut(KStdAccel::New), | 141 | * KStdAccel::shortcut(KStdAccel::New), |
140 | * this, SLOT(fileNew()), | 142 | * this, SLOT(fileNew()), |
141 | * actionCollection(), "new"); | 143 | * actionCollection(), "new"); |
142 | * </PRE> | 144 | * </PRE> |
@@ -166,459 +168,459 @@ class KMainWindow; | |||
166 | * newAct->setEnabled(false) | 168 | * newAct->setEnabled(false) |
167 | * </PRE> | 169 | * </PRE> |
168 | * and both the menuitem in File and the toolbar button will instantly | 170 | * and both the menuitem in File and the toolbar button will instantly |
169 | * be disabled. | 171 | * be disabled. |
170 | * | 172 | * |
171 | * Do not delete a KAction object without unplugging it from all its | 173 | * Do not delete a KAction object without unplugging it from all its |
172 | * containers. The simplest way to do that is to use the unplugAll() | 174 | * containers. The simplest way to do that is to use the unplugAll() |
173 | * as in the following example: | 175 | * as in the following example: |
174 | * <PRE> | 176 | * <PRE> |
175 | * newAct->unplugAll(); | 177 | * newAct->unplugAll(); |
176 | * delete newAct; | 178 | * delete newAct; |
177 | * </PRE> | 179 | * </PRE> |
178 | * Normally you will not need to do this as KActionCollection manages | 180 | * Normally you will not need to do this as KActionCollection manages |
179 | * everything for you. | 181 | * everything for you. |
180 | * | 182 | * |
181 | * Note: if you are using a "standard" action like "new", "paste", | 183 | * Note: if you are using a "standard" action like "new", "paste", |
182 | * "quit", or any other action described in the KDE UI Standards, | 184 | * "quit", or any other action described in the KDE UI Standards, |
183 | * please use the methods in the @ref KStdAction class rather than | 185 | * please use the methods in the @ref KStdAction class rather than |
184 | * defining your own. | 186 | * defining your own. |
185 | * | 187 | * |
186 | * @sect Usage Within the XML Framework: | 188 | * @sect Usage Within the XML Framework: |
187 | * | 189 | * |
188 | * If you are using KAction within the context of the XML menu and | 190 | * If you are using KAction within the context of the XML menu and |
189 | * toolbar building framework, then there are a few tiny changes. The | 191 | * toolbar building framework, then there are a few tiny changes. The |
190 | * first is that you must insert your new action into an action | 192 | * first is that you must insert your new action into an action |
191 | * collection. The action collection (a @ref KActionCollection) is, | 193 | * collection. The action collection (a @ref KActionCollection) is, |
192 | * logically enough, a central collection of all of the actions | 194 | * logically enough, a central collection of all of the actions |
193 | * defined in your application. The XML UI framework code in KXMLGUI | 195 | * defined in your application. The XML UI framework code in KXMLGUI |
194 | * classes needs access to this collection in order to build up the | 196 | * classes needs access to this collection in order to build up the |
195 | * GUI (it's how the builder code knows which actions are valid and | 197 | * GUI (it's how the builder code knows which actions are valid and |
196 | * which aren't). | 198 | * which aren't). |
197 | * | 199 | * |
198 | * Also, if you use the XML builder framework, then you do not ever | 200 | * Also, if you use the XML builder framework, then you do not ever |
199 | * have to plug your actions into containers manually. The framework | 201 | * have to plug your actions into containers manually. The framework |
200 | * does that for you. | 202 | * does that for you. |
201 | * | 203 | * |
202 | * @see KStdAction | 204 | * @see KStdAction |
203 | * @short Class to encapsulate user-driven action or event | 205 | * @short Class to encapsulate user-driven action or event |
204 | */ | 206 | */ |
205 | class KAction : public QObject | 207 | class KAction : public QObject |
206 | { | 208 | { |
207 | friend class KActionCollection; | 209 | friend class KActionCollection; |
208 | Q_OBJECT | 210 | Q_OBJECT |
209 | Q_PROPERTY( int containerCount READ containerCount ) | 211 | Q_PROPERTY( int containerCount READ containerCount ) |
210 | Q_PROPERTY( QString plainText READ plainText ) | 212 | Q_PROPERTY( QString plainText READ plainText ) |
211 | Q_PROPERTY( QString text READ text WRITE setText ) | 213 | Q_PROPERTY( QString text READ text WRITE setText ) |
212 | Q_PROPERTY( QString shortcut READ shortcutText WRITE setShortcutText ) | 214 | Q_PROPERTY( QString shortcut READ shortcutText WRITE setShortcutText ) |
213 | Q_PROPERTY( bool enabled READ isEnabled WRITE setEnabled ) | 215 | Q_PROPERTY( bool enabled READ isEnabled WRITE setEnabled ) |
214 | Q_PROPERTY( QString group READ group WRITE setGroup ) | 216 | Q_PROPERTY( QString group READ group WRITE setGroup ) |
215 | Q_PROPERTY( QString whatsThis READ whatsThis WRITE setWhatsThis ) | 217 | Q_PROPERTY( QString whatsThis READ whatsThis WRITE setWhatsThis ) |
216 | Q_PROPERTY( QString toolTip READ toolTip WRITE setToolTip ) | 218 | Q_PROPERTY( QString toolTip READ toolTip WRITE setToolTip ) |
217 | Q_PROPERTY( QString icon READ icon WRITE setIcon ) | 219 | Q_PROPERTY( QString icon READ icon WRITE setIcon ) |
218 | public: | 220 | public: |
219 | /** | 221 | /** |
220 | * Constructs an action with text, potential keyboard | 222 | * Constructs an action with text, potential keyboard |
221 | * shortcut, and a SLOT to call when this action is invoked by | 223 | * shortcut, and a SLOT to call when this action is invoked by |
222 | * the user. | 224 | * the user. |
223 | * | 225 | * |
224 | * If you do not want or have a keyboard shortcut, | 226 | * If you do not want or have a keyboard shortcut, |
225 | * set the @p cut param to 0. | 227 | * set the @p cut param to 0. |
226 | * | 228 | * |
227 | * This is the most common KAction used when you do not have a | 229 | * This is the most common KAction used when you do not have a |
228 | * corresponding icon (note that it won't appear in the current version | 230 | * corresponding icon (note that it won't appear in the current version |
229 | * of the "Edit ToolBar" dialog, because an action needs an icon to be | 231 | * of the "Edit ToolBar" dialog, because an action needs an icon to be |
230 | * plugged in a toolbar...). | 232 | * plugged in a toolbar...). |
231 | * | 233 | * |
232 | * @param text The text that will be displayed. | 234 | * @param text The text that will be displayed. |
233 | * @param cut The corresponding keyboard shortcut. | 235 | * @param cut The corresponding keyboard shortcut. |
234 | * @param receiver The SLOT's parent. | 236 | * @param receiver The SLOT's parent. |
235 | * @param slot The SLOT to invoke to execute this action. | 237 | * @param slot The SLOT to invoke to execute this action. |
236 | * @param parent This action's parent. | 238 | * @param parent This action's parent. |
237 | * @param name An internal name for this action. | 239 | * @param name An internal name for this action. |
238 | */ | 240 | */ |
239 | KAction( const QString& text, const KShortcut& cut, | 241 | KAction( const QString& text, const KShortcut& cut, |
240 | const QObject* receiver, const char* slot, | 242 | const QObject* receiver, const char* slot, |
241 | KActionCollection* parent, const char* name ); | 243 | KActionCollection* parent, const char* name ); |
242 | /** | 244 | /** |
243 | * Constructs an action with text, icon, potential keyboard | 245 | * Constructs an action with text, icon, potential keyboard |
244 | * shortcut, and a SLOT to call when this action is invoked by | 246 | * shortcut, and a SLOT to call when this action is invoked by |
245 | * the user. | 247 | * the user. |
246 | * | 248 | * |
247 | * If you do not want or have a keyboard shortcut, set the | 249 | * If you do not want or have a keyboard shortcut, set the |
248 | * @p cut param to 0. | 250 | * @p cut param to 0. |
249 | * | 251 | * |
250 | * This is the other common KAction used. Use it when you | 252 | * This is the other common KAction used. Use it when you |
251 | * @p do have a corresponding icon. | 253 | * @p do have a corresponding icon. |
252 | * | 254 | * |
253 | * @param text The text that will be displayed. | 255 | * @param text The text that will be displayed. |
254 | * @param pix The icon to display. | 256 | * @param pix The icon to display. |
255 | * @param cut The corresponding keyboard shortcut. | 257 | * @param cut The corresponding keyboard shortcut. |
256 | * @param receiver The SLOT's parent. | 258 | * @param receiver The SLOT's parent. |
257 | * @param slot The SLOT to invoke to execute this action. | 259 | * @param slot The SLOT to invoke to execute this action. |
258 | * @param parent This action's parent. | 260 | * @param parent This action's parent. |
259 | * @param name An internal name for this action. | 261 | * @param name An internal name for this action. |
260 | */ | 262 | */ |
261 | 263 | ||
262 | KAction( const QString& text, const QIconSet& pix, const KShortcut& cut, | 264 | KAction( const QString& text, const QIcon& pix, const KShortcut& cut, |
263 | const QObject* receiver, const char* slot, | 265 | const QObject* receiver, const char* slot, |
264 | KActionCollection* parent, const char* name ); | 266 | KActionCollection* parent, const char* name ); |
265 | 267 | ||
266 | /** | 268 | /** |
267 | * Constructs an action with text, icon, potential keyboard | 269 | * Constructs an action with text, icon, potential keyboard |
268 | * shortcut, and a SLOT to call when this action is invoked by | 270 | * shortcut, and a SLOT to call when this action is invoked by |
269 | * the user. The icon is loaded on demand later based on where it | 271 | * the user. The icon is loaded on demand later based on where it |
270 | * is plugged in. | 272 | * is plugged in. |
271 | * | 273 | * |
272 | * If you do not want or have a keyboard shortcut, set the | 274 | * If you do not want or have a keyboard shortcut, set the |
273 | * @p cut param to 0. | 275 | * @p cut param to 0. |
274 | * | 276 | * |
275 | * This is the other common KAction used. Use it when you | 277 | * This is the other common KAction used. Use it when you |
276 | * @p do have a corresponding icon. | 278 | * @p do have a corresponding icon. |
277 | * | 279 | * |
278 | * @param text The text that will be displayed. | 280 | * @param text The text that will be displayed. |
279 | * @param pix The icon to display. | 281 | * @param pix The icon to display. |
280 | * @param cut The corresponding keyboard shortcut (shortcut). | 282 | * @param cut The corresponding keyboard shortcut (shortcut). |
281 | * @param receiver The SLOT's parent. | 283 | * @param receiver The SLOT's parent. |
282 | * @param slot The SLOT to invoke to execute this action. | 284 | * @param slot The SLOT to invoke to execute this action. |
283 | * @param parent This action's parent. | 285 | * @param parent This action's parent. |
284 | * @param name An internal name for this action. | 286 | * @param name An internal name for this action. |
285 | */ | 287 | */ |
286 | KAction( const QString& text, const QString& pix, const KShortcut& cut, | 288 | KAction( const QString& text, const QString& pix, const KShortcut& cut, |
287 | const QObject* receiver, const char* slot, | 289 | const QObject* receiver, const char* slot, |
288 | KActionCollection* parent, const char* name ); | 290 | KActionCollection* parent, const char* name ); |
289 | 291 | ||
290 | /** | 292 | /** |
291 | * The same as the above constructor, but with a KGuiItem providing | 293 | * The same as the above constructor, but with a KGuiItem providing |
292 | * the text and icon. | 294 | * the text and icon. |
293 | * | 295 | * |
294 | * @param item The KGuiItem with the label and (optional) icon. | 296 | * @param item The KGuiItem with the label and (optional) icon. |
295 | */ | 297 | */ |
296 | KAction( const KGuiItem& item, const KShortcut& cut, | 298 | KAction( const KGuiItem& item, const KShortcut& cut, |
297 | const QObject* receiver, const char* slot, | 299 | const QObject* receiver, const char* slot, |
298 | KActionCollection* parent, const char* name ); | 300 | KActionCollection* parent, const char* name ); |
299 | /** | 301 | /** |
300 | * @obsolete | 302 | * @obsolete |
301 | */ | 303 | */ |
302 | KAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0, const char* name = 0 ); | 304 | KAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0, const char* name = 0 ); |
303 | /** | 305 | /** |
304 | * @obsolete | 306 | * @obsolete |
305 | */ | 307 | */ |
306 | KAction( const QString& text, const KShortcut& cut, | 308 | KAction( const QString& text, const KShortcut& cut, |
307 | const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 ); | 309 | const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 ); |
308 | /** | 310 | /** |
309 | * @obsolete | 311 | * @obsolete |
310 | */ | 312 | */ |
311 | KAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(), | 313 | KAction( const QString& text, const QIcon& pix, const KShortcut& cut = KShortcut(), |
312 | QObject* parent = 0, const char* name = 0 ); | 314 | QObject* parent = 0, const char* name = 0 ); |
313 | /** | 315 | /** |
314 | * @obsolete | 316 | * @obsolete |
315 | */ | 317 | */ |
316 | KAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(), | 318 | KAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(), |
317 | QObject* parent = 0, const char* name = 0 ); | 319 | QObject* parent = 0, const char* name = 0 ); |
318 | /** | 320 | /** |
319 | * @obsolete | 321 | * @obsolete |
320 | */ | 322 | */ |
321 | KAction( const QString& text, const QIconSet& pix, const KShortcut& cut, | 323 | KAction( const QString& text, const QIcon& pix, const KShortcut& cut, |
322 | const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 ); | 324 | const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 ); |
323 | /** | 325 | /** |
324 | * @obsolete | 326 | * @obsolete |
325 | */ | 327 | */ |
326 | KAction( const QString& text, const QString& pix, const KShortcut& cut, | 328 | KAction( const QString& text, const QString& pix, const KShortcut& cut, |
327 | const QObject* receiver, const char* slot, QObject* parent, | 329 | const QObject* receiver, const char* slot, QObject* parent, |
328 | const char* name = 0 ); | 330 | const char* name = 0 ); |
329 | /** | 331 | /** |
330 | * @obsolete | 332 | * @obsolete |
331 | */ | 333 | */ |
332 | KAction( QObject* parent = 0, const char* name = 0 ); | 334 | KAction( QObject* parent = 0, const char* name = 0 ); |
333 | 335 | ||
334 | /** | 336 | /** |
335 | * Standard destructor | 337 | * Standard destructor |
336 | */ | 338 | */ |
337 | virtual ~KAction(); | 339 | virtual ~KAction(); |
338 | 340 | ||
339 | /** | 341 | /** |
340 | * "Plug" or insert this action into a given widget. | 342 | * "Plug" or insert this action into a given widget. |
341 | * | 343 | * |
342 | * This will | 344 | * This will |
343 | * typically be a menu or a toolbar. From this point on, you will | 345 | * typically be a menu or a toolbar. From this point on, you will |
344 | * never need to directly manipulate the item in the menu or | 346 | * never need to directly manipulate the item in the menu or |
345 | * toolbar. You do all enabling/disabling/manipulation directly | 347 | * toolbar. You do all enabling/disabling/manipulation directly |
346 | * with your KAction object. | 348 | * with your KAction object. |
347 | * | 349 | * |
348 | * @param w The GUI element to display this action | 350 | * @param w The GUI element to display this action |
349 | */ | 351 | */ |
350 | virtual int plug( QWidget *w, int index = -1 ); | 352 | virtual int plug( QWidget *w, int index = -1 ); |
351 | 353 | ||
352 | /** | 354 | /** |
353 | * @deprecated. Shouldn't be used. No substitute available. | 355 | * @deprecated. Shouldn't be used. No substitute available. |
354 | * | 356 | * |
355 | * "Plug" or insert this action into a given KAccel. | 357 | * "Plug" or insert this action into a given KAccel. |
356 | * | 358 | * |
357 | * @param accel The KAccel collection which holds this accel | 359 | * @param accel The KAccel collection which holds this accel |
358 | * @param configurable If the shortcut is configurable via | 360 | * @param configurable If the shortcut is configurable via |
359 | * the KAccel configuration dialog (this is somehow deprecated since | 361 | * the KAccel configuration dialog (this is somehow deprecated since |
360 | * there is now a KAction key configuration dialog). | 362 | * there is now a KAction key configuration dialog). |
361 | */ | 363 | */ |
362 | virtual void plugAccel(KAccel *accel, bool configurable = true); | 364 | virtual void plugAccel(KAccel *accel, bool configurable = true); |
363 | 365 | ||
364 | /** | 366 | /** |
365 | * "Unplug" or remove this action from a given widget. | 367 | * "Unplug" or remove this action from a given widget. |
366 | * | 368 | * |
367 | * This will typically be a menu or a toolbar. This is rarely | 369 | * This will typically be a menu or a toolbar. This is rarely |
368 | * used in "normal" application. Typically, it would be used if | 370 | * used in "normal" application. Typically, it would be used if |
369 | * your application has several views or modes, each with a | 371 | * your application has several views or modes, each with a |
370 | * completely different menu structure. If you simply want to | 372 | * completely different menu structure. If you simply want to |
371 | * disable an action for a given period, use @ref setEnabled() | 373 | * disable an action for a given period, use @ref setEnabled() |
372 | * instead. | 374 | * instead. |
373 | * | 375 | * |
374 | * @param w Remove the action from this GUI element. | 376 | * @param w Remove the action from this GUI element. |
375 | */ | 377 | */ |
376 | virtual void unplug( QWidget *w ); | 378 | virtual void unplug( QWidget *w ); |
377 | 379 | ||
378 | /** | 380 | /** |
379 | * @deprecated. Complement method to plugAccel(). | 381 | * @deprecated. Complement method to plugAccel(). |
380 | * Disconnect this action from the KAccel. | 382 | * Disconnect this action from the KAccel. |
381 | */ | 383 | */ |
382 | virtual void unplugAccel(); | 384 | virtual void unplugAccel(); |
383 | 385 | ||
384 | /** | 386 | /** |
385 | * returns whether the action is plugged into any container widget or not. | 387 | * returns whether the action is plugged into any container widget or not. |
386 | * @since 3.1 | 388 | * @since 3.1 |
387 | */ | 389 | */ |
388 | virtual bool isPlugged() const; | 390 | virtual bool isPlugged() const; |
389 | 391 | ||
390 | /** | 392 | /** |
391 | * returns whether the action is plugged into the given container | 393 | * returns whether the action is plugged into the given container |
392 | */ | 394 | */ |
393 | bool isPlugged( const QWidget *container ) const; | 395 | bool isPlugged( const QWidget *container ) const; |
394 | 396 | ||
395 | /** | 397 | /** |
396 | * returns whether the action is plugged into the given container with the given, container specific, id (often | 398 | * returns whether the action is plugged into the given container with the given, container specific, id (often |
397 | * menu or toolbar id ) . | 399 | * menu or toolbar id ) . |
398 | */ | 400 | */ |
399 | virtual bool isPlugged( const QWidget *container, int id ) const; | 401 | virtual bool isPlugged( const QWidget *container, int id ) const; |
400 | 402 | ||
401 | /** | 403 | /** |
402 | * returns whether the action is plugged into the given container with the given, container specific, representative | 404 | * returns whether the action is plugged into the given container with the given, container specific, representative |
403 | * container widget item. | 405 | * container widget item. |
404 | */ | 406 | */ |
405 | virtual bool isPlugged( const QWidget *container, const QWidget *_representative ) const; | 407 | virtual bool isPlugged( const QWidget *container, const QWidget *_representative ) const; |
406 | 408 | ||
407 | QWidget* container( int index ) const; | 409 | QWidget* container( int index ) const; |
408 | int itemId( int index ) const; | 410 | int itemId( int index ) const; |
409 | QWidget* representative( int index ) const; | 411 | QWidget* representative( int index ) const; |
410 | int containerCount() const; | 412 | int containerCount() const; |
411 | /// @since 3.1 | 413 | /// @since 3.1 |
412 | uint kaccelCount() const; | 414 | uint kaccelCount() const; |
413 | 415 | ||
414 | virtual bool hasIcon() const; | 416 | virtual bool hasIcon() const; |
415 | #ifndef KDE_NO_COMPAT | 417 | #ifndef KDE_NO_COMPAT |
416 | bool hasIconSet() const { return hasIcon(); } | 418 | bool hasIconSet() const { return hasIcon(); } |
417 | #endif | 419 | #endif |
418 | virtual QString plainText() const; | 420 | virtual QString plainText() const; |
419 | 421 | ||
420 | /** | 422 | /** |
421 | * Get the text associated with this action. | 423 | * Get the text associated with this action. |
422 | */ | 424 | */ |
423 | virtual QString text() const; | 425 | virtual QString text() const; |
424 | 426 | ||
425 | /** | 427 | /** |
426 | * Get the keyboard shortcut associated with this action. | 428 | * Get the keyboard shortcut associated with this action. |
427 | */ | 429 | */ |
428 | virtual const KShortcut& shortcut() const; | 430 | virtual const KShortcut& shortcut() const; |
429 | /** | 431 | /** |
430 | * Get the default shortcut for this action. | 432 | * Get the default shortcut for this action. |
431 | */ | 433 | */ |
432 | virtual const KShortcut& shortcutDefault() const; | 434 | virtual const KShortcut& shortcutDefault() const; |
433 | 435 | ||
434 | // These two methods are for Q_PROPERTY | 436 | // These two methods are for Q_PROPERTY |
435 | QString shortcutText() const; | 437 | QString shortcutText() const; |
436 | void setShortcutText( const QString& ); | 438 | void setShortcutText( const QString& ); |
437 | 439 | ||
438 | /** | 440 | /** |
439 | * Returns true if this action is enabled. | 441 | * Returns true if this action is enabled. |
440 | */ | 442 | */ |
441 | virtual bool isEnabled() const; | 443 | virtual bool isEnabled() const; |
442 | 444 | ||
443 | /** | 445 | /** |
444 | * Returns true if this action's shortcut is configurable. | 446 | * Returns true if this action's shortcut is configurable. |
445 | */ | 447 | */ |
446 | virtual bool isShortcutConfigurable() const; | 448 | virtual bool isShortcutConfigurable() const; |
447 | 449 | ||
448 | virtual QString group() const; | 450 | virtual QString group() const; |
449 | 451 | ||
450 | /** | 452 | /** |
451 | * Get the What's this text for the action. | 453 | * Get the What's this text for the action. |
452 | */ | 454 | */ |
453 | virtual QString whatsThis() const; | 455 | virtual QString whatsThis() const; |
454 | 456 | ||
455 | /** | 457 | /** |
456 | * Get the tooltip text for the action. | 458 | * Get the tooltip text for the action. |
457 | */ | 459 | */ |
458 | virtual QString toolTip() const; | 460 | virtual QString toolTip() const; |
459 | 461 | ||
460 | /** | 462 | /** |
461 | * Get the QIconSet from which the icons used to display this action will | 463 | * Get the QIconSet from which the icons used to display this action will |
462 | * be chosen. | 464 | * be chosen. |
463 | */ | 465 | */ |
464 | virtual QIconSet iconSet( KIcon::Group group, int size=0 ) const; | 466 | virtual QIcon iconSet( KIcon::Group group, int size=0 ) const; |
465 | 467 | ||
466 | #ifndef KDE_NO_COMPAT | 468 | #ifndef KDE_NO_COMPAT |
467 | QIconSet iconSet() const | 469 | QIcon iconSet() const |
468 | { | 470 | { |
469 | return iconSet( KIcon::Small ); | 471 | return iconSet( KIcon::Small ); |
470 | } | 472 | } |
471 | #endif | 473 | #endif |
472 | 474 | ||
473 | virtual QString icon() const; | 475 | virtual QString icon() const; |
474 | 476 | ||
475 | KActionCollection *parentCollection() const; | 477 | KActionCollection *parentCollection() const; |
476 | 478 | ||
477 | /** | 479 | /** |
478 | * @internal | 480 | * @internal |
479 | * Generate a toolbar button id. Made public for reimplementations. | 481 | * Generate a toolbar button id. Made public for reimplementations. |
480 | */ | 482 | */ |
481 | static int getToolButtonID(); | 483 | static int getToolButtonID(); |
482 | 484 | ||
483 | 485 | ||
484 | void unplugAll(); | 486 | void unplugAll(); |
485 | 487 | ||
486 | public slots: | 488 | public slots: |
487 | /** | 489 | /** |
488 | * Sets the text associated with this action. The text is used for menu | 490 | * Sets the text associated with this action. The text is used for menu |
489 | * and toolbar labels etc. | 491 | * and toolbar labels etc. |
490 | */ | 492 | */ |
491 | virtual void setText(const QString &text); | 493 | virtual void setText(const QString &text); |
492 | 494 | ||
493 | /** | 495 | /** |
494 | * Sets the keyboard shortcut associated with this action. | 496 | * Sets the keyboard shortcut associated with this action. |
495 | */ | 497 | */ |
496 | virtual bool setShortcut( const KShortcut& ); | 498 | virtual bool setShortcut( const KShortcut& ); |
497 | 499 | ||
498 | virtual void setGroup( const QString& ); | 500 | virtual void setGroup( const QString& ); |
499 | 501 | ||
500 | /** | 502 | /** |
501 | * Sets the What's this text for the action. This text will be displayed when | 503 | * Sets the What's this text for the action. This text will be displayed when |
502 | * a widget that has been created by plugging this action into a container | 504 | * a widget that has been created by plugging this action into a container |
503 | * is clicked on in What's this mode. | 505 | * is clicked on in What's this mode. |
504 | * | 506 | * |
505 | * The What's this text can include QML markup as well as raw text. | 507 | * The What's this text can include QML markup as well as raw text. |
506 | */ | 508 | */ |
507 | virtual void setWhatsThis( const QString& text ); | 509 | virtual void setWhatsThis( const QString& text ); |
508 | 510 | ||
509 | /** | 511 | /** |
510 | * Sets the tooltip text for the action. | 512 | * Sets the tooltip text for the action. |
511 | * This will be used as a tooltip for a toolbar button, as a | 513 | * This will be used as a tooltip for a toolbar button, as a |
512 | * statusbar help-text for a menu item, and it also appears | 514 | * statusbar help-text for a menu item, and it also appears |
513 | * in the toolbar editor, to describe the action. | 515 | * in the toolbar editor, to describe the action. |
514 | */ | 516 | */ |
515 | virtual void setToolTip( const QString& ); | 517 | virtual void setToolTip( const QString& ); |
516 | 518 | ||
517 | /** | 519 | /** |
518 | * Sets the QIconSet from which the icons used to display this action will | 520 | * Sets the QIconSet from which the icons used to display this action will |
519 | * be chosen. | 521 | * be chosen. |
520 | */ | 522 | */ |
521 | virtual void setIconSet( const QIconSet &iconSet ); | 523 | virtual void setIconSet( const QIcon &iconSet ); |
522 | 524 | ||
523 | virtual void setIcon( const QString& icon ); | 525 | virtual void setIcon( const QString& icon ); |
524 | 526 | ||
525 | /** | 527 | /** |
526 | * Enables or disables this action. All uses of this action (eg. in menus | 528 | * Enables or disables this action. All uses of this action (eg. in menus |
527 | * or toolbars) will be updated to reflect the state of the action. | 529 | * or toolbars) will be updated to reflect the state of the action. |
528 | */ | 530 | */ |
529 | virtual void setEnabled(bool enable); | 531 | virtual void setEnabled(bool enable); |
530 | 532 | ||
531 | /** | 533 | /** |
532 | * Indicate whether the user may configure the action's shortcut. | 534 | * Indicate whether the user may configure the action's shortcut. |
533 | */ | 535 | */ |
534 | virtual void setShortcutConfigurable( bool ); | 536 | virtual void setShortcutConfigurable( bool ); |
535 | 537 | ||
536 | /** | 538 | /** |
537 | * Emulate user's interaction programmatically, by activating the action. | 539 | * Emulate user's interaction programmatically, by activating the action. |
538 | * The implementation simply emits activated(). | 540 | * The implementation simply emits activated(). |
539 | */ | 541 | */ |
540 | virtual void activate(); | 542 | virtual void activate(); |
541 | 543 | ||
542 | protected slots: | 544 | protected slots: |
543 | virtual void slotDestroyed(); | 545 | virtual void slotDestroyed(); |
544 | virtual void slotKeycodeChanged(); | 546 | virtual void slotKeycodeChanged(); |
545 | virtual void slotActivated(); | 547 | virtual void slotActivated(); |
546 | 548 | ||
547 | protected: | 549 | protected: |
548 | KToolBar* toolBar( int index ) const; | 550 | KToolBar* toolBar( int index ) const; |
549 | QPopupMenu* popupMenu( int index ) const; | 551 | Q3PopupMenu* popupMenu( int index ) const; |
550 | void removeContainer( int index ); | 552 | void removeContainer( int index ); |
551 | int findContainer( const QWidget* widget ) const; | 553 | int findContainer( const QWidget* widget ) const; |
552 | void plugMainWindowAccel( QWidget *w ); | 554 | void plugMainWindowAccel( QWidget *w ); |
553 | 555 | ||
554 | void addContainer( QWidget* parent, int id ); | 556 | void addContainer( QWidget* parent, int id ); |
555 | void addContainer( QWidget* parent, QWidget* representative ); | 557 | void addContainer( QWidget* parent, QWidget* representative ); |
556 | 558 | ||
557 | virtual void updateShortcut( int i ); | 559 | virtual void updateShortcut( int i ); |
558 | virtual void updateShortcut( QPopupMenu* menu, int id ); | 560 | virtual void updateShortcut( Q3PopupMenu* menu, int id ); |
559 | virtual void updateGroup( int id ); | 561 | virtual void updateGroup( int id ); |
560 | virtual void updateText(int i ); | 562 | virtual void updateText(int i ); |
561 | virtual void updateEnabled(int i); | 563 | virtual void updateEnabled(int i); |
562 | virtual void updateIconSet(int i); | 564 | virtual void updateIconSet(int i); |
563 | virtual void updateIcon( int i); | 565 | virtual void updateIcon( int i); |
564 | virtual void updateToolTip( int id ); | 566 | virtual void updateToolTip( int id ); |
565 | virtual void updateWhatsThis( int i ); | 567 | virtual void updateWhatsThis( int i ); |
566 | 568 | ||
567 | KActionCollection *m_parentCollection; | 569 | KActionCollection *m_parentCollection; |
568 | QString whatsThisWithIcon() const; | 570 | QString whatsThisWithIcon() const; |
569 | 571 | ||
570 | signals: | 572 | signals: |
571 | void activated(); | 573 | void activated(); |
572 | void enabled( bool ); | 574 | void enabled( bool ); |
573 | 575 | ||
574 | private: | 576 | private: |
575 | void initPrivate( const QString& text, const KShortcut& cut, | 577 | void initPrivate( const QString& text, const KShortcut& cut, |
576 | const QObject* receiver, const char* slot ); | 578 | const QObject* receiver, const char* slot ); |
577 | KAccel* kaccelCurrent(); | 579 | KAccel* kaccelCurrent(); |
578 | bool initShortcut( const KShortcut& ); | 580 | bool initShortcut( const KShortcut& ); |
579 | void plugShortcut(); | 581 | void plugShortcut(); |
580 | bool updateKAccelShortcut( KAccel* kaccel ); | 582 | bool updateKAccelShortcut( KAccel* kaccel ); |
581 | void insertKAccel( KAccel* ); | 583 | void insertKAccel( KAccel* ); |
582 | /** @internal To be used exclusively by KActionCollection::removeWidget(). */ | 584 | /** @internal To be used exclusively by KActionCollection::removeWidget(). */ |
583 | void removeKAccel( KAccel* ); | 585 | void removeKAccel( KAccel* ); |
584 | 586 | ||
585 | #ifndef KDE_NO_COMPAT | 587 | #ifndef KDE_NO_COMPAT |
586 | public: | 588 | public: |
587 | /** | 589 | /** |
588 | * @deprecated. Use shortcut(). | 590 | * @deprecated. Use shortcut(). |
589 | * Get the keyboard accelerator associated with this action. | 591 | * Get the keyboard accelerator associated with this action. |
590 | */ | 592 | */ |
591 | int accel() const; | 593 | int accel() const; |
592 | 594 | ||
593 | QString statusText() const | 595 | QString statusText() const |
594 | { return toolTip(); } | 596 | { return toolTip(); } |
595 | 597 | ||
596 | /** | 598 | /** |
597 | * @deprecated. Use setShortcut(). | 599 | * @deprecated. Use setShortcut(). |
598 | * Sets the keyboard accelerator associated with this action. | 600 | * Sets the keyboard accelerator associated with this action. |
599 | */ | 601 | */ |
600 | void setAccel( int key ); | 602 | void setAccel( int key ); |
601 | 603 | ||
602 | /** | 604 | /** |
603 | * @deprecated. Use setToolTip instead (they do the same thing now). | 605 | * @deprecated. Use setToolTip instead (they do the same thing now). |
604 | */ | 606 | */ |
605 | void setStatusText( const QString &text ) | 607 | void setStatusText( const QString &text ) |
606 | { setToolTip( text ); } | 608 | { setToolTip( text ); } |
607 | 609 | ||
608 | /** | 610 | /** |
609 | * @deprecated. for backwards compatibility. | 611 | * @deprecated. for backwards compatibility. |
610 | */ | 612 | */ |
611 | int menuId( int i ) { return itemId( i ); } | 613 | int menuId( int i ) { return itemId( i ); } |
612 | #endif // !KDE_NO_COMPAT | 614 | #endif // !KDE_NO_COMPAT |
613 | 615 | ||
614 | protected: | 616 | protected: |
615 | virtual void virtual_hook( int id, void* data ); | 617 | virtual void virtual_hook( int id, void* data ); |
616 | private: | 618 | private: |
617 | class KActionPrivate; | 619 | class KActionPrivate; |
618 | KActionPrivate *d; | 620 | KActionPrivate *d; |
619 | }; | 621 | }; |
620 | 622 | ||
621 | #include <kactioncollection.h> | 623 | #include <kactioncollection.h> |
622 | #include <kactionclasses.h> | 624 | #include <kactionclasses.h> |
623 | 625 | ||
624 | #endif | 626 | #endif |