1QAction(3qt) QAction(3qt)
2
6 QAction - Abstract user interface action that can appear both in menus
7 and tool bars
8
10 #include <qaction.h>
11 Inherits QObject.
13 Inherited by QActionGroup.
15 Public Members
17 QAction ( QObject * parent, const char * name = 0 )
18 QAction ( const QString & menuText, QKeySequence accel, QObject *
19 parent, const char * name = 0 )
20 QAction ( const QIconSet & icon, const QString & menuText, QKeySequence
21 accel, QObject * parent, const char * name = 0 )
22 QAction ( const QString & text, const QIconSet & icon, const QString &
23 menuText, QKeySequence accel, QObject * parent, const char * name =
24 0, bool toggle = FALSE ) (obsolete)
25 QAction ( const QString & text, const QString & menuText, QKeySequence
26 accel, QObject * parent, const char * name = 0, bool toggle = FALSE
27 ) (obsolete)
28 QAction ( QObject * parent, const char * name, bool toggle )
29 (obsolete)
30 ~QAction ()
31 virtual void setIconSet ( const QIconSet & )
32 QIconSet iconSet () const
33 virtual void setText ( const QString & )
34 QString text () const
35 virtual void setMenuText ( const QString & )
36 QString menuText () const
37 virtual void setToolTip ( const QString & )
38 QString toolTip () const
39 virtual void setStatusTip ( const QString & )
40 QString statusTip () const
41 virtual void setWhatsThis ( const QString & )
42 QString whatsThis () const
43 virtual void setAccel ( const QKeySequence & key )
44 QKeySequence accel () const
45 virtual void setToggleAction ( bool )
46 bool isToggleAction () const
47 bool isOn () const
48 bool isEnabled () const
49 bool isVisible () const
50 virtual bool addTo ( QWidget * w )
51 virtual bool removeFrom ( QWidget * w )
52 Public Slots
54 void activate ()
55 void toggle ()
56 virtual void setOn ( bool )
57 virtual void setEnabled ( bool )
58 void setDisabled ( bool disable )
59 void setVisible ( bool )
60 Signals
62 void activated ()
63 void toggled ( bool on )
64 Properties
66 QKeySequence accel - the action's accelerator key
67 bool enabled - whether the action is enabled
68 QIconSet iconSet - the action's icon
69 QString menuText - the action's menu text
70 bool on - whether a toggle action is on
71 QString statusTip - the action's status tip
72 QString text - the action's descriptive text
73 bool toggleAction - whether the action is a toggle action
74 QString toolTip - the action's tool tip
75 bool visible - whether the action can be seen (e.g. in menus and
76 toolbars)
77 QString whatsThis - the action's "What's This?" help text
78 Protected Members
80 virtual void addedTo ( QWidget * actionWidget, QWidget * container )
81 virtual void addedTo ( int index, QPopupMenu * menu )
82
84 The QAction class provides an abstract user interface action that can
85 appear both in menus and tool bars.
86 In GUI applications many commands can be invoked via a menu option, a
88 toolbar button and a keyboard accelerator. Since the same action must
89 be performed regardless of how the action was invoked, and since the
90 menu and toolbar should be kept in sync, it is useful to represent a
91 command as an action. An action can be added to a menu and a toolbar
92 and will automatically keep them in sync. For example, if the user
93 presses a Bold toolbar button the Bold menu item will automatically be
94 checked.
95 A QAction may contain an icon, a menu text, an accelerator, a status
97 text, a whats this text and a tool tip. Most of these can be set in the
98 constructor. They can also be set independently with setIconSet(),
99 setText(), setMenuText(), setToolTip(), setStatusTip(), setWhatsThis()
100 and setAccel().
101 An action may be a toggle action e.g. a Bold toolbar button, or a
103 command action, e.g. 'Open File' to invoke an open file dialog. Toggle
104 actions emit the toggled() signal when their state changes. Both
105 command and toggle actions emit the activated() signal when they are
106 invoked. Use setToggleAction() to set an action's toggled status. To
107 see if an action is a toggle action use isToggleAction(). A toggle
108 action may be "on", isOn() returns TRUE, or "off", isOn() returns
109 FALSE.
110 Actions are added to widgets (menus or toolbars) using addTo(), and
112 removed using removeFrom().
113 Once a QAction has been created it should be added to the relevant menu
115 and toolbar and then connected to the slot which will perform the
116 action. For example:
117 fileOpenAction = new QAction( QPixmap( fileopen ), "&Open...",
119 CTRL+Key_O, this, "open" );
120 connect( fileOpenAction, SIGNAL( activated() ) , this, SLOT( choose() ) );
121 We create a "File Save" action with a menu text of "&Save" and Ctrl+S
123 as the keyboard accelerator. We connect the fileSaveAction's
124 activated() signal to our own save() slot. Note that at this point
125 there is no menu or toolbar action, we'll add them next:
126 QToolBar * fileTools = new QToolBar( this, "file operations" );
128 fileSaveAction->addTo( fileTools );
130 QPopupMenu * file = new QPopupMenu( this );
132 menuBar()->insertItem( "&File", file );
133 fileSaveAction->addTo( file );
135 We create a toolbar and add our fileSaveAction to it. Similarly we
137 create a menu, add a top-level menu item, and add our fileSaveAction.
138 We recommend that actions are created as children of the window that
140 they are used in. In most cases actions will be children of the
141 application's main window.
142 To prevent recursion, don't create an action as a child of a widget
144 that the action is later added to.
145 See also Main Window and Related Classes and Basic Widgets.
147
150 Constructs an action called name with parent parent.
151 If parent is a QActionGroup, the new action inserts itself into parent.
153 For accelerators and status tips to work, parent must either be a
155 widget, or an action group whose parent is a widget.
156 Warning: To prevent recursion, don't create an action as a child of a
158 widget that the action is later added to.
159
161 parent, const char * name = 0 )
162 This constructor results in an icon-less action with the the menu text
163 menuText and keyboard accelerator accel. It is a child of parent and
164 called name.
165 If parent is a QActionGroup, the action automatically becomes a member
167 of it.
168 For accelerators and status tips to work, parent must either be a
170 widget, or an action group whose parent is a widget.
171 The action uses a stripped version of menuText (e.g. "&Menu Option..."
173 becomes "Menu Option") as descriptive text for toolbuttons. You can
174 override this by setting a specific description with setText(). The
175 same text and accel will be used for tool tips and status tips unless
176 you provide text for these using setToolTip() and setStatusTip().
177 Call setToggleAction(TRUE) to make the action a toggle action.
179 Warning: To prevent recursion, don't create an action as a child of a
181 widget that the action is later added to.
182
184 QKeySequence accel, QObject * parent, const char * name = 0 )
185 This constructor creates an action with the following properties: the
186 icon or iconset icon, the menu text menuText and keyboard accelerator
187 accel. It is a child of parent and called name.
188 If parent is a QActionGroup, the action automatically becomes a member
190 of it.
191 For accelerators and status tips to work, parent must either be a
193 widget, or an action group whose parent is a widget.
194 The action uses a stripped version of menuText (e.g. "&Menu Option..."
196 becomes "Menu Option") as descriptive text for toolbuttons. You can
197 override this by setting a specific description with setText(). The
198 same text and accel will be used for tool tips and status tips unless
199 you provide text for these using setToolTip() and setStatusTip().
200 Call setToggleAction(TRUE) to make the action a toggle action.
202 Warning: To prevent recursion, don't create an action as a child of a
204 widget that the action is later added to.
205
207 & menuText, QKeySequence accel, QObject * parent, const char * name =
208 0, bool toggle = FALSE )
209 This function is obsolete. It is provided to keep old source working.
210 We strongly advise against using it in new code.
211 This constructor creates an action with the following properties: the
213 description text, the icon or iconset icon, the menu text menuText and
214 keyboard accelerator accel. It is a child of parent and called name. If
215 toggle is TRUE the action will be a toggle action, otherwise it will be
216 a command action.
217 If parent is a QActionGroup, the action automatically becomes a member
219 of it.
220 For accelerators and status tips to work, parent must either be a
222 widget, or an action group whose parent is a widget.
223 The text and accel will be used for tool tips and status tips unless
225 you provide specific text for these using setToolTip() and
226 setStatusTip().
227
229 QKeySequence accel, QObject * parent, const char * name = 0, bool
230 toggle = FALSE )
231 This function is obsolete. It is provided to keep old source working.
232 We strongly advise against using it in new code.
233 This constructor results in an icon-less action with the description
235 text, the menu text menuText and the keyboard accelerator accel. Its
236 parent is parent and it is called name. If toggle is TRUE the action
237 will be a toggle action, otherwise it will be a command action.
238 The action automatically becomes a member of parent if parent is a
240 QActionGroup.
241 For accelerators and status tips to work, parent must either be a
243 widget, or an action group whose parent is a widget.
244 The text and accel will be used for tool tips and status tips unless
246 you provide specific text for these using setToolTip() and
247 setStatusTip().
248
250 This function is obsolete. It is provided to keep old source working.
251 We strongly advise against using it in new code.
252 Constructs an action called name with parent parent.
254 If toggle is TRUE the action will be a toggle action, otherwise it will
256 be a command action.
257 If parent is a QActionGroup, the new action inserts itself into parent.
259 For accelerators and status tips to work, parent must either be a
261 widget, or an action group whose parent is a widget.
262
264 Destroys the object and frees allocated resources.
265
267 Returns the action's accelerator key. See the "accel" property for
268 details.
269
271 Activates the action and executes all connected slots. This only works
272 for actions that are not toggle action.
273 See also toggle().
275
277 This signal is emitted when an action is activated by the user, e.g.
278 when the user clicks a menu option or a toolbar button or presses an
279 action's accelerator key combination.
280 Connect to this signal for command actions. Connect to the toggled()
282 signal for toggle actions.
283 Examples:
285
287 Adds this action to widget w.
288 Currently actions may be added to QToolBar and QPopupMenu widgets.
290 An action added to a tool bar is automatically displayed as a tool
292 button; an action added to a pop up menu appears as a menu option.
293 addTo() returns TRUE if the action was added successfully and FALSE
295 otherwise. (If w is not a QToolBar or QPopupMenu the action will not be
296 added and FALSE will be returned.)
297 See also removeFrom().
299 Examples:
301 Reimplemented in QActionGroup.
303
305 protected]
306 This function is called from the addTo() function when it has created a
307 widget (actionWidget) for the action in the container.
308
310 This is an overloaded member function, provided for convenience. It
311 behaves essentially like the above function.
312 This function is called from the addTo() function when it has created a
314 menu item at the index position index in the popup menu menu.
315
317 Returns the action's icon. See the "iconSet" property for details.
318
320 Returns TRUE if the action is enabled; otherwise returns FALSE. See the
321 "enabled" property for details.
322
324 Returns TRUE if a toggle action is on; otherwise returns FALSE. See the
325 "on" property for details.
326
328 Returns TRUE if the action is a toggle action; otherwise returns FALSE.
329 See the "toggleAction" property for details.
330
332 Returns TRUE if the action can be seen (e.g. in menus and toolbars);
333 otherwise returns FALSE. See the "visible" property for details.
334
336 Returns the action's menu text. See the "menuText" property for
337 details.
338
340 Removes the action from widget w.
341 Returns TRUE if the action was removed successfully; otherwise returns
343 FALSE.
344 See also addTo().
346
348 Sets the action's accelerator key to key. See the "accel" property for
349 details.
350
352 Disables the action if disable is TRUE; otherwise enables the action.
353 See the enabled documentation for more information.
355
357 Sets whether the action is enabled. See the "enabled" property for
358 details.
359
361 Sets the action's icon. See the "iconSet" property for details.
362
364 Sets the action's menu text. See the "menuText" property for details.
365
367 Sets whether a toggle action is on. See the "on" property for details.
368
370 Sets the action's status tip. See the "statusTip" property for details.
371
373 Sets the action's descriptive text. See the "text" property for
374 details.
375
377 Sets whether the action is a toggle action. See the "toggleAction"
378 property for details.
379
381 Sets the action's tool tip. See the "toolTip" property for details.
382
384 Sets whether the action can be seen (e.g. in menus and toolbars). See
385 the "visible" property for details.
386
388 Sets the action's "What's This?" help text. See the "whatsThis"
389 property for details.
390
392 Returns the action's status tip. See the "statusTip" property for
393 details.
394
396 Returns the action's descriptive text. See the "text" property for
397 details.
398
400 Toggles the state of a toggle action.
401 See also on, activate(), toggled(), and toggleAction.
403
405 This signal is emitted when a toggle action changes state; command
406 actions and QActionGroups don't emit toggled().
407 The on argument denotes the new state: If on is TRUE the toggle action
409 is switched on, and if on is FALSE the toggle action is switched off.
410 To trigger a user command depending on whether a toggle action has been
412 switched on or off connect it to a slot that takes a bool to indicate
413 the state, e.g.
414 QMainWindow * window = new QMainWindow;
416 QAction * labelonoffaction = new QAction( window, "labelonoff" );
418 QObject::connect( labelonoffaction, SIGNAL( toggled( bool ) ),
420 window, SLOT( setUsesTextLabel( bool ) ) );
421 See also activated(), toggleAction, and on.
423 Example: action/toggleaction/toggleaction.cpp.
425
427 Returns the action's tool tip. See the "toolTip" property for details.
428
430 Returns the action's "What's This?" help text. See the "whatsThis"
431 property for details.
432 Property Documentation
435 This property holds the action's accelerator key.
436 The keycodes can be found in Qt::Key and Qt::Modifier. There is no
438 default accelerator key.
439 Set this property's value with setAccel() and get this property's value
441 with accel().
442
444 This property holds whether the action is enabled.
445 Disabled actions can't be chosen by the user. They don't disappear from
447 the menu/tool bar but are displayed in a way which indicates that they
448 are unavailable, e.g. they might be displayed grayed out.
449 What's this? help on disabled actions is still available provided the
451 QAction::whatsThis property is set.
452 Set this property's value with setEnabled() and get this property's
454 value with isEnabled().
455
457 This property holds the action's icon.
458 The icon is used as the tool button icon and in the menu to the left of
460 the menu text. There is no default icon.
461 If a null icon (QIconSet::isNull() is passed into this function, the
463 icon of the action is cleared.
464 (See the action/toggleaction/toggleaction.cpp example.)
466 Set this property's value with setIconSet() and get this property's
468 value with iconSet().
469
471 This property holds the action's menu text.
472 If the action is added to a menu the menu option will consist of the
474 icon (if there is one), the menu text and the accelerator (if there is
475 one). If the menu text is not explicitly set in the constructor or by
476 using setMenuText() the action's description text will be used as the
477 menu text. There is no default menu text.
478 See also text.
480 Set this property's value with setMenuText() and get this property's
482 value with menuText().
483
485 This property holds whether a toggle action is on.
486 This property is always on (TRUE) for command actions and
488 QActionGroups; setOn() has no effect on them. For action's where
489 isToggleAction() is TRUE, this property's default value is off (FALSE).
490 See also toggleAction.
492 Set this property's value with setOn() and get this property's value
494 with isOn().
495
497 This property holds the action's status tip.
498 The statusTip is displayed on all status bars that this action's
500 toplevel parent widget provides.
501 If no status tip is defined, the action uses the tool tip text.
503 There is no default statusTip text.
505 See also statusTip and toolTip.
507 Set this property's value with setStatusTip() and get this property's
509 value with statusTip().
510
512 This property holds the action's descriptive text.
513 If QMainWindow::usesTextLabel is TRUE, the text appears as a label in
515 the relevant tool button. It also serves as the default text in menus
516 and tool tips if these have not been specifically defined. There is no
517 default text.
518 See also menuText, toolTip, and statusTip.
520 Set this property's value with setText() and get this property's value
522 with text().
523
525 This property holds whether the action is a toggle action.
526 A toggle action is one which has an on/off state. For example a Bold
528 toolbar button is either on or off. An action which is not a toggle
529 action is a command action; a command action is simply executed, e.g.
530 file save. This property's default is FALSE.
531 In some situations, the state of one toggle action should depend on the
533 state of others. For example, "Left Align", "Center" and" Right Align"
534 toggle actions are mutually exclusive. To achieve exclusive toggling,
535 add the relevant toggle actions to a QActionGroup with the
536 QActionGroup::exclusive property set to TRUE.
537 Set this property's value with setToggleAction() and get this
539 property's value with isToggleAction().
540
542 This property holds the action's tool tip.
543 This text is used for the tool tip. If no status tip has been set the
545 tool tip will be used for the status tip.
546 If no tool tip is specified the action's text is used, and if that
548 hasn't been specified the description text is used as the tool tip
549 text.
550 There is no default tool tip text.
552 See also statusTip and accel.
554 Set this property's value with setToolTip() and get this property's
556 value with toolTip().
557
559 This property holds whether the action can be seen (e.g. in menus and
560 toolbars).
561 If visible is TRUE the action can be seen (e.g. in menus and toolbars)
563 and chosen by the user; if visible is FALSE the action cannot be seen
564 or chosen by the user.
565 Actions which are not visible are not grayed out; they do not appear at
567 all.
568 Set this property's value with setVisible() and get this property's
570 value with isVisible().
571
573 This property holds the action's "What's This?" help text.
574 The whats this text is used to provide a brief description of the
576 action. The text may contain rich text (HTML-like tags -- see
577 QStyleSheet for the list of supported tags). There is no default"
578 What's This" text.
579 See also QWhatsThis.
581 Set this property's value with setWhatsThis() and get this property's
583 value with whatsThis().
584
587 http://doc.trolltech.com/qaction.html
588 http://www.trolltech.com/faq/tech.html
589
591 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
592 license file included in the distribution for a complete license
593 statement.
594
596 Generated automatically from the source code.
597
599 If you find a bug in Qt, please report it as described in
600 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
601 help you. Thank you.
602 The definitive Qt documentation is provided in HTML format; it is
604 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
605 web browser. This man page is provided as a convenience for those users
606 who prefer man pages, although this format is not officially supported
607 by Trolltech.
608 If you find errors in this manual page, please report them to qt-
610 bugs@trolltech.com. Please include the name of the manual page
611 (qaction.3qt) and the Qt version (3.3.8).
612Trolltech AS 2 February 2007 QAction(3qt)