1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtGui module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
43 #include "qactiongroup.h"
46 #include "qaction_p.h"
47 #include "qapplication.h"
51 #include <private/qshortcutmap_p.h>
52 #include <private/qapplication_p.h>
53 #include <private/qmenu_p.h>
55 #define QAPP_CHECK(functionName) \
57 qWarning("QAction: Initialize QApplication before calling '" functionName "'."); \
64 internal: guesses a descriptive text from a text suited for a menu entry
66 static QString qt_strippedText(QString s)
68 s.remove( QString::fromLatin1("...") );
70 while (i < s.size()) {
72 if (s.at(i-1) != QLatin1Char('&'))
74 if (i < s.size() && s.at(i) == QLatin1Char('&'))
82 QActionPrivate::QActionPrivate() : group(0), enabled(1), forceDisabled(0),
83 visible(1), forceInvisible(0), checkable(0), checked(0), separator(0), fontSet(false),
84 forceEnabledInSoftkeys(false), menuActionSoftkeys(false),
85 iconVisibleInMenu(-1),
86 menuRole(QAction::TextHeuristicRole), softKeyRole(QAction::NoSoftKey),
87 priority(QAction::NormalPriority)
89 #ifndef QT_NO_SHORTCUT
91 shortcutContext = Qt::WindowShortcut;
96 QActionPrivate::~QActionPrivate()
100 bool QActionPrivate::showStatusText(QWidget *widget, const QString &str)
102 #ifdef QT_NO_STATUSTIP
106 if(QObject *object = widget ? widget : parent) {
107 QStatusTipEvent tip(str);
108 QApplication::sendEvent(object, &tip);
115 void QActionPrivate::sendDataChanged()
118 QActionEvent e(QEvent::ActionChanged, q);
119 for (int i = 0; i < widgets.size(); ++i) {
120 QWidget *w = widgets.at(i);
121 QApplication::sendEvent(w, &e);
123 #ifndef QT_NO_GRAPHICSVIEW
124 for (int i = 0; i < graphicsWidgets.size(); ++i) {
125 QGraphicsWidget *w = graphicsWidgets.at(i);
126 QApplication::sendEvent(w, &e);
129 QApplication::sendEvent(q, &e);
134 #ifndef QT_NO_SHORTCUT
135 void QActionPrivate::redoGrab(QShortcutMap &map)
139 map.removeShortcut(shortcutId, q);
140 if (shortcut.isEmpty())
142 shortcutId = map.addShortcut(q, shortcut, shortcutContext, qWidgetShortcutContextMatcher);
144 map.setShortcutEnabled(false, shortcutId, q);
146 map.setShortcutAutoRepeat(false, shortcutId, q);
149 void QActionPrivate::redoGrabAlternate(QShortcutMap &map)
152 for(int i = 0; i < alternateShortcutIds.count(); ++i) {
153 if (const int id = alternateShortcutIds.at(i))
154 map.removeShortcut(id, q);
156 alternateShortcutIds.clear();
157 if (alternateShortcuts.isEmpty())
159 for(int i = 0; i < alternateShortcuts.count(); ++i) {
160 const QKeySequence& alternate = alternateShortcuts.at(i);
161 if (!alternate.isEmpty())
162 alternateShortcutIds.append(map.addShortcut(q, alternate, shortcutContext, qWidgetShortcutContextMatcher));
164 alternateShortcutIds.append(0);
167 for(int i = 0; i < alternateShortcutIds.count(); ++i) {
168 const int id = alternateShortcutIds.at(i);
169 map.setShortcutEnabled(false, id, q);
173 for(int i = 0; i < alternateShortcutIds.count(); ++i) {
174 const int id = alternateShortcutIds.at(i);
175 map.setShortcutAutoRepeat(false, id, q);
180 void QActionPrivate::setShortcutEnabled(bool enable, QShortcutMap &map)
184 map.setShortcutEnabled(enable, shortcutId, q);
185 for(int i = 0; i < alternateShortcutIds.count(); ++i) {
186 if (const int id = alternateShortcutIds.at(i))
187 map.setShortcutEnabled(enable, id, q);
190 #endif // QT_NO_SHORTCUT
195 \brief The QAction class provides an abstract user interface
196 action that can be inserted into widgets.
198 \ingroup mainwindow-classes
202 * parent and widget are different
203 * parent does not define context
206 In applications many common commands can be invoked via menus,
207 toolbar buttons, and keyboard shortcuts. Since the user expects
208 each command to be performed in the same way, regardless of the
209 user interface used, it is useful to represent each command as
212 Actions can be added to menus and toolbars, and will
213 automatically keep them in sync. For example, in a word processor,
214 if the user presses a Bold toolbar button, the Bold menu item
215 will automatically be checked.
217 Actions can be created as independent objects, but they may
218 also be created during the construction of menus; the QMenu class
219 contains convenience functions for creating actions suitable for
222 A QAction may contain an icon, menu text, a shortcut, status text,
223 "What's This?" text, and a tooltip. Most of these can be set in
224 the constructor. They can also be set independently with
225 setIcon(), setText(), setIconText(), setShortcut(),
226 setStatusTip(), setWhatsThis(), and setToolTip(). For menu items,
227 it is possible to set an individual font with setFont().
229 Actions are added to widgets using QWidget::addAction() or
230 QGraphicsWidget::addAction(). Note that an action must be added to a
231 widget before it can be used; this is also true when the shortcut should
232 be global (i.e., Qt::ApplicationShortcut as Qt::ShortcutContext).
234 Once a QAction has been created it should be added to the relevant
235 menu and toolbar, then connected to the slot which will perform
236 the action. For example:
238 \snippet mainwindows/application/mainwindow.cpp 19
240 \snippet mainwindows/application/mainwindow.cpp 28
241 \snippet mainwindows/application/mainwindow.cpp 31
243 We recommend that actions are created as children of the window
244 they are used in. In most cases actions will be children of
245 the application's main window.
247 \sa QMenu, QToolBar, {Application Example}
251 \fn void QAction::trigger()
253 This is a convenience slot that calls activate(Trigger).
257 \fn void QAction::hover()
259 This is a convenience slot that calls activate(Hover).
263 \enum QAction::MenuRole
265 This enum describes how an action should be moved into the application menu on Mac OS X.
267 \value NoRole This action should not be put into the application menu
268 \value TextHeuristicRole This action should be put in the application menu based on the action's text
269 as described in the QMenuBar documentation.
270 \value ApplicationSpecificRole This action should be put in the application menu with an application specific role
271 \value AboutQtRole This action matches handles the "About Qt" menu item.
272 \value AboutRole This action should be placed where the "About" menu item is in the application menu. The text of
273 the menu item will be set to "About <application name>". The application name is fetched from the
274 \c{Info.plist} file in the application's bundle (See \l{Deploying an Application on Mac OS X}).
275 \value PreferencesRole This action should be placed where the "Preferences..." menu item is in the application menu.
276 \value QuitRole This action should be placed where the Quit menu item is in the application menu.
278 Setting this value only has effect on items that are in the immediate menus
279 of the menubar, not the submenus of those menus. For example, if you have
280 File menu in your menubar and the File menu has a submenu, setting the
281 MenuRole for the actions in that submenu have no effect. They will never be moved.
286 \enum QAction::SoftKeyRole
288 This enum describes how an action should be placed in the softkey bar. Currently this enum only
289 has an effect on the Symbian platform.
291 \value NoSoftKey This action should not be used as a softkey
292 \value PositiveSoftKey This action is used to describe a softkey with a positive or non-destructive
293 role such as Ok, Select, or Options.
294 \value NegativeSoftKey This action is used to describe a soft ey with a negative or destructive role
295 role such as Cancel, Discard, or Close.
296 \value SelectSoftKey This action is used to describe a role that selects a particular item or widget
299 Actions with a softkey role defined are only visible in the softkey bar when the widget containing
300 the action has focus. If no widget currently has focus, the softkey framework will traverse up the
301 widget parent hierarchy looking for a widget containing softkey actions.
305 Constructs an action with \a parent. If \a parent is an action
306 group the action will be automatically inserted into the group.
308 QAction::QAction(QObject* parent)
309 : QObject(*(new QActionPrivate), parent)
312 d->group = qobject_cast<QActionGroup *>(parent);
314 d->group->addAction(this);
319 Constructs an action with some \a text and \a parent. If \a
320 parent is an action group the action will be automatically
321 inserted into the group.
323 The action uses a stripped version of \a text (e.g. "\&Menu
324 Option..." becomes "Menu Option") as descriptive text for
325 tool buttons. You can override this by setting a specific
326 description with setText(). The same text will be used for
327 tooltips unless you specify a different text using
331 QAction::QAction(const QString &text, QObject* parent)
332 : QObject(*(new QActionPrivate), parent)
336 d->group = qobject_cast<QActionGroup *>(parent);
338 d->group->addAction(this);
342 Constructs an action with an \a icon and some \a text and \a
343 parent. If \a parent is an action group the action will be
344 automatically inserted into the group.
346 The action uses a stripped version of \a text (e.g. "\&Menu
347 Option..." becomes "Menu Option") as descriptive text for
348 tool buttons. You can override this by setting a specific
349 description with setText(). The same text will be used for
350 tooltips unless you specify a different text using
353 QAction::QAction(const QIcon &icon, const QString &text, QObject* parent)
354 : QObject(*(new QActionPrivate), parent)
359 d->group = qobject_cast<QActionGroup *>(parent);
361 d->group->addAction(this);
367 QAction::QAction(QActionPrivate &dd, QObject *parent)
368 : QObject(dd, parent)
371 d->group = qobject_cast<QActionGroup *>(parent);
373 d->group->addAction(this);
377 Returns the parent widget.
379 QWidget *QAction::parentWidget() const
381 QObject *ret = parent();
382 while (ret && !ret->isWidgetType())
384 return (QWidget*)ret;
389 Returns a list of widgets this action has been added to.
391 \sa QWidget::addAction(), associatedGraphicsWidgets()
393 QList<QWidget *> QAction::associatedWidgets() const
399 #ifndef QT_NO_GRAPHICSVIEW
402 Returns a list of widgets this action has been added to.
404 \sa QWidget::addAction(), associatedWidgets()
406 QList<QGraphicsWidget *> QAction::associatedGraphicsWidgets() const
409 return d->graphicsWidgets;
413 #ifndef QT_NO_SHORTCUT
415 \property QAction::shortcut
416 \brief the action's primary shortcut key
418 Valid keycodes for this property can be found in \l Qt::Key and
419 \l Qt::Modifier. There is no default shortcut key.
421 void QAction::setShortcut(const QKeySequence &shortcut)
423 QAPP_CHECK("setShortcut");
426 if (d->shortcut == shortcut)
429 d->shortcut = shortcut;
430 d->redoGrab(qApp->d_func()->shortcutMap);
431 d->sendDataChanged();
437 Sets \a shortcuts as the list of shortcuts that trigger the
438 action. The first element of the list is the primary shortcut.
442 void QAction::setShortcuts(const QList<QKeySequence> &shortcuts)
446 QList <QKeySequence> listCopy = shortcuts;
448 QKeySequence primary;
449 if (!listCopy.isEmpty())
450 primary = listCopy.takeFirst();
452 if (d->shortcut == primary && d->alternateShortcuts == listCopy)
455 QAPP_CHECK("setShortcuts");
457 d->shortcut = primary;
458 d->alternateShortcuts = listCopy;
459 d->redoGrab(qApp->d_func()->shortcutMap);
460 d->redoGrabAlternate(qApp->d_func()->shortcutMap);
461 d->sendDataChanged();
467 Sets a platform dependent list of shortcuts based on the \a key.
468 The result of calling this function will depend on the currently running platform.
469 Note that more than one shortcut can assigned by this action.
470 If only the primary shortcut is required, use setShortcut instead.
472 \sa QKeySequence::keyBindings()
474 void QAction::setShortcuts(QKeySequence::StandardKey key)
476 QList <QKeySequence> list = QKeySequence::keyBindings(key);
481 Returns the primary shortcut.
485 QKeySequence QAction::shortcut() const
494 Returns the list of shortcuts, with the primary shortcut as
495 the first element of the list.
499 QList<QKeySequence> QAction::shortcuts() const
502 QList <QKeySequence> shortcuts;
503 if (!d->shortcut.isEmpty())
504 shortcuts << d->shortcut;
505 if (!d->alternateShortcuts.isEmpty())
506 shortcuts << d->alternateShortcuts;
511 \property QAction::shortcutContext
512 \brief the context for the action's shortcut
514 Valid values for this property can be found in \l Qt::ShortcutContext.
515 The default value is Qt::WindowShortcut.
517 void QAction::setShortcutContext(Qt::ShortcutContext context)
520 if (d->shortcutContext == context)
522 QAPP_CHECK("setShortcutContext");
523 d->shortcutContext = context;
524 d->redoGrab(qApp->d_func()->shortcutMap);
525 d->redoGrabAlternate(qApp->d_func()->shortcutMap);
526 d->sendDataChanged();
529 Qt::ShortcutContext QAction::shortcutContext() const
532 return d->shortcutContext;
536 \property QAction::autoRepeat
537 \brief whether the action can auto repeat
540 If true, the action will auto repeat when the keyboard shortcut
541 combination is held down, provided that keyboard auto repeat is
542 enabled on the system.
543 The default value is true.
545 void QAction::setAutoRepeat(bool on)
548 if (d->autorepeat == on)
550 QAPP_CHECK("setAutoRepeat");
552 d->redoGrab(qApp->d_func()->shortcutMap);
553 d->redoGrabAlternate(qApp->d_func()->shortcutMap);
554 d->sendDataChanged();
557 bool QAction::autoRepeat() const
560 return d->autorepeat;
562 #endif // QT_NO_SHORTCUT
565 \property QAction::font
566 \brief the action's font
568 The font property is used to render the text set on the
569 QAction. The font will can be considered a hint as it will not be
570 consulted in all cases based upon application and style.
572 By default, this property contains the application's default font.
574 \sa QAction::setText(), QStyle
576 void QAction::setFont(const QFont &font)
584 d->sendDataChanged();
587 QFont QAction::font() const
595 Destroys the object and frees allocated resources.
600 for (int i = d->widgets.size()-1; i >= 0; --i) {
601 QWidget *w = d->widgets.at(i);
602 w->removeAction(this);
604 #ifndef QT_NO_GRAPHICSVIEW
605 for (int i = d->graphicsWidgets.size()-1; i >= 0; --i) {
606 QGraphicsWidget *w = d->graphicsWidgets.at(i);
607 w->removeAction(this);
611 d->group->removeAction(this);
612 #ifndef QT_NO_SHORTCUT
613 if (d->shortcutId && qApp) {
614 qApp->d_func()->shortcutMap.removeShortcut(d->shortcutId, this);
615 for(int i = 0; i < d->alternateShortcutIds.count(); ++i) {
616 const int id = d->alternateShortcutIds.at(i);
617 qApp->d_func()->shortcutMap.removeShortcut(id, this);
624 Sets this action group to \a group. The action will be automatically
625 added to the group's list of actions.
627 Actions within the group will be mutually exclusive.
629 \sa QActionGroup, QAction::actionGroup()
631 void QAction::setActionGroup(QActionGroup *group)
634 if(group == d->group)
638 d->group->removeAction(this);
641 group->addAction(this);
645 Returns the action group for this action. If no action group manages
646 this action then 0 will be returned.
648 \sa QActionGroup, QAction::setActionGroup()
650 QActionGroup *QAction::actionGroup() const
658 \property QAction::icon
659 \brief the action's icon
661 In toolbars, the icon is used as the tool button icon; in menus,
662 it is displayed to the left of the menu text. There is no default
665 If a null icon (QIcon::isNull() is passed into this function,
666 the icon of the action is cleared.
668 void QAction::setIcon(const QIcon &icon)
672 d->sendDataChanged();
675 QIcon QAction::icon() const
683 Returns the menu contained by this action. Actions that contain
684 menus can be used to create menu items with submenus, or inserted
685 into toolbars to create buttons with popup menus.
687 \sa QMenu::addAction()
689 QMenu *QAction::menu() const
696 Sets the menu contained by this action to the specified \a menu.
698 void QAction::setMenu(QMenu *menu)
702 d->menu->d_func()->setOverrideMenuAction(0); //we reset the default action of any previous menu
705 menu->d_func()->setOverrideMenuAction(this);
706 d->sendDataChanged();
711 If \a b is true then this action will be considered a separator.
713 How a separator is represented depends on the widget it is inserted
714 into. Under most circumstances the text, submenu, and icon will be
715 ignored for separator actions.
717 \sa QAction::isSeparator()
719 void QAction::setSeparator(bool b)
722 if (d->separator == b)
726 d->sendDataChanged();
730 Returns true if this action is a separator action; otherwise it
733 \sa QAction::setSeparator()
735 bool QAction::isSeparator() const
742 \property QAction::text
743 \brief the action's descriptive text
745 If the action is added to a menu, the menu option will consist of
746 the icon (if there is one), the text, and the shortcut (if there
747 is one). If the text is not explicitly set in the constructor, or
748 by using setText(), the action's description icon text will be
749 used as text. There is no default text.
753 void QAction::setText(const QString &text)
760 d->sendDataChanged();
763 QString QAction::text() const
769 s.replace(QLatin1Char('&'), QLatin1String("&&"));
779 \property QAction::iconText
780 \brief the action's descriptive icon text
782 If QToolBar::toolButtonStyle is set to a value that permits text to
783 be displayed, the text defined held in this property appears as a
784 label in the relevant tool button.
786 It also serves as the default text in menus and tooltips if the action
787 has not been defined with setText() or setToolTip(), and will
788 also be used in toolbar buttons if no icon has been defined using setIcon().
790 If the icon text is not explicitly set, the action's normal text will be
791 used for the icon text.
793 By default, this property contains an empty string.
795 \sa setToolTip(), setStatusTip()
797 void QAction::setIconText(const QString &text)
800 if (d->iconText == text)
804 d->sendDataChanged();
807 QString QAction::iconText() const
810 if (d->iconText.isEmpty())
811 return qt_strippedText(d->text);
816 \property QAction::toolTip
817 \brief the action's tooltip
819 This text is used for the tooltip. If no tooltip is specified,
820 the action's text is used.
822 By default, this property contains the action's text.
824 \sa setStatusTip(), setShortcut()
826 void QAction::setToolTip(const QString &tooltip)
829 if (d->tooltip == tooltip)
832 d->tooltip = tooltip;
833 d->sendDataChanged();
836 QString QAction::toolTip() const
839 if (d->tooltip.isEmpty()) {
840 if (!d->text.isEmpty())
841 return qt_strippedText(d->text);
842 return qt_strippedText(d->iconText);
848 \property QAction::statusTip
849 \brief the action's status tip
851 The status tip is displayed on all status bars provided by the
852 action's top-level parent widget.
854 By default, this property contains an empty string.
856 \sa setToolTip(), showStatusText()
858 void QAction::setStatusTip(const QString &statustip)
861 if (d->statustip == statustip)
864 d->statustip = statustip;
865 d->sendDataChanged();
868 QString QAction::statusTip() const
875 \property QAction::whatsThis
876 \brief the action's "What's This?" help text
878 The "What's This?" text is used to provide a brief description of
879 the action. The text may contain rich text. There is no default
884 void QAction::setWhatsThis(const QString &whatsthis)
887 if (d->whatsthis == whatsthis)
890 d->whatsthis = whatsthis;
891 d->sendDataChanged();
894 QString QAction::whatsThis() const
901 \enum QAction::Priority
904 This enum defines priorities for actions in user interface.
906 \value LowPriority The action should not be prioritized in
909 \value NormalPriority
911 \value HighPriority The action should be prioritized in
919 \property QAction::priority
922 \brief the actions's priority in the user interface.
924 This property can be set to indicate how the action should be prioritized
925 in the user interface.
927 For instance, when toolbars have the Qt::ToolButtonTextBesideIcon
928 mode set, then actions with LowPriority will not show the text
931 void QAction::setPriority(Priority priority)
934 if (d->priority == priority)
937 d->priority = priority;
938 d->sendDataChanged();
941 QAction::Priority QAction::priority() const
948 \property QAction::checkable
949 \brief whether the action is a checkable action
951 A checkable action is one which has an on/off state. For example,
952 in a word processor, a Bold toolbar button may be either on or
953 off. An action which is not a toggle action is a command action;
954 a command action is simply executed, e.g. file save.
955 By default, this property is false.
957 In some situations, the state of one toggle action should depend
958 on the state of others. For example, "Left Align", "Center" and
959 "Right Align" toggle actions are mutually exclusive. To achieve
960 exclusive toggling, add the relevant toggle actions to a
961 QActionGroup with the QActionGroup::exclusive property set to
964 \sa QAction::setChecked()
966 void QAction::setCheckable(bool b)
969 if (d->checkable == b)
974 d->sendDataChanged();
977 bool QAction::isCheckable() const
984 \fn void QAction::toggle()
986 This is a convenience function for the \l checked property.
987 Connect to it to change the checked state to its opposite state.
989 void QAction::toggle()
992 setChecked(!d->checked);
996 \property QAction::checked
997 \brief whether the action is checked.
999 Only checkable actions can be checked. By default, this is false
1000 (the action is unchecked).
1004 void QAction::setChecked(bool b)
1007 if (!d->checkable || d->checked == b)
1010 QPointer<QAction> guard(this);
1012 d->sendDataChanged();
1017 bool QAction::isChecked() const
1024 \fn void QAction::setDisabled(bool b)
1026 This is a convenience function for the \l enabled property, that
1027 is useful for signals--slots connections. If \a b is true the
1028 action is disabled; otherwise it is enabled.
1032 \property QAction::enabled
1033 \brief whether the action is enabled
1035 Disabled actions cannot be chosen by the user. They do not
1036 disappear from menus or toolbars, but they are displayed in a way
1037 which indicates that they are unavailable. For example, they might
1038 be displayed using only shades of gray.
1040 \uicontrol{What's This?} help on disabled actions is still available, provided
1041 that the QAction::whatsThis property is set.
1043 An action will be disabled when all widgets to which it is added
1044 (with QWidget::addAction()) are disabled or not visible. When an
1045 action is disabled, it is not possible to trigger it through its
1048 By default, this property is true (actions are enabled).
1052 void QAction::setEnabled(bool b)
1055 if (b == d->enabled && b != d->forceDisabled)
1057 d->forceDisabled = !b;
1058 if (b && (!d->visible || (d->group && !d->group->isEnabled())))
1060 QAPP_CHECK("setEnabled");
1062 #ifndef QT_NO_SHORTCUT
1063 d->setShortcutEnabled(b, qApp->d_func()->shortcutMap);
1065 d->sendDataChanged();
1068 bool QAction::isEnabled() const
1075 \property QAction::visible
1076 \brief whether the action can be seen (e.g. in menus and toolbars)
1078 If \e visible is true the action can be seen (e.g. in menus and
1079 toolbars) and chosen by the user; if \e visible is false the
1080 action cannot be seen or chosen by the user.
1082 Actions which are not visible are \e not grayed out; they do not
1085 By default, this property is true (actions are visible).
1087 void QAction::setVisible(bool b)
1090 if (b == d->visible && b != d->forceInvisible)
1092 QAPP_CHECK("setVisible");
1093 d->forceInvisible = !b;
1095 d->enabled = b && !d->forceDisabled && (!d->group || d->group->isEnabled()) ;
1096 #ifndef QT_NO_SHORTCUT
1097 d->setShortcutEnabled(d->enabled, qApp->d_func()->shortcutMap);
1099 d->sendDataChanged();
1103 bool QAction::isVisible() const
1113 QAction::event(QEvent *e)
1115 #ifndef QT_NO_SHORTCUT
1116 if (e->type() == QEvent::Shortcut) {
1117 QShortcutEvent *se = static_cast<QShortcutEvent *>(e);
1118 Q_ASSERT_X(se->key() == d_func()->shortcut || d_func()->alternateShortcuts.contains(se->key()),
1120 "Received shortcut event from incorrect shortcut");
1121 if (se->isAmbiguous())
1122 qWarning("QAction::eventFilter: Ambiguous shortcut overload: %s", se->key().toString(QKeySequence::NativeText).toLatin1().constData());
1128 return QObject::event(e);
1132 Returns the user data as set in QAction::setData.
1137 QAction::data() const
1144 \fn void QAction::setData(const QVariant &userData)
1146 Sets the action's internal data to the given \a userData.
1151 QAction::setData(const QVariant &data)
1155 d->sendDataChanged();
1160 Updates the relevant status bar for the \a widget specified by sending a
1161 QStatusTipEvent to its parent widget. Returns true if an event was sent;
1162 otherwise returns false.
1164 If a null widget is specified, the event is sent to the action's parent.
1169 QAction::showStatusText(QWidget *widget)
1171 return d_func()->showStatusText(widget, statusTip());
1175 Sends the relevant signals for ActionEvent \a event.
1177 Action based widgets use this API to cause the QAction
1178 to emit signals as well as emitting their own.
1180 void QAction::activate(ActionEvent event)
1183 if(event == Trigger) {
1184 QPointer<QObject> guard = this;
1186 // the checked action of an exclusive group cannot be unchecked
1187 if (d->checked && (d->group && d->group->isExclusive()
1188 && d->group->checkedAction() == this)) {
1189 if (!guard.isNull())
1190 emit triggered(true);
1193 setChecked(!d->checked);
1195 if (!guard.isNull())
1196 emit triggered(d->checked);
1197 } else if(event == Hover) {
1203 \fn void QAction::triggered(bool checked)
1205 This signal is emitted when an action is activated by the user;
1206 for example, when the user clicks a menu option, toolbar button,
1207 or presses an action's shortcut key combination, or when trigger()
1208 was called. Notably, it is \e not emitted when setChecked() or
1211 If the action is checkable, \a checked is true if the action is
1212 checked, or false if the action is unchecked.
1214 \sa QAction::activate(), QAction::toggled(), checked
1218 \fn void QAction::toggled(bool checked)
1220 This signal is emitted whenever a checkable action changes its
1221 isChecked() status. This can be the result of a user interaction,
1222 or because setChecked() was called.
1224 \a checked is true if the action is checked, or false if the
1225 action is unchecked.
1227 \sa QAction::activate(), QAction::triggered(), checked
1231 \fn void QAction::hovered()
1233 This signal is emitted when an action is highlighted by the user;
1234 for example, when the user pauses with the cursor over a menu option,
1235 toolbar button, or presses an action's shortcut key combination.
1237 \sa QAction::activate()
1241 \fn void QAction::changed()
1243 This signal is emitted when an action has changed. If you
1244 are only interested in actions in a given widget, you can
1245 watch for QWidget::actionEvent() sent with an
1246 QEvent::ActionChanged.
1248 \sa QWidget::actionEvent()
1252 \enum QAction::ActionEvent
1254 This enum type is used when calling QAction::activate()
1256 \value Trigger this will cause the QAction::triggered() signal to be emitted.
1258 \value Hover this will cause the QAction::hovered() signal to be emitted.
1262 \property QAction::menuRole
1263 \brief the action's menu role
1266 This indicates what role the action serves in the application menu on Mac
1267 OS X. By default all action have the TextHeuristicRole, which means that
1268 the action is added based on its text (see QMenuBar for more information).
1270 The menu role can only be changed before the actions are put into the menu
1271 bar in Mac OS X (usually just before the first application window is
1274 void QAction::setMenuRole(MenuRole menuRole)
1277 if (d->menuRole == menuRole)
1280 d->menuRole = menuRole;
1281 d->sendDataChanged();
1284 QAction::MenuRole QAction::menuRole() const
1291 \property QAction::softKeyRole
1292 \brief the action's softkey role
1295 This indicates what type of role this action describes in the softkey framework
1296 on platforms where such a framework is supported. Currently this is only
1297 supported on the Symbian platform.
1299 The softkey role can be changed any time.
1301 void QAction::setSoftKeyRole(SoftKeyRole softKeyRole)
1304 if (d->softKeyRole == softKeyRole)
1307 d->softKeyRole = softKeyRole;
1308 d->sendDataChanged();
1311 QAction::SoftKeyRole QAction::softKeyRole() const
1314 return d->softKeyRole;
1318 \property QAction::iconVisibleInMenu
1319 \brief Whether or not an action should show an icon in a menu
1322 In some applications, it may make sense to have actions with icons in the
1323 toolbar, but not in menus. If true, the icon (if valid) is shown in the menu, when it
1324 is false, it is not shown.
1326 The default is to follow whether the Qt::AA_DontShowIconsInMenus attribute
1327 is set for the application. Explicitly settings this property overrides
1328 the presence (or abscence) of the attribute.
1331 \snippet code/src_gui_kernel_qaction.cpp 0
1333 \sa QAction::icon, QApplication::setAttribute()
1335 void QAction::setIconVisibleInMenu(bool visible)
1338 if (d->iconVisibleInMenu == -1 || visible != bool(d->iconVisibleInMenu)) {
1339 int oldValue = d->iconVisibleInMenu;
1340 d->iconVisibleInMenu = visible;
1341 // Only send data changed if we really need to.
1344 && visible == !QApplication::instance()->testAttribute(Qt::AA_DontShowIconsInMenus))) {
1345 d->sendDataChanged();
1350 bool QAction::isIconVisibleInMenu() const
1353 if (d->iconVisibleInMenu == -1) {
1354 return !QApplication::instance()->testAttribute(Qt::AA_DontShowIconsInMenus);
1356 return d->iconVisibleInMenu;
1361 #include "moc_qaction.cpp"
1363 #endif // QT_NO_ACTION