QActionGroup Class Reference

#include <qactiongroup.h>

Inheritance diagram for QActionGroup:

Inheritance graph
[legend]
Collaboration diagram for QActionGroup:

Collaboration graph
[legend]
List of all members.

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 Align} action, a {Right Align} action, a {Justify} action, and a {Center} action, only one of these actions should be active at any one time. One simple way of achieving this is to group the actions together in an action group.

Here's a example (from the {mainwindows/menus}{Menus} example):

mainwindows/menus/mainwindow.cpp new QActionGroup leftAlignAct->setChecked

Here we create a new action group. Since the action group is exclusive by default, only one of the actions in the group is checked at any one time.

qactiongroup-align.png Alignment options in a QMenu

A QActionGroup emits an triggered() signal when one of its actions is chosen. Each action in an action group emits its triggered() signal as usual.

As stated above, an action group is exclusive by default; it ensures that only one checkable action is active at any one time. If you want to group checkable actions without making them exclusive, you can turn of exclusiveness by calling setExclusive(false).

Actions can be added to an action group using addAction(), but it is usually more convenient to specify a group when creating actions; this ensures that actions are automatically created with a parent. Actions can be visually separated from each other by adding a separator action to the group; create an action and use QAction's {QAction::}{setSeparator()} function to make it considered a separator. Action groups are added to widgets with the QWidget::addActions() function.

See also:
QAction

Definition at line 37 of file qactiongroup.h.

Public Slots

void setEnabled (bool)
void setDisabled (bool b)
void setVisible (bool)
void setExclusive (bool)

Signals

void triggered (QAction *)
QT_MOC_COMPAT void selected (QAction *)
void hovered (QAction *)

Public Member Functions

 QActionGroup (QObject *parent)
 ~QActionGroup ()
QAction * addAction (QAction *a)
QAction * addAction (const QString &text)
QAction * addAction (const QIcon &icon, const QString &text)
void removeAction (QAction *a)
QList< QAction * > actions () const
QAction * checkedAction () const
bool isExclusive () const
bool isEnabled () const
bool isVisible () const

Private Member Functions

 Q_PRIVATE_SLOT (d_func(), void _q_actionTriggered()) Q_PRIVATE_SLOT(d_func()
void _q_actionChanged ()) Q_PRIVATE_SLOT(d_func()

Constructor & Destructor Documentation

QActionGroup::QActionGroup ( QObject *  parent  )  [explicit]

Constructs an action group for the parent object.

The action group is exclusive by default. Call setExclusive(false) to make the action group non-exclusive.

Definition at line 132 of file qactiongroup.cpp.

00132                                           : QObject(*new QActionGroupPrivate, parent)
00133 {
00134 }

QActionGroup::~QActionGroup (  ) 

Destroys the action group.

Definition at line 139 of file qactiongroup.cpp.

00140 {
00141 }

Member Function Documentation

QAction * QActionGroup::addAction ( QAction *  action  ) 

Adds the action to this group, and returns it.

Normally an action is added to a group by creating it with the group as its parent, so this function is not usually used.

See also:
QAction::setActionGroup()

Definition at line 153 of file qactiongroup.cpp.

References _q_actionChanged(), a, QObject::connect(), d, hovered(), SIGNAL, SLOT, and triggered().

Referenced by addAction(), QDesignerWorkbench::addFormWindow(), MainWindow::addToMenu(), QDesignerWorkbench::addToolWindow(), ColorSwatch::ColorSwatch(), QDesignerActions::QDesignerActions(), QMultiInputContext::QMultiInputContext(), QAction::setActionGroup(), and ToolBar::ToolBar().

00154 {
00155     Q_D(QActionGroup);
00156     if(!d->actions.contains(a)) {
00157         d->actions.append(a);
00158         QObject::connect(a, SIGNAL(triggered()), this, SLOT(_q_actionTriggered()));
00159         QObject::connect(a, SIGNAL(changed()), this, SLOT(_q_actionChanged()));
00160         QObject::connect(a, SIGNAL(hovered()), this, SLOT(_q_actionHovered()));
00161     }
00162     if(!a->d_func()->forceDisabled) {
00163         a->setEnabled(d->enabled);
00164         a->d_func()->forceDisabled = false;
00165     }
00166     if(!a->d_func()->forceInvisible) {
00167         a->setVisible(d->visible);
00168         a->d_func()->forceInvisible = false;
00169     }
00170     if(a->isChecked())
00171         d->current = a;
00172     if(a->d_func()->group != this)
00173         a->d_func()->group = this;
00174     return a;
00175 }

Here is the call graph for this function:

QAction * QActionGroup::addAction ( const QString &  text  ) 

Creates and returns an action with text. The newly created action is a child of this action 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:
QAction::setActionGroup()

Definition at line 186 of file qactiongroup.cpp.

00187 {
00188     return new QAction(text, this);
00189 }

QAction * QActionGroup::addAction ( const QIcon &  icon,
const QString &  text 
)

Creates and returns an action with text and an icon. The newly created action is a child of this action group.

Normally an action is added to a group by creating it with the group as its parent, so this function is not usually used.

See also:
QAction::setActionGroup()

Definition at line 200 of file qactiongroup.cpp.

00201 {
00202     return new QAction(icon, text, this);
00203 }

void QActionGroup::removeAction ( QAction *  action  ) 

Removes the action from this group. The action will have no parent as a result.

See also:
QAction::setActionGroup()

Definition at line 211 of file qactiongroup.cpp.

References _q_actionChanged(), d, QObject::disconnect(), hovered(), SIGNAL, SLOT, and triggered().

Referenced by QtWindowListMenu::eventFilter(), QDesignerWorkbench::removeFormWindow(), QDesignerWorkbench::removeToolWindow(), and QtWindowListMenu::removeWindow().

00212 {
00213     Q_D(QActionGroup);
00214     if (d->actions.removeAll(action)) {
00215         QObject::disconnect(action, SIGNAL(triggered()), this, SLOT(_q_actionTriggered()));
00216         QObject::disconnect(action, SIGNAL(changed()), this, SLOT(_q_actionChanged()));
00217         QObject::disconnect(action, SIGNAL(hovered()), this, SLOT(_q_actionHovered()));
00218         action->d_func()->group = 0;
00219     }
00220 }

Here is the call graph for this function:

QList< QAction * > QActionGroup::actions (  )  const

Returns the list of this groups's actions. This may be empty.

Definition at line 225 of file qactiongroup.cpp.

References d.

Referenced by addAction(), QDesignerWorkbench::addFormWindow(), QDesignerWorkbench::addToolWindow(), QDesignerWorkbench::changeBringToFrontVisiblity(), MainWindow::checkCurrentStyle(), ColorSwatch::ColorSwatch(), QAbstractFormBuilder::createDom(), QDesignerActions::fixActionContext(), QDesignerWorkbench::initialize(), MainWindow::loadPlugins(), TextEdit::setupTextActions(), ToolBar::ToolBar(), and QDesignerActions::updateRecentFileActions().

00226 {
00227     Q_D(const QActionGroup);
00228     return d->actions;
00229 }

QAction * QActionGroup::checkedAction (  )  const

Returns the currently checked action in the group, or 0 if none are checked.

Definition at line 293 of file qactiongroup.cpp.

References d.

00294 {
00295     Q_D(const QActionGroup);
00296     return d->current;
00297 }

bool QActionGroup::isExclusive (  )  const

Definition at line 248 of file qactiongroup.cpp.

References d.

Referenced by QMenuPrivate::getStyleOption().

00249 {
00250     Q_D(const QActionGroup);
00251     return d->exclusive;
00252 }

bool QActionGroup::isEnabled (  )  const

Definition at line 283 of file qactiongroup.cpp.

References d.

Referenced by ColorSwatch::allow(), ToolBar::allow(), ToolBar::place(), ColorSwatch::place(), ColorSwatch::updateContextMenu(), and ToolBar::updateMenu().

00284 {
00285     Q_D(const QActionGroup);
00286     return d->enabled;
00287 }

bool QActionGroup::isVisible (  )  const

Definition at line 320 of file qactiongroup.cpp.

References d.

00321 {
00322     Q_D(const QActionGroup);
00323     return d->visible;
00324 }

void QActionGroup::setEnabled ( bool   )  [slot]

Definition at line 271 of file qactiongroup.cpp.

References d.

Referenced by QDesignerActions::activeFormWindowChanged().

00272 {
00273     Q_D(QActionGroup);
00274     d->enabled = b;
00275     for(QList<QAction*>::Iterator it = d->actions.begin(); it != d->actions.end(); ++it) {
00276         if(!(*it)->d_func()->forceDisabled) {
00277             (*it)->setEnabled(b);
00278             (*it)->d_func()->forceDisabled = false;
00279         }
00280     }
00281 }

void QActionGroup::setDisabled ( bool  b  )  [inline, slot]

This is a convenience function for the enabled property, that is useful for signals--slots connections. If b is true the action group is disabled; otherwise it is enabled.

Definition at line 70 of file qactiongroup.h.

00070 { setEnabled(!b); }

void QActionGroup::setVisible ( bool   )  [slot]

Definition at line 308 of file qactiongroup.cpp.

References d.

00309 {
00310     Q_D(QActionGroup);
00311     d->visible = b;
00312     for(QList<QAction*>::Iterator it = d->actions.begin(); it != d->actions.end(); ++it) {
00313         if(!(*it)->d_func()->forceInvisible) {
00314             (*it)->setVisible(b);
00315             (*it)->d_func()->forceInvisible = false;
00316         }
00317     }
00318 }

void QActionGroup::setExclusive ( bool   )  [slot]

Definition at line 242 of file qactiongroup.cpp.

References d.

Referenced by ColorSwatch::ColorSwatch(), QDesignerWorkbench::initialize(), QDesignerActions::QDesignerActions(), QtWindowListMenu::QtWindowListMenu(), QToolBar::resizeEvent(), MainWindow::setupDockWidgets(), and ToolBar::ToolBar().

00243 {
00244     Q_D(QActionGroup);
00245     d->exclusive = b;
00246 }

void QActionGroup::triggered ( QAction *  action  )  [signal]

This signal is emitted when the given action in the action group is activated by the user; for example, when the user clicks a menu option, toolbar button, or presses an action's shortcut key combination.

Connect to this signal for command actions.

See also:
QAction::activate()

Referenced by addAction(), and removeAction().

void QActionGroup::selected ( QAction *  action  )  [signal]

Use triggered() instead.

void QActionGroup::hovered ( QAction *  action  )  [signal]

This signal is emitted when the given action in the action group is highlighted by the user; for example, when the user pauses with the cursor over a menu option, toolbar button, or presses an action's shortcut key combination.

See also:
QAction::activate()

Referenced by addAction(), and removeAction().

QActionGroup::Q_PRIVATE_SLOT ( d_func()  ,
void   _q_actionTriggered() 
) [private]

void QActionGroup::_q_actionChanged (  )  [private]

Referenced by addAction(), and removeAction().

The documentation for this class was generated from the following files:
Generated on Thu Mar 15 16:49:26 2007 for Qt 4.2 User's Guide by  doxygen 1.5.1