1QAction(3qt)                                                      QAction(3qt)
2
3
4

NAME

6       QAction - Abstract user interface action that can appear both in menus
7       and tool bars
8

SYNOPSIS

10       #include <qaction.h>
11
12       Inherits QObject.
13
14       Inherited by QActionGroup.
15
16   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
53   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
61   Signals
62       void activated ()
63       void toggled ( bool on )
64
65   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
79   Protected Members
80       virtual void addedTo ( QWidget * actionWidget, QWidget * container )
81       virtual void addedTo ( int index, QPopupMenu * menu )
82

DESCRIPTION

84       The QAction class provides an abstract user interface action that can
85       appear both in menus and tool bars.
86
87       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
96       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
102       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
111       Actions are added to widgets (menus or toolbars) using addTo(), and
112       removed using removeFrom().
113
114       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
118               fileOpenAction = new QAction( QPixmap( fileopen ), "&Open...",
119                                             CTRL+Key_O, this, "open" );
120               connect( fileOpenAction, SIGNAL( activated() ) , this, SLOT( choose() ) );
121
122       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
127               QToolBar * fileTools = new QToolBar( this, "file operations" );
128
129               fileSaveAction->addTo( fileTools );
130
131               QPopupMenu * file = new QPopupMenu( this );
132               menuBar()->insertItem( "&File", file );
133
134               fileSaveAction->addTo( file );
135
136       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
139       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
143       To prevent recursion, don't create an action as a child of a widget
144       that the action is later added to.
145
146       See also Main Window and Related Classes and Basic Widgets.
147

MEMBER FUNCTION DOCUMENTATION

QAction::QAction ( QObject * parent, const char * name = 0 )

150       Constructs an action called name with parent parent.
151
152       If parent is a QActionGroup, the new action inserts itself into parent.
153
154       For accelerators and status tips to work, parent must either be a
155       widget, or an action group whose parent is a widget.
156
157       Warning: To prevent recursion, don't create an action as a child of a
158       widget that the action is later added to.
159

QAction::QAction ( const QString & menuText, QKeySequence accel, QObject *

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
166       If parent is a QActionGroup, the action automatically becomes a member
167       of it.
168
169       For accelerators and status tips to work, parent must either be a
170       widget, or an action group whose parent is a widget.
171
172       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
178       Call setToggleAction(TRUE) to make the action a toggle action.
179
180       Warning: To prevent recursion, don't create an action as a child of a
181       widget that the action is later added to.
182

QAction::QAction ( const QIconSet & icon, const QString & menuText,

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
189       If parent is a QActionGroup, the action automatically becomes a member
190       of it.
191
192       For accelerators and status tips to work, parent must either be a
193       widget, or an action group whose parent is a widget.
194
195       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
201       Call setToggleAction(TRUE) to make the action a toggle action.
202
203       Warning: To prevent recursion, don't create an action as a child of a
204       widget that the action is later added to.
205

QAction::QAction ( const QString & text, const QIconSet & icon, const QString

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
212       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
218       If parent is a QActionGroup, the action automatically becomes a member
219       of it.
220
221       For accelerators and status tips to work, parent must either be a
222       widget, or an action group whose parent is a widget.
223
224       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

QAction::QAction ( const QString & text, const QString & menuText,

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
234       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
239       The action automatically becomes a member of parent if parent is a
240       QActionGroup.
241
242       For accelerators and status tips to work, parent must either be a
243       widget, or an action group whose parent is a widget.
244
245       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

QAction::QAction ( QObject * parent, const char * name, bool toggle )

250       This function is obsolete. It is provided to keep old source working.
251       We strongly advise against using it in new code.
252
253       Constructs an action called name with parent parent.
254
255       If toggle is TRUE the action will be a toggle action, otherwise it will
256       be a command action.
257
258       If parent is a QActionGroup, the new action inserts itself into parent.
259
260       For accelerators and status tips to work, parent must either be a
261       widget, or an action group whose parent is a widget.
262

QAction::~QAction ()

264       Destroys the object and frees allocated resources.
265

QKeySequence QAction::accel () const

267       Returns the action's accelerator key. See the "accel" property for
268       details.
269

void QAction::activate () [slot]

271       Activates the action and executes all connected slots. This only works
272       for actions that are not toggle action.
273
274       See also toggle().
275

void QAction::activated () [signal]

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
281       Connect to this signal for command actions. Connect to the toggled()
282       signal for toggle actions.
283
284       Examples:
285

bool QAction::addTo ( QWidget * w ) [virtual]

287       Adds this action to widget w.
288
289       Currently actions may be added to QToolBar and QPopupMenu widgets.
290
291       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
294       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
298       See also removeFrom().
299
300       Examples:
301
302       Reimplemented in QActionGroup.
303

void QAction::addedTo ( QWidget * actionWidget, QWidget * container ) [virtual

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

void QAction::addedTo ( int index, QPopupMenu * menu ) [virtual protected]

310       This is an overloaded member function, provided for convenience. It
311       behaves essentially like the above function.
312
313       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

QIconSet QAction::iconSet () const

317       Returns the action's icon. See the "iconSet" property for details.
318

bool QAction::isEnabled () const

320       Returns TRUE if the action is enabled; otherwise returns FALSE. See the
321       "enabled" property for details.
322

bool QAction::isOn () const

324       Returns TRUE if a toggle action is on; otherwise returns FALSE. See the
325       "on" property for details.
326

bool QAction::isToggleAction () const

328       Returns TRUE if the action is a toggle action; otherwise returns FALSE.
329       See the "toggleAction" property for details.
330

bool QAction::isVisible () const

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

QString QAction::menuText () const

336       Returns the action's menu text. See the "menuText" property for
337       details.
338

bool QAction::removeFrom ( QWidget * w ) [virtual]

340       Removes the action from widget w.
341
342       Returns TRUE if the action was removed successfully; otherwise returns
343       FALSE.
344
345       See also addTo().
346

void QAction::setAccel ( const QKeySequence & key ) [virtual]

348       Sets the action's accelerator key to key. See the "accel" property for
349       details.
350

void QAction::setDisabled ( bool disable ) [slot]

352       Disables the action if disable is TRUE; otherwise enables the action.
353
354       See the enabled documentation for more information.
355

void QAction::setEnabled ( bool ) [virtual slot]

357       Sets whether the action is enabled. See the "enabled" property for
358       details.
359

void QAction::setIconSet ( const QIconSet & ) [virtual]

361       Sets the action's icon. See the "iconSet" property for details.
362

void QAction::setMenuText ( const QString & ) [virtual]

364       Sets the action's menu text. See the "menuText" property for details.
365

void QAction::setOn ( bool ) [virtual slot]

367       Sets whether a toggle action is on. See the "on" property for details.
368

void QAction::setStatusTip ( const QString & ) [virtual]

370       Sets the action's status tip. See the "statusTip" property for details.
371

void QAction::setText ( const QString & ) [virtual]

373       Sets the action's descriptive text. See the "text" property for
374       details.
375

void QAction::setToggleAction ( bool ) [virtual]

377       Sets whether the action is a toggle action. See the "toggleAction"
378       property for details.
379

void QAction::setToolTip ( const QString & ) [virtual]

381       Sets the action's tool tip. See the "toolTip" property for details.
382

void QAction::setVisible ( bool ) [slot]

384       Sets whether the action can be seen (e.g. in menus and toolbars). See
385       the "visible" property for details.
386

void QAction::setWhatsThis ( const QString & ) [virtual]

388       Sets the action's "What's This?" help text. See the "whatsThis"
389       property for details.
390

QString QAction::statusTip () const

392       Returns the action's status tip. See the "statusTip" property for
393       details.
394

QString QAction::text () const

396       Returns the action's descriptive text. See the "text" property for
397       details.
398

void QAction::toggle () [slot]

400       Toggles the state of a toggle action.
401
402       See also on, activate(), toggled(), and toggleAction.
403

void QAction::toggled ( bool on ) [signal]

405       This signal is emitted when a toggle action changes state; command
406       actions and QActionGroups don't emit toggled().
407
408       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
411       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
415               QMainWindow * window = new QMainWindow;
416
417               QAction * labelonoffaction = new QAction( window, "labelonoff" );
418
419               QObject::connect( labelonoffaction, SIGNAL( toggled( bool ) ),
420                                 window, SLOT( setUsesTextLabel( bool ) ) );
421
422       See also activated(), toggleAction, and on.
423
424       Example: action/toggleaction/toggleaction.cpp.
425

QString QAction::toolTip () const

427       Returns the action's tool tip. See the "toolTip" property for details.
428

QString QAction::whatsThis () const

430       Returns the action's "What's This?" help text. See the "whatsThis"
431       property for details.
432
433   Property Documentation

QKeySequence accel

435       This property holds the action's accelerator key.
436
437       The keycodes can be found in Qt::Key and Qt::Modifier. There is no
438       default accelerator key.
439
440       Set this property's value with setAccel() and get this property's value
441       with accel().
442

bool enabled

444       This property holds whether the action is enabled.
445
446       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
450       What's this? help on disabled actions is still available provided the
451       QAction::whatsThis property is set.
452
453       Set this property's value with setEnabled() and get this property's
454       value with isEnabled().
455

QIconSet iconSet

457       This property holds the action's icon.
458
459       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
462       If a null icon (QIconSet::isNull() is passed into this function, the
463       icon of the action is cleared.
464
465       (See the action/toggleaction/toggleaction.cpp example.)
466
467       Set this property's value with setIconSet() and get this property's
468       value with iconSet().
469

QString menuText

471       This property holds the action's menu text.
472
473       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
479       See also text.
480
481       Set this property's value with setMenuText() and get this property's
482       value with menuText().
483

bool on

485       This property holds whether a toggle action is on.
486
487       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
491       See also toggleAction.
492
493       Set this property's value with setOn() and get this property's value
494       with isOn().
495

QString statusTip

497       This property holds the action's status tip.
498
499       The statusTip is displayed on all status bars that this action's
500       toplevel parent widget provides.
501
502       If no status tip is defined, the action uses the tool tip text.
503
504       There is no default statusTip text.
505
506       See also statusTip and toolTip.
507
508       Set this property's value with setStatusTip() and get this property's
509       value with statusTip().
510

QString text

512       This property holds the action's descriptive text.
513
514       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
519       See also menuText, toolTip, and statusTip.
520
521       Set this property's value with setText() and get this property's value
522       with text().
523

bool toggleAction

525       This property holds whether the action is a toggle action.
526
527       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
532       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
538       Set this property's value with setToggleAction() and get this
539       property's value with isToggleAction().
540

QString toolTip

542       This property holds the action's tool tip.
543
544       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
547       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
551       There is no default tool tip text.
552
553       See also statusTip and accel.
554
555       Set this property's value with setToolTip() and get this property's
556       value with toolTip().
557

bool visible

559       This property holds whether the action can be seen (e.g. in menus and
560       toolbars).
561
562       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
566       Actions which are not visible are not grayed out; they do not appear at
567       all.
568
569       Set this property's value with setVisible() and get this property's
570       value with isVisible().
571

QString whatsThis

573       This property holds the action's "What's This?" help text.
574
575       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
580       See also QWhatsThis.
581
582       Set this property's value with setWhatsThis() and get this property's
583       value with whatsThis().
584
585

SEE ALSO

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

AUTHOR

596       Generated automatically from the source code.
597

BUGS

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
603       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
609       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).
612
613
614
615Trolltech AS                    2 February 2007                   QAction(3qt)
Impressum