Detailed Description
The QActionGroup class groups actions together.
In some situations it is useful to group actions together. For
example, if you have a left justify action, a right justify action
and a center action, only one of these actions should be active at
any one time, and one simple way of achieving this is to group the
actions together in an action group and call setExclusive(TRUE).
An action group can also be added to a menu or a toolbar as a
single unit, with all the actions within the action group
appearing as separate menu options and toolbar buttons.
Here's an example from examples/textedit:
QActionGroup *grp = new QActionGroup( this );
grp->setExclusive( TRUE );
connect( grp, SIGNAL( selected( QAction* ) ), this, SLOT( textAlign( QAction* ) ) );
We create a new action group and call setExclusive() to ensure
that only one of the actions in the group is ever active at any
one time. We then connect the group's selected() signal to our
textAlign() slot.
actionAlignLeft = new QAction( tr( "Left" ), QPixmap( "textleft.xpm" ), tr( "&Left" ), CTRL + Key_L, grp, "textLeft" );
actionAlignLeft->addTo( tb );
actionAlignLeft->addTo( menu );
actionAlignLeft->setToggleAction( TRUE );
We create a left align action, add it to the toolbar and the menu
and make it a toggle action. We create center and right align
actions in exactly the same way.
The actions in an action group emit their activated() (and for
toggle actions, toggled()) signals as usual.
The setExclusive() function is used to ensure that only one action
is active at any one time: it should be used with actions which
have their toggleAction set to TRUE.
Action group actions appear as individual menu options and toolbar
buttons. For exclusive action groups use setUsesDropDown() to
display the actions in a subwidget of any widget the action group
is added to. For example, the actions would appear in a combobox
in a toolbar or as a submenu in a menu.
Actions can be added to an action group using add(), but normally
they are added by creating the action with the action group as
parent. Actions can have separators dividing them using
addSeparator(). Action groups are added to widgets with addTo().
See also Main Window and Related Classes and Basic Widgets.
Member Function Documentation
QActionGroup::QActionGroup ( QObject * parent, const char * name = 0, bool exclusive = TRUE )
Constructs an action group called name, with parent parent.
If exclusive is TRUE only one toggle action in the group will
ever be active.
QActionGroup::~QActionGroup ()
Destroys the object and frees allocated resources.
void QActionGroup::add ( QAction * action )
Adds action action to this group.
Normally an action is added to a group by creating it with the
group as parent, so this function is not usually used.
See also addTo().
void QActionGroup::addSeparator ()
Adds a separator to the group.
bool QActionGroup::addTo ( QWidget * w ) [virtual]
Adds this action group to the widget w.
If usesDropDown() is TRUE and exclusive is TRUE (see
setExclusive()) the actions are presented in a combobox if w is
a toolbar and as a submenu if w is a menu. Otherwise (the
default) the actions within the group are added to the widget
individually. For example if the widget is a menu, the actions
will appear as individual menu options, and if the widget is a
toolbar, the actions will appear as toolbar buttons.
It is recommended that actions in action groups, especially where
usesDropDown() is TRUE, have their menuText() or text() property
set.
All actions should be added to the action group before the
action group is added to the widget. If actions are added to the
action group after the action group has been added to the
widget these later actions will not appear.
See also exclusive, usesDropDown and removeFrom().
Example: themes/themes.cpp.
Reimplemented from QAction.
void QActionGroup::addedTo ( QWidget * actionWidget, QWidget * container, QAction * a ) [virtual protected]
This function is called from the addTo() function when it has
created a widget (actionWidget) for the child action a in
the container.
void QActionGroup::addedTo ( int index, QPopupMenu * menu, QAction * a ) [virtual protected]
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
This function is called from the addTo() function when it has
created a menu item for the child action at the index position index in the popup menu menu.
void QActionGroup::insert ( QAction * a )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
Use add() instead, or better still create the action with the action
group as its parent.
bool QActionGroup::isExclusive () const
Returns TRUE if the action group does exclusive toggling; otherwise returns FALSE.
See the "exclusive" property for details.
void QActionGroup::selected ( QAction * ) [signal]
This signal is emitted from exclusive groups when toggle actions
change state.
The argument is the action whose state changed to "on".
See also exclusive and on.
Examples: chart/chartform.cpp and textedit/textedit.cpp.
void QActionGroup::setExclusive ( bool )
Sets whether the action group does exclusive toggling.
See the "exclusive" property for details.
void QActionGroup::setUsesDropDown ( bool enable )
Sets whether the group's actions are displayed in a subwidget of the widgets the action group is added to to enable.
See the "usesDropDown" property for details.
bool QActionGroup::usesDropDown () const
Returns TRUE if the group's actions are displayed in a subwidget of the widgets the action group is added to; otherwise returns FALSE.
See the "usesDropDown" property for details.
Property Documentation
bool exclusive
This property holds whether the action group does exclusive toggling.
If exclusive is TRUE only one toggle action in the action group
can ever be active at any one time. If the user chooses another
toggle action in the group the one they chose becomes active and
the one that was active becomes inactive. By default this property
is FALSE.
See also QAction::toggleAction.
Set this property's value with setExclusive() and get this property's value with isExclusive().
bool usesDropDown
This property holds whether the group's actions are displayed in a subwidget of the widgets the action group is added to.
Exclusive action groups added to a toolbar display their actions
in a combobox with the action's QAction::text and QAction::iconSet properties shown. Non-exclusive groups are
represented by a tool button showing their QAction::iconSet and
-- depending on QMainWindow::usesTextLabel() -- text()
property.
In a popup menu the member actions are displayed in a submenu.
Changing usesDropDown only effects subsequent calls to addTo().
This property's default is FALSE.
Set this property's value with setUsesDropDown() and get this property's value with usesDropDown().
This file is part of the Qt toolkit.
Copyright © 1995-2002
Trolltech. All Rights Reserved.
