QAction Class Reference

The QAction class abstracts a user interface action that can appear both in menus and tool bars. More...

#include <qaction.h>

Inherits QObject.

Inherited by QActionGroup.

List of all member functions.

Public Members

• QAction ( QObject * parent = 0, const char * name = 0, bool toggle = FALSE ) 
• QAction ( const QString & text, const QIconSet & icon, const QString & menuText, int accel, QObject * parent, const char * name = 0, bool toggle = FALSE ) 
• QAction ( const QString & text, const QString & menuText, int accel, QObject * parent, const char * name = 0, bool toggle = FALSE ) 
• ~QAction () 
• virtual void setIconSet ( const QIconSet & ) 
• QIconSet iconSet () const
• virtual void setText ( const QString & ) 
• QString text () const
• virtual void setMenuText ( const QString & ) 
• QString menuText () const
• virtual void setToolTip ( const QString & ) 
• QString toolTip () const
• virtual void setStatusTip ( const QString & ) 
• QString statusTip () const
• virtual void setWhatsThis ( const QString & ) 
• QString whatsThis () const
• virtual void setAccel ( int key ) 
• int accel () const
• virtual void setToggleAction ( bool ) 
• bool isToggleAction () const
• virtual void setOn ( bool ) 
• bool isOn () const
• bool isEnabled () const
• virtual bool addTo ( QWidget * ) 
• virtual bool removeFrom ( QWidget * ) 

Public Slots

• virtual void setEnabled ( bool ) 

Signals

• void activated () 
• void toggled ( bool ) 

Properties

Detailed Description

There are two basic kind of user interface actions, command actions and options. QAction usually models a command action, for example "open file". When the actual action shall be performed, it emits the activated() signal. Options, for example the drawing tools in a paint program, are represented by toggle actions (see setToggleAction() ). A toggle action emits a toggled() signal whenever it changes state. Several toggle actions can be combined in a QActionGroup.

To provide an action to the user, use addTo() to add it to either a menu or a tool bar, for example:

  QPopupMenu* popup = new QPopupMenu;
  QAction* myAction= new QAction;
  myAction->setText( "MyAction" );
  myAction->addTo( popup );

You can add an action to an arbitrary number of menus and toolbars and remove it again with removeFrom().

Changing an action's properties, for example using setEnabled(), setOn() or setText(), immediately shows up in all representations. Other properties that define the way an action is presented to the user are iconSet(), menuText(), toolTip(), statusTip() and whatsThis().

An action may also be triggered by an accelerator key declared with setAccel(). Since accelerators are window specific, the application window has to be an ancestor of the action. Generally, it is therefore a good idea to always create actions as direct children of the main window.

Member Function Documentation

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

Constructs an action with parent parent and name name.

If toggle is TRUE, the action becomes a toggle action.

If the parent is a QActionGroup, the action automatically becomes a member of it.

Note: for accelerators to work, the parent or one of its ancestors has to be the application window.

QAction::QAction ( const QString & text, const QIconSet & icon, const QString & menuText, int accel, QObject * parent, const char * name = 0, bool toggle = FALSE )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Constructs an action with text text, icon icon, menu text menuText, a keyboard accelerator accel, a parent and name name. text will also show up in tooltips, unless you call setToolTip() with a different tip later.

If the parent is a QActionGroup, the action automatically becomes a member of it.

Note: for accelerators to work, the parent or one of its ancestors has to be the application window.

QAction::QAction ( const QString & text, const QString & menuText, int accel, QObject * parent, const char * name = 0, bool toggle = FALSE )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Constructs an action with text text, menu text menuText, a keyboard accelerator accel, a parent and name name. text will also show up in tooltips, unless you call setToolTip() with a different tip later.

If toggle is TRUE, the action becomes a toggle action.

If the parent is a QActionGroup, the action automatically becomes a member of it.

Note: for accelerators to work, the parent or one of its ancestors has to be the application window.

QAction::~QAction ()

Destroys the object and frees any allocated resources.

int QAction::accel () const

Returns the acceleration key.

See also setAccel().

void QAction::activated () [signal]

This signal is emitted when the action was activated by the user.

See also toggled().

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

Adds this action to widget w.

Currently supported widget types are QToolBar and QPopupMenu.

Returns TRUE when the action was added successfully, FALSE otherwise.

See also removeFrom().

Reimplemented in QActionGroup.

QIconSet QAction::iconSet () const

Returns the icon set.

See also setIconSet();.

bool QAction::isEnabled () const

Returns TRUE if the action is enabled, or FALSE if it is disabled.

See also setEnabled().

bool QAction::isOn () const

Returns TRUE if this toggle action is switched on, or FALSE if it is switched off.

See also setOn() and isToggleAction().

bool QAction::isToggleAction () const

Returns whether the action is a toggle action or not.

See also setToggleAction().

QString QAction::menuText () const

Returns the text used for menu items.

If no menu text has been defined yet, this is the same as text().

See also setMenuText() and text().

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

Removes the action from widget w

Returns TRUE when the action was removed successfully, FALSE otherwise.

See also addTo().

Reimplemented in QActionGroup.

void QAction::setAccel ( int key ) [virtual]

Sets the action's accelerator to key.

Note: For accelerators to work, the parent or one of its ancestors has to be the application window.

See also accel().

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

Enables the action if enable is TRUE, otherwise disables it.

Menu items and/or tool buttons presenting the action to the user are updated accordingly.

See also isEnabled().

Reimplemented in QActionGroup.

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

Sets the icon set to icon.

See also iconSet();.

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

Sets a special text text for menu items. Use this to specify ellipses or keyboard shortcuts that should not show up in tooltips or as button text.

See also setText() and menuText().

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

Switches a toggle action on if enable is TRUE or off if enable is FALSE.

This function should be called only for toggle actions.

See also isOn() and setToggleAction().

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

Sets the status tip to tip. The tip will be displayed on all status bars the topmost parent of the action provides.

See also statusTip().

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

Sets the text to text.

See also setMenuText() and text().

void QAction::setToggleAction ( bool enable ) [virtual]

Makes the action a toggle action if enable is TRUE, or a normal action if enable is FALSE.

You may want to add toggle actions to a QActionGroup for exclusive toggling.

See also isToggleAction().

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

Sets the tool tip to tip.

See also toolTip().

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

Sets What's This help to whatsThis.

See also whatsThis().

QString QAction::statusTip () const

Returns the current status tip.

If not status tip has been defined yet, this is the same as toolTip()

See also setStatusTip() and toolTip().

QString QAction::text () const

Returns the current text.

See also setText() and menuText().

void QAction::toggled ( bool ) [signal]

This signal is emitted when a toggle action changes state.

See also activated() and setToggleAction().

QString QAction::toolTip () const

Returns the current tool tip.

If no tool tip has been defined yet, it returns text and a hotkey hint.

See also setToolTip() and text().

QString QAction::whatsThis () const

Returns the What's This help for this action.

See also setWhatsThis().

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.