1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qaction.h"

    43 #include "qactiongroup.h"

    44 

    45 #ifndef QT_NO_ACTION

    46 #include "qaction_p.h"

    47 #include "qapplication.h"

    48 #include "qevent.h"

    49 #include "qlist.h"

    50 #include "qdebug.h"

    51 #include <private/qshortcutmap_p.h>

    52 #include <private/qapplication_p.h>

    53 #include <private/qmenu_p.h>

    54 

    55 #define QAPP_CHECK(functionName) \

    56     if (!qApp) { \

    57         qWarning("QAction: Initialize QApplication before calling '" functionName "'."); \

    58         return; \

    59     }

    60 

    61 QT_BEGIN_NAMESPACE

    62 

    63 /*

    64   internal: guesses a descriptive text from a text suited for a menu entry

    65  */

    66 static QString qt_strippedText(QString s)

    67 {

    68     s.remove( QString::fromLatin1("...") );

    69     int i = 0;

    70     while (i < s.size()) {

    71         ++i;

    72         if (s.at(i-1) != QLatin1Char('&'))

    73             continue;

    74         if (i < s.size() && s.at(i) == QLatin1Char('&'))

    75             ++i;

    76         s.remove(i-1,1);

    77     }

    78     return s.trimmed();

    79 }

    80 

    81 

    82 QActionPrivate::QActionPrivate() : group(0), enabled(1), forceDisabled(0),

    83                                    visible(1), forceInvisible(0), checkable(0), checked(0), separator(0), fontSet(false),

    84                                    menuRole(QAction::TextHeuristicRole), softKeyRole(QAction::NoSoftKey),

    85                                    priority(QAction::NormalPriority), iconVisibleInMenu(-1)

    86 {

    87 #ifdef QT3_SUPPORT

    88     static int qt_static_action_id = -1;

    89     param = id = --qt_static_action_id;

    90     act_signal = 0;

    91 #endif

    92 #ifndef QT_NO_SHORTCUT

    93     shortcutId = 0;

    94     shortcutContext = Qt::WindowShortcut;

    95     autorepeat = true;

    96 #endif

    97 }

    98 

    99 QActionPrivate::~QActionPrivate()

   100 {

   101 }

   102 

   103 bool QActionPrivate::showStatusText(QWidget *widget, const QString &str)

   104 {

   105 #ifdef QT_NO_STATUSTIP

   106     Q_UNUSED(widget);

   107     Q_UNUSED(str);

   108 #else

   109     if(QObject *object = widget ? widget : parent) {

   110         QStatusTipEvent tip(str);

   111         QApplication::sendEvent(object, &tip);

   112         return true;

   113     }

   114 #endif

   115     return false;

   116 }

   117 

   118 void QActionPrivate::sendDataChanged()

   119 {

   120     Q_Q(QAction);

   121     QActionEvent e(QEvent::ActionChanged, q);

   122     for (int i = 0; i < widgets.size(); ++i) {

   123         QWidget *w = widgets.at(i);

   124         QApplication::sendEvent(w, &e);

   125     }

   126 #ifndef QT_NO_GRAPHICSVIEW

   127     for (int i = 0; i < graphicsWidgets.size(); ++i) {

   128         QGraphicsWidget *w = graphicsWidgets.at(i);

   129         QApplication::sendEvent(w, &e);

   130     }

   131 #endif

   132     QApplication::sendEvent(q, &e);

   133 

   134     emit q->changed();

   135 }

   136 

   137 #ifndef QT_NO_SHORTCUT

   138 void QActionPrivate::redoGrab(QShortcutMap &map)

   139 {

   140     Q_Q(QAction);

   141     if (shortcutId)

   142         map.removeShortcut(shortcutId, q);

   143     if (shortcut.isEmpty())

   144         return;

   145     shortcutId = map.addShortcut(q, shortcut, shortcutContext);

   146     if (!enabled)

   147         map.setShortcutEnabled(false, shortcutId, q);

   148     if (!autorepeat)

   149         map.setShortcutAutoRepeat(false, shortcutId, q);

   150 }

   151 

   152 void QActionPrivate::redoGrabAlternate(QShortcutMap &map)

   153 {

   154     Q_Q(QAction);

   155     for(int i = 0; i < alternateShortcutIds.count(); ++i) {

   156         if (const int id = alternateShortcutIds.at(i))

   157             map.removeShortcut(id, q);

   158     }

   159     alternateShortcutIds.clear();

   160     if (alternateShortcuts.isEmpty())

   161         return;

   162     for(int i = 0; i < alternateShortcuts.count(); ++i) {

   163         const QKeySequence& alternate = alternateShortcuts.at(i);

   164         if (!alternate.isEmpty())

   165             alternateShortcutIds.append(map.addShortcut(q, alternate, shortcutContext));

   166         else

   167             alternateShortcutIds.append(0);

   168     }

   169     if (!enabled) {

   170         for(int i = 0; i < alternateShortcutIds.count(); ++i) {

   171             const int id = alternateShortcutIds.at(i);

   172             map.setShortcutEnabled(false, id, q);

   173         }

   174     }

   175     if (!autorepeat) {

   176         for(int i = 0; i < alternateShortcutIds.count(); ++i) {

   177             const int id = alternateShortcutIds.at(i);

   178             map.setShortcutAutoRepeat(false, id, q);

   179         }

   180     }

   181 }

   182 

   183 void QActionPrivate::setShortcutEnabled(bool enable, QShortcutMap &map)

   184 {

   185     Q_Q(QAction);

   186     if (shortcutId)

   187         map.setShortcutEnabled(enable, shortcutId, q);

   188     for(int i = 0; i < alternateShortcutIds.count(); ++i) {

   189         if (const int id = alternateShortcutIds.at(i))

   190             map.setShortcutEnabled(enable, id, q);

   191     }

   192 }

   193 #endif // QT_NO_SHORTCUT

   194 

   195 

   196 /*!

   197     \class QAction

   198     \brief The QAction class provides an abstract user interface

   199     action that can be inserted into widgets.

   200 

   201     \ingroup mainwindow-classes

   202 

   203 

   204     \omit

   205         * parent and widget are different

   206         * parent does not define context

   207     \endomit

   208 

   209     In applications many common commands can be invoked via menus,

   210     toolbar buttons, and keyboard shortcuts. Since the user expects

   211     each command to be performed in the same way, regardless of the

   212     user interface used, it is useful to represent each command as

   213     an \e action.

   214 

   215     Actions can be added to menus and toolbars, and will

   216     automatically keep them in sync. For example, in a word processor,

   217     if the user presses a Bold toolbar button, the Bold menu item

   218     will automatically be checked.

   219 

   220     Actions can be created as independent objects, but they may

   221     also be created during the construction of menus; the QMenu class

   222     contains convenience functions for creating actions suitable for

   223     use as menu items.

   224 

   225     A QAction may contain an icon, menu text, a shortcut, status text,

   226     "What's This?" text, and a tooltip. Most of these can be set in

   227     the constructor. They can also be set independently with

   228     setIcon(), setText(), setIconText(), setShortcut(),

   229     setStatusTip(), setWhatsThis(), and setToolTip(). For menu items,

   230     it is possible to set an individual font with setFont().

   231 

   232     Actions are added to widgets using QWidget::addAction() or

   233     QGraphicsWidget::addAction(). Note that an action must be added to a

   234     widget before it can be used; this is also true when the shortcut should

   235     be global (i.e., Qt::ApplicationShortcut as Qt::ShortcutContext).

   236 

   237     Once a QAction has been created it should be added to the relevant

   238     menu and toolbar, then connected to the slot which will perform

   239     the action. For example:

   240 

   241     \snippet examples/mainwindows/application/mainwindow.cpp 19

   242     \codeline

   243     \snippet examples/mainwindows/application/mainwindow.cpp 28

   244     \snippet examples/mainwindows/application/mainwindow.cpp 31

   245 

   246     We recommend that actions are created as children of the window

   247     they are used in. In most cases actions will be children of

   248     the application's main window.

   249 

   250     \sa QMenu, QToolBar, {Application Example}

   251 */

   252 

   253 /*!

   254     \fn void QAction::trigger()

   255 

   256     This is a convenience slot that calls activate(Trigger).

   257 */

   258 

   259 /*!

   260     \fn void QAction::hover()

   261 

   262     This is a convenience slot that calls activate(Hover).

   263 */

   264 

   265 /*!

   266     \enum QAction::MenuRole

   267 

   268     This enum describes how an action should be moved into the application menu on Mac OS X.

   269 

   270     \value NoRole This action should not be put into the application menu

   271     \value TextHeuristicRole This action should be put in the application menu based on the action's text

   272            as described in the QMenuBar documentation.

   273     \value ApplicationSpecificRole This action should be put in the application menu with an application specific role

   274     \value AboutQtRole This action matches handles the "About Qt" menu item.

   275     \value AboutRole This action should be placed where the "About" menu item is in the application menu. The text of

   276            the menu item will be set to "About <application name>". The application name is fetched from the

   277            \c{Info.plist} file in the application's bundle (See \l{Deploying an Application on Mac OS X}).

   278     \value PreferencesRole This action should be placed where the  "Preferences..." menu item is in the application menu.

   279     \value QuitRole This action should be placed where the Quit menu item is in the application menu.

   280 

   281     Setting this value only has effect on items that are in the immediate menus

   282     of the menubar, not the submenus of those menus. For example, if you have

   283     File menu in your menubar and the File menu has a submenu, setting the

   284     MenuRole for the actions in that submenu have no effect. They will never be moved.

   285 */

   286 

   287 /*! \since 4.6

   288 

   289     \enum QAction::SoftKeyRole

   290 

   291     This enum describes how an action should be placed in the softkey bar. Currently this enum only

   292     has an effect on the Symbian platform.

   293 

   294     \value NoSoftKey This action should not be used as a softkey

   295     \value PositiveSoftKey This action is used to describe a softkey with a positive or non-destructive

   296            role such as Ok, Select, or Options.

   297     \value NegativeSoftKey This action is used to describe a soft ey with a negative or destructive role

   298            role such as Cancel, Discard, or Close.

   299     \value SelectSoftKey This action is used to describe a role that selects a particular item or widget

   300            in the application.

   301 

   302     Actions with a softkey role defined are only visible in the softkey bar when the widget containing

   303     the action has focus. If no widget currently has focus, the softkey framework will traverse up the

   304     widget parent hierarchy looking for a widget containing softkey actions.

   305  */

   306 

   307 /*!

   308     Constructs an action with \a parent. If \a parent is an action

   309     group the action will be automatically inserted into the group.

   310 */

   311 QAction::QAction(QObject* parent)

   312     : QObject(*(new QActionPrivate), parent)

   313 {

   314     Q_D(QAction);

   315     d->group = qobject_cast<QActionGroup *>(parent);

   316     if (d->group)

   317         d->group->addAction(this);

   318 }

   319 

   320 

   321 /*!

   322     Constructs an action with some \a text and \a parent. If \a

   323     parent is an action group the action will be automatically

   324     inserted into the group.

   325 

   326     The action uses a stripped version of \a text (e.g. "\&Menu

   327     Option..." becomes "Menu Option") as descriptive text for

   328     tool buttons. You can override this by setting a specific

   329     description with setText(). The same text will be used for

   330     tooltips unless you specify a different text using

   331     setToolTip().

   332 

   333 */

   334 QAction::QAction(const QString &text, QObject* parent)

   335     : QObject(*(new QActionPrivate), parent)

   336 {

   337     Q_D(QAction);

   338     d->text = text;

   339     d->group = qobject_cast<QActionGroup *>(parent);

   340     if (d->group)

   341         d->group->addAction(this);

   342 }

   343 

   344 /*!

   345     Constructs an action with an \a icon and some \a text and \a

   346     parent. If \a parent is an action group the action will be

   347     automatically inserted into the group.

   348 

   349     The action uses a stripped version of \a text (e.g. "\&Menu

   350     Option..." becomes "Menu Option") as descriptive text for

   351     tool buttons. You can override this by setting a specific

   352     description with setText(). The same text will be used for

   353     tooltips unless you specify a different text using

   354     setToolTip().

   355 */

   356 QAction::QAction(const QIcon &icon, const QString &text, QObject* parent)

   357     : QObject(*(new QActionPrivate), parent)

   358 {

   359     Q_D(QAction);

   360     d->icon = icon;

   361     d->text = text;

   362     d->group = qobject_cast<QActionGroup *>(parent);

   363     if (d->group)

   364         d->group->addAction(this);

   365 }

   366 

   367 /*!

   368     \internal

   369 */

   370 QAction::QAction(QActionPrivate &dd, QObject *parent)

   371     : QObject(dd, parent)

   372 {

   373     Q_D(QAction);

   374     d->group = qobject_cast<QActionGroup *>(parent);

   375     if (d->group)

   376         d->group->addAction(this);

   377 }

   378 

   379 /*!

   380     Returns the parent widget.

   381 */

   382 QWidget *QAction::parentWidget() const

   383 {

   384     QObject *ret = parent();

   385     while (ret && !ret->isWidgetType())

   386         ret = ret->parent();

   387     return (QWidget*)ret;

   388 }

   389 

   390 /*!

   391   \since 4.2

   392   Returns a list of widgets this action has been added to.

   393 

   394   \sa QWidget::addAction(), associatedGraphicsWidgets()

   395 */

   396 QList<QWidget *> QAction::associatedWidgets() const

   397 {

   398     Q_D(const QAction);

   399     return d->widgets;

   400 }

   401 

   402 #ifndef QT_NO_GRAPHICSVIEW

   403 /*!

   404   \since 4.5

   405   Returns a list of widgets this action has been added to.

   406 

   407   \sa QWidget::addAction(), associatedWidgets()

   408 */

   409 QList<QGraphicsWidget *> QAction::associatedGraphicsWidgets() const

   410 {

   411     Q_D(const QAction);

   412     return d->graphicsWidgets;

   413 }

   414 #endif

   415 

   416 #ifndef QT_NO_SHORTCUT

   417 /*!

   418     \property QAction::shortcut

   419     \brief the action's primary shortcut key

   420 

   421     Valid keycodes for this property can be found in \l Qt::Key and

   422     \l Qt::Modifier. There is no default shortcut key.

   423 */

   424 void QAction::setShortcut(const QKeySequence &shortcut)

   425 {

   426     QAPP_CHECK("setShortcut");

   427 

   428     Q_D(QAction);

   429     if (d->shortcut == shortcut)

   430         return;

   431 

   432     d->shortcut = shortcut;

   433     d->redoGrab(qApp->d_func()->shortcutMap);

   434     d->sendDataChanged();

   435 }

   436 

   437 /*!

   438     \since 4.2

   439 

   440     Sets \a shortcuts as the list of shortcuts that trigger the

   441     action. The first element of the list is the primary shortcut.

   442 

   443     \sa shortcut

   444 */

   445 void QAction::setShortcuts(const QList<QKeySequence> &shortcuts)

   446 {

   447     Q_D(QAction);

   448 

   449     QList <QKeySequence> listCopy = shortcuts;

   450 

   451     QKeySequence primary;

   452     if (!listCopy.isEmpty())

   453         primary = listCopy.takeFirst();

   454 

   455     if (d->shortcut == primary && d->alternateShortcuts == listCopy)

   456         return;

   457 

   458     QAPP_CHECK("setShortcuts");

   459 

   460     d->shortcut = primary;

   461     d->alternateShortcuts = listCopy;

   462     d->redoGrab(qApp->d_func()->shortcutMap);

   463     d->redoGrabAlternate(qApp->d_func()->shortcutMap);

   464     d->sendDataChanged();

   465 }

   466 

   467 /*!

   468     \since 4.2

   469 

   470     Sets a platform dependent list of shortcuts based on the \a key.

   471     The result of calling this function will depend on the currently running platform.

   472     Note that more than one shortcut can assigned by this action.

   473     If only the primary shortcut is required, use setShortcut instead.

   474 

   475     \sa QKeySequence::keyBindings()

   476 */

   477 void QAction::setShortcuts(QKeySequence::StandardKey key)

   478 {

   479     QList <QKeySequence> list = QKeySequence::keyBindings(key);

   480     setShortcuts(list);

   481 }

   482 

   483 /*!

   484     Returns the primary shortcut.

   485 

   486     \sa setShortcuts()

   487 */

   488 QKeySequence QAction::shortcut() const

   489 {

   490     Q_D(const QAction);

   491     return d->shortcut;

   492 }

   493 

   494 /*!

   495     \since 4.2

   496 

   497     Returns the list of shortcuts, with the primary shortcut as

   498     the first element of the list.

   499 

   500     \sa setShortcuts()

   501 */

   502 QList<QKeySequence> QAction::shortcuts() const

   503 {

   504     Q_D(const QAction);

   505     QList <QKeySequence> shortcuts;

   506     if (!d->shortcut.isEmpty())

   507         shortcuts << d->shortcut;

   508     if (!d->alternateShortcuts.isEmpty())

   509         shortcuts << d->alternateShortcuts;

   510     return shortcuts;

   511 }

   512 

   513 /*!

   514     \property QAction::shortcutContext

   515     \brief the context for the action's shortcut

   516 

   517     Valid values for this property can be found in \l Qt::ShortcutContext.

   518     The default value is Qt::WindowShortcut.

   519 */

   520 void QAction::setShortcutContext(Qt::ShortcutContext context)

   521 {

   522     Q_D(QAction);

   523     if (d->shortcutContext == context)

   524         return;

   525     QAPP_CHECK("setShortcutContext");

   526     d->shortcutContext = context;

   527     d->redoGrab(qApp->d_func()->shortcutMap);

   528     d->redoGrabAlternate(qApp->d_func()->shortcutMap);

   529     d->sendDataChanged();

   530 }

   531 

   532 Qt::ShortcutContext QAction::shortcutContext() const

   533 {

   534     Q_D(const QAction);

   535     return d->shortcutContext;

   536 }

   537 

   538 /*!

   539     \property QAction::autoRepeat

   540     \brief whether the action can auto repeat

   541     \since 4.2

   542 

   543     If true, the action will auto repeat when the keyboard shortcut

   544     combination is held down, provided that keyboard auto repeat is

   545     enabled on the system.

   546     The default value is true.

   547 */

   548 void QAction::setAutoRepeat(bool on)

   549 {

   550     Q_D(QAction);

   551     if (d->autorepeat == on)

   552         return;

   553     QAPP_CHECK("setAutoRepeat");

   554     d->autorepeat = on;

   555     d->redoGrab(qApp->d_func()->shortcutMap);

   556     d->redoGrabAlternate(qApp->d_func()->shortcutMap);

   557     d->sendDataChanged();

   558 }

   559 

   560 bool QAction::autoRepeat() const

   561 {

   562     Q_D(const QAction);

   563     return d->autorepeat;

   564 }

   565 #endif // QT_NO_SHORTCUT

   566 

   567 /*!

   568     \property QAction::font

   569     \brief the action's font

   570 

   571     The font property is used to render the text set on the

   572     QAction. The font will can be considered a hint as it will not be

   573     consulted in all cases based upon application and style.

   574 

   575     By default, this property contains the application's default font.

   576 

   577     \sa QAction::setText() QStyle

   578 */

   579 void QAction::setFont(const QFont &font)

   580 {

   581     Q_D(QAction);

   582     if (d->font == font)

   583         return;

   584 

   585     d->fontSet = true;

   586     d->font = font;

   587     d->sendDataChanged();

   588 }

   589 

   590 QFont QAction::font() const

   591 {

   592     Q_D(const QAction);

   593     return d->font;

   594 }

   595 

   596 #ifdef QT3_SUPPORT

   597 /*!

   598     Use one of the QAction constructors that doesn't take a \a name

   599     argument and call setObjectName() instead.

   600 */

   601 QAction::QAction(QObject* parent, const char* name)

   602  : QObject(*(new QActionPrivate), parent)

   603 {

   604     Q_D(QAction);

   605     setObjectName(QString::fromAscii(name));

   606     d->group = qobject_cast<QActionGroup *>(parent);

   607     if (d->group)

   608         d->group->addAction(this);

   609 }

   610 

   611 

   612 /*!

   613     Use one of the QAction constructors that doesn't take a \a name

   614     argument and call setObjectName() instead.

   615 */

   616 QAction::QAction(const QString &text, const QKeySequence &shortcut, QObject* parent, const char* name)

   617  : QObject(*(new QActionPrivate), parent)

   618 {

   619     Q_D(QAction);

   620     setObjectName(QString::fromAscii(name));

   621     d->text = text;

   622     setShortcut(shortcut);

   623     d->group = qobject_cast<QActionGroup *>(parent);

   624     if (d->group)

   625         d->group->addAction(this);

   626 }

   627 

   628 /*!

   629     Use one of the QAction constructors that doesn't take a \a name

   630     argument and call setObjectName() instead.

   631 */

   632 QAction::QAction(const QIcon &icon, const QString &text, const QKeySequence &shortcut,

   633                  QObject* parent, const char* name)

   634     : QObject(*(new QActionPrivate), parent)

   635 {

   636     Q_D(QAction);

   637     setObjectName(QString::fromAscii(name));

   638     d->text = text;

   639     setShortcut(shortcut);

   640     d->icon = icon;

   641     d->group = qobject_cast<QActionGroup *>(parent);

   642     if (d->group)

   643         d->group->addAction(this);

   644 }

   645 #endif

   646 

   647 /*!

   648     Destroys the object and frees allocated resources.

   649 */

   650 QAction::~QAction()

   651 {

   652     Q_D(QAction);

   653     for (int i = d->widgets.size()-1; i >= 0; --i) {

   654         QWidget *w = d->widgets.at(i);

   655         w->removeAction(this);

   656     }

   657 #ifndef QT_NO_GRAPHICSVIEW

   658     for (int i = d->graphicsWidgets.size()-1; i >= 0; --i) {

   659         QGraphicsWidget *w = d->graphicsWidgets.at(i);

   660         w->removeAction(this);

   661     }

   662 #endif

   663     if (d->group)

   664         d->group->removeAction(this);

   665 #ifndef QT_NO_SHORTCUT

   666     if (d->shortcutId && qApp) {

   667         qApp->d_func()->shortcutMap.removeShortcut(d->shortcutId, this);

   668         for(int i = 0; i < d->alternateShortcutIds.count(); ++i) {

   669             const int id = d->alternateShortcutIds.at(i);

   670             qApp->d_func()->shortcutMap.removeShortcut(id, this);

   671         }

   672     }

   673 #endif

   674 }

   675 

   676 /*!

   677   Sets this action group to \a group. The action will be automatically

   678   added to the group's list of actions.

   679 

   680   Actions within the group will be mutually exclusive.

   681 

   682   \sa QActionGroup, QAction::actionGroup()

   683 */

   684 void QAction::setActionGroup(QActionGroup *group)

   685 {

   686     Q_D(QAction);

   687     if(group == d->group)

   688         return;

   689 

   690     if(d->group)

   691         d->group->removeAction(this);

   692     d->group = group;

   693     if(group)

   694         group->addAction(this);

   695 }

   696 

   697 /*!

   698   Returns the action group for this action. If no action group manages

   699   this action then 0 will be returned.

   700 

   701   \sa QActionGroup, QAction::setActionGroup()

   702 */

   703 QActionGroup *QAction::actionGroup() const

   704 {

   705     Q_D(const QAction);

   706     return d->group;

   707 }

   708 

   709 

   710 /*!

   711     \property QAction::icon

   712     \brief the action's icon

   713 

   714     In toolbars, the icon is used as the tool button icon; in menus,

   715     it is displayed to the left of the menu text. There is no default

   716     icon.

   717 

   718     On Symbian the icons which are passed to softkeys, i.e. to actions with

   719     softkey role, need to have pixmap alpha channel correctly set otherwise

   720     drawing artifacts will appear when softkey is pressed down.

   721 

   722     If a null icon (QIcon::isNull() is passed into this function,

   723     the icon of the action is cleared.

   724 */

   725 void QAction::setIcon(const QIcon &icon)

   726 {

   727     Q_D(QAction);

   728     d->icon = icon;

   729     d->sendDataChanged();

   730 }

   731 

   732 QIcon QAction::icon() const

   733 {

   734     Q_D(const QAction);

   735     return d->icon;

   736 }

   737 

   738 #ifndef QT_NO_MENU

   739 /*!

   740   Returns the menu contained by this action. Actions that contain

   741   menus can be used to create menu items with submenus, or inserted

   742   into toolbars to create buttons with popup menus.

   743 

   744   \sa QMenu::addAction()

   745 */

   746 QMenu *QAction::menu() const

   747 {

   748     Q_D(const QAction);

   749     return d->menu;

   750 }

   751 

   752 /*!

   753     Sets the menu contained by this action to the specified \a menu.

   754 */

   755 void QAction::setMenu(QMenu *menu)

   756 {

   757     Q_D(QAction);

   758     if (d->menu)

   759         d->menu->d_func()->setOverrideMenuAction(0); //we reset the default action of any previous menu

   760     d->menu = menu;

   761     if (menu)

   762         menu->d_func()->setOverrideMenuAction(this);

   763     d->sendDataChanged();

   764 }

   765 #endif // QT_NO_MENU

   766 

   767 /*!

   768   If \a b is true then this action will be considered a separator.

   769 

   770   How a separator is represented depends on the widget it is inserted

   771   into. Under most circumstances the text, submenu, and icon will be

   772   ignored for separator actions.

   773 

   774   \sa QAction::isSeparator()

   775 */

   776 void QAction::setSeparator(bool b)

   777 {

   778     Q_D(QAction);

   779     if (d->separator == b)

   780         return;

   781 

   782     d->separator = b;

   783     d->sendDataChanged();

   784 }

   785 

   786 /*!

   787   Returns true if this action is a separator action; otherwise it

   788   returns false.

   789 

   790   \sa QAction::setSeparator()

   791 */

   792 bool QAction::isSeparator() const

   793 {

   794     Q_D(const QAction);

   795     return d->separator;

   796 }

   797 

   798 /*!

   799     \property QAction::text

   800     \brief the action's descriptive text

   801 

   802     If the action is added to a menu, the menu option will consist of

   803     the icon (if there is one), the text, and the shortcut (if there

   804     is one). If the text is not explicitly set in the constructor, or

   805     by using setText(), the action's description icon text will be

   806     used as text. There is no default text.

   807 

   808     \sa iconText

   809 */

   810 void QAction::setText(const QString &text)

   811 {

   812     Q_D(QAction);

   813     if (d->text == text)

   814         return;

   815 

   816     d->text = text;

   817     d->sendDataChanged();

   818 }

   819 

   820 QString QAction::text() const

   821 {

   822     Q_D(const QAction);

   823     QString s = d->text;

   824     if(s.isEmpty()) {

   825         s = d->iconText;

   826         s.replace(QLatin1Char('&'), QLatin1String("&&"));

   827     }

   828     return s;

   829 }

   830 

   831 

   832 

   833 

   834 

   835 /*!

   836     \property QAction::iconText

   837     \brief the action's descriptive icon text

   838 

   839     If QToolBar::toolButtonStyle is set to a value that permits text to

   840     be displayed, the text defined held in this property appears as a

   841     label in the relevant tool button.

   842 

   843     It also serves as the default text in menus and tooltips if the action

   844     has not been defined with setText() or setToolTip(), and will

   845     also be used in toolbar buttons if no icon has been defined using setIcon().

   846 

   847     If the icon text is not explicitly set, the action's normal text will be

   848     used for the icon text.

   849 

   850     By default, this property contains an empty string.

   851 

   852     \sa setToolTip(), setStatusTip()

   853 */

   854 void QAction::setIconText(const QString &text)

   855 {

   856     Q_D(QAction);

   857     if (d->iconText == text)

   858         return;

   859 

   860     d->iconText = text;

   861     d->sendDataChanged();

   862 }

   863 

   864 QString QAction::iconText() const

   865 {

   866     Q_D(const QAction);

   867     if (d->iconText.isEmpty())

   868         return qt_strippedText(d->text);

   869     return d->iconText;

   870 }

   871 

   872 /*!

   873     \property QAction::toolTip

   874     \brief the action's tooltip

   875 

   876     This text is used for the tooltip. If no tooltip is specified,

   877     the action's text is used.

   878 

   879     By default, this property contains the action's text.

   880 

   881     \sa setStatusTip() setShortcut()

   882 */

   883 void QAction::setToolTip(const QString &tooltip)

   884 {

   885     Q_D(QAction);

   886     if (d->tooltip == tooltip)

   887         return;

   888 

   889     d->tooltip = tooltip;

   890     d->sendDataChanged();

   891 }

   892 

   893 QString QAction::toolTip() const

   894 {

   895     Q_D(const QAction);

   896     if (d->tooltip.isEmpty()) {

   897         if (!d->text.isEmpty())

   898             return qt_strippedText(d->text);

   899         return qt_strippedText(d->iconText);

   900     }

   901     return d->tooltip;

   902 }

   903 

   904 /*!

   905     \property QAction::statusTip

   906     \brief the action's status tip

   907 

   908     The status tip is displayed on all status bars provided by the

   909     action's top-level parent widget.

   910 

   911     By default, this property contains an empty string.

   912 

   913     \sa setToolTip() showStatusText()

   914 */

   915 void QAction::setStatusTip(const QString &statustip)

   916 {

   917     Q_D(QAction);

   918     if (d->statustip == statustip)

   919         return;

   920 

   921     d->statustip = statustip;

   922     d->sendDataChanged();

   923 }

   924 

   925 QString QAction::statusTip() const

   926 {

   927     Q_D(const QAction);

   928     return d->statustip;

   929 }

   930 

   931 /*!

   932     \property QAction::whatsThis

   933     \brief the action's "What's This?" help text

   934 

   935     The "What's This?" text is used to provide a brief description of

   936     the action. The text may contain rich text. There is no default

   937     "What's This?" text.

   938 

   939     \sa QWhatsThis Q3StyleSheet

   940 */

   941 void QAction::setWhatsThis(const QString &whatsthis)

   942 {

   943     Q_D(QAction);

   944     if (d->whatsthis == whatsthis)

   945         return;

   946 

   947     d->whatsthis = whatsthis;

   948     d->sendDataChanged();

   949 }

   950 

   951 QString QAction::whatsThis() const

   952 {

   953     Q_D(const QAction);

   954     return d->whatsthis;

   955 }

   956 

   957 /*!

   958     \enum QAction::Priority

   959     \since 4.6

   960 

   961     This enum defines priorities for actions in user interface.

   962 

   963     \value LowPriority The action should not be prioritized in

   964     the user interface.

   965 

   966     \value NormalPriority

   967 

   968     \value HighPriority The action should be prioritized in

   969     the user interface.

   970 

   971     \sa priority

   972 */

   973 

   974 

   975 /*!

   976     \property QAction::priority

   977     \since 4.6

   978 

   979     \brief the actions's priority in the user interface.

   980 

   981     This property can be set to indicate how the action should be prioritized

   982     in the user interface.

   983 

   984     For instance, when toolbars have the Qt::ToolButtonTextBesideIcon

   985     mode set, then actions with LowPriority will not show the text

   986     labels.

   987 */

   988 void QAction::setPriority(Priority priority)

   989 {

   990     Q_D(QAction);

   991     if (d->priority == priority)

   992         return;

   993 

   994     d->priority = priority;

   995     d->sendDataChanged();

   996 }

   997 

   998 QAction::Priority QAction::priority() const

   999 {

  1000     Q_D(const QAction);

  1001     return d->priority;

  1002 }

  1003 

  1004 /*!

  1005     \property QAction::checkable

  1006     \brief whether the action is a checkable action

  1007 

  1008     A checkable action is one which has an on/off state. For example,

  1009     in a word processor, a Bold toolbar button may be either on or

  1010     off. An action which is not a toggle action is a command action;

  1011     a command action is simply executed, e.g. file save.

  1012     By default, this property is false.

  1013 

  1014     In some situations, the state of one toggle action should depend

  1015     on the state of others. For example, "Left Align", "Center" and

  1016     "Right Align" toggle actions are mutually exclusive. To achieve

  1017     exclusive toggling, add the relevant toggle actions to a

  1018     QActionGroup with the QActionGroup::exclusive property set to

  1019     true.

  1020 

  1021     \sa QAction::setChecked()

  1022 */

  1023 void QAction::setCheckable(bool b)

  1024 {

  1025     Q_D(QAction);

  1026     if (d->checkable == b)

  1027         return;

  1028 

  1029     d->checkable = b;

  1030     d->checked = false;

  1031     d->sendDataChanged();

  1032 }

  1033 

  1034 bool QAction::isCheckable() const

  1035 {

  1036     Q_D(const QAction);

  1037     return d->checkable;

  1038 }

  1039 

  1040 /*!

  1041     \fn void QAction::toggle()

  1042 

  1043     This is a convenience function for the \l checked property.

  1044     Connect to it to change the checked state to its opposite state.

  1045 */

  1046 void QAction::toggle()

  1047 {

  1048     Q_D(QAction);

  1049     setChecked(!d->checked);

  1050 }

  1051 

  1052 /*!

  1053     \property QAction::checked

  1054     \brief whether the action is checked.

  1055 

  1056     Only checkable actions can be checked.  By default, this is false

  1057     (the action is unchecked).

  1058 

  1059     \sa checkable

  1060 */

  1061 void QAction::setChecked(bool b)

  1062 {

  1063     Q_D(QAction);

  1064     if (!d->checkable || d->checked == b)

  1065         return;

  1066 

  1067     QPointer<QAction> guard(this);

  1068     d->checked = b;

  1069     d->sendDataChanged();

  1070     if (guard)

  1071         emit toggled(b);

  1072 }

  1073 

  1074 bool QAction::isChecked() const

  1075 {

  1076     Q_D(const QAction);

  1077     return d->checked;

  1078 }

  1079 

  1080 /*!

  1081     \fn void QAction::setDisabled(bool b)

  1082 

  1083     This is a convenience function for the \l enabled property, that

  1084     is useful for signals--slots connections. If \a b is true the

  1085     action is disabled; otherwise it is enabled.

  1086 */

  1087 

  1088 /*!

  1089     \property QAction::enabled

  1090     \brief whether the action is enabled

  1091 

  1092     Disabled actions cannot be chosen by the user. They do not

  1093     disappear from menus or toolbars, but they are displayed in a way

  1094     which indicates that they are unavailable. For example, they might

  1095     be displayed using only shades of gray.

  1096 

  1097     \gui{What's This?} help on disabled actions is still available, provided

  1098     that the QAction::whatsThis property is set.

  1099 

  1100     An action will be disabled when all widgets to which it is added

  1101     (with QWidget::addAction()) are disabled or not visible. When an

  1102     action is disabled, it is not possible to trigger it through its

  1103     shortcut.

  1104 

  1105     By default, this property is true (actions are enabled).

  1106 

  1107     \sa text

  1108 */

  1109 void QAction::setEnabled(bool b)

  1110 {

  1111     Q_D(QAction);

  1112     if (b == d->enabled && b != d->forceDisabled)

  1113         return;

  1114     d->forceDisabled = !b;

  1115     if (b && (!d->visible || (d->group && !d->group->isEnabled())))

  1116         return;

  1117     QAPP_CHECK("setEnabled");

  1118     d->enabled = b;

  1119 #ifndef QT_NO_SHORTCUT

  1120     d->setShortcutEnabled(b, qApp->d_func()->shortcutMap);

  1121 #endif

  1122     d->sendDataChanged();

  1123 }

  1124 

  1125 bool QAction::isEnabled() const

  1126 {

  1127     Q_D(const QAction);

  1128     return d->enabled;

  1129 }

  1130 

  1131 /*!

  1132     \property QAction::visible

  1133     \brief whether the action can be seen (e.g. in menus and toolbars)

  1134 

  1135     If \e visible is true the action can be seen (e.g. in menus and