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

     2 **

     3 ** Copyright (C) 2009 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 void QActionPrivate::sendDataChanged()

   104 {

   105     Q_Q(QAction);

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

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

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

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

   110     }

   111 #ifndef QT_NO_GRAPHICSVIEW

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

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

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

   115     }

   116 #endif

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

   118 

   119     emit q->changed();

   120 }

   121 

   122 #ifndef QT_NO_SHORTCUT

   123 void QActionPrivate::redoGrab(QShortcutMap &map)

   124 {

   125     Q_Q(QAction);

   126     if (shortcutId)

   127         map.removeShortcut(shortcutId, q);

   128     if (shortcut.isEmpty())

   129         return;

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

   131     if (!enabled)

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

   133     if (!autorepeat)

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

   135 }

   136 

   137 void QActionPrivate::redoGrabAlternate(QShortcutMap &map)

   138 {

   139     Q_Q(QAction);

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

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

   142             map.removeShortcut(id, q);

   143     }

   144     alternateShortcutIds.clear();

   145     if (alternateShortcuts.isEmpty())

   146         return;

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

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

   149         if (!alternate.isEmpty())

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

   151         else

   152             alternateShortcutIds.append(0);

   153     }

   154     if (!enabled) {

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

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

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

   158         }

   159     }

   160     if (!autorepeat) {

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

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

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

   164         }

   165     }

   166 }

   167 

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

   169 {

   170     Q_Q(QAction);

   171     if (shortcutId)

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

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

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

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

   176     }

   177 }

   178 #endif // QT_NO_SHORTCUT

   179 

   180 

   181 /*!

   182     \class QAction

   183     \brief The QAction class provides an abstract user interface

   184     action that can be inserted into widgets.

   185 

   186     \ingroup mainwindow-classes

   187 

   188 

   189     \omit

   190         * parent and widget are different

   191         * parent does not define context

   192     \endomit

   193 

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

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

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

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

   198     an \e action.

   199 

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

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

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

   203     will automatically be checked.

   204 

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

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

   207     contains convenience functions for creating actions suitable for

   208     use as menu items.

   209 

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

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

   212     the constructor. They can also be set independently with

   213     setIcon(), setText(), setIconText(), setShortcut(),

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

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

   216 

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

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

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

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

   221 

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

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

   224     the action. For example:

   225 

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

   227     \codeline

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

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

   230 

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

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

   233     the application's main window.

   234 

   235     \sa QMenu, QToolBar, {Application Example}

   236 */

   237 

   238 /*!

   239     \fn void QAction::trigger()

   240 

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

   242 */

   243 

   244 /*!

   245     \fn void QAction::hover()

   246 

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

   248 */

   249 

   250 /*!

   251     \enum QAction::MenuRole

   252 

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

   254 

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

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

   257            as described in the QMenuBar documentation.

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

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

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

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

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

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

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

   265 

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

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

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

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

   270 */

   271 

   272 /*! \since 4.6

   273 

   274     \enum QAction::SoftKeyRole

   275 

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

   277     has an effect on the Symbian platform.

   278 

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

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

   281            role such as Ok, Select, or Options.

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

   283            role such as Cancel, Discard, or Close.

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

   285            in the application.

   286 

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

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

   289     widget parent heirarchy looking for a widget containing softkey actions.

   290  */

   291 

   292 /*!

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

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

   295 */

   296 QAction::QAction(QObject* parent)

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

   298 {

   299     Q_D(QAction);

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

   301     if (d->group)

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

   303 }

   304 

   305 

   306 /*!

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

   308     parent is an action group the action will be automatically

   309     inserted into the group.

   310 

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

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

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

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

   315     tooltips unless you specify a different text using

   316     setToolTip().

   317 

   318 */

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

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

   321 {

   322     Q_D(QAction);

   323     d->text = text;

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

   325     if (d->group)

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

   327 }

   328 

   329 /*!

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

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

   332     automatically inserted into the group.

   333 

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

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

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

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

   338     tooltips unless you specify a different text using

   339     setToolTip().

   340 */

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

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

   343 {

   344     Q_D(QAction);

   345     d->icon = icon;

   346     d->text = text;

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

   348     if (d->group)

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

   350 }

   351 

   352 /*!

   353     \internal

   354 */

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

   356     : QObject(dd, parent)

   357 {

   358     Q_D(QAction);

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

   360     if (d->group)

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

   362 }

   363 

   364 /*!

   365     Returns the parent widget.

   366 */

   367 QWidget *QAction::parentWidget() const

   368 {

   369     QObject *ret = parent();

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

   371         ret = ret->parent();

   372     return (QWidget*)ret;

   373 }

   374 

   375 /*!

   376   \since 4.2

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

   378 

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

   380 */

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

   382 {

   383     Q_D(const QAction);

   384     return d->widgets;

   385 }

   386 

   387 #ifndef QT_NO_GRAPHICSVIEW

   388 /*!

   389   \since 4.5

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

   391 

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

   393 */

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

   395 {

   396     Q_D(const QAction);

   397     return d->graphicsWidgets;

   398 }

   399 #endif

   400 

   401 #ifndef QT_NO_SHORTCUT

   402 /*!

   403     \property QAction::shortcut

   404     \brief the action's primary shortcut key

   405 

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

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

   408 */

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

   410 {

   411     QAPP_CHECK("setShortcut");

   412 

   413     Q_D(QAction);

   414     if (d->shortcut == shortcut)

   415         return;

   416 

   417     d->shortcut = shortcut;

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

   419     d->sendDataChanged();

   420 }

   421 

   422 /*!

   423     \since 4.2

   424 

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

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

   427 

   428     \sa shortcut

   429 */

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

   431 {

   432     Q_D(QAction);

   433 

   434     QList <QKeySequence> listCopy = shortcuts;

   435 

   436     QKeySequence primary;

   437     if (!listCopy.isEmpty())

   438         primary = listCopy.takeFirst();

   439 

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

   441         return;

   442 

   443     QAPP_CHECK("setShortcuts");

   444 

   445     d->shortcut = primary;

   446     d->alternateShortcuts = listCopy;

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

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

   449     d->sendDataChanged();

   450 }

   451 

   452 /*!

   453     \since 4.2

   454 

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

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

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

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

   459 

   460     \sa QKeySequence::keyBindings()

   461 */

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

   463 {

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

   465     setShortcuts(list);

   466 }

   467 

   468 /*!

   469     Returns the primary shortcut.

   470 

   471     \sa setShortcuts()

   472 */

   473 QKeySequence QAction::shortcut() const

   474 {

   475     Q_D(const QAction);

   476     return d->shortcut;

   477 }

   478 

   479 /*!

   480     \since 4.2

   481 

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

   483     the first element of the list.

   484 

   485     \sa setShortcuts()

   486 */

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

   488 {

   489     Q_D(const QAction);

   490     QList <QKeySequence> shortcuts;

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

   492         shortcuts << d->shortcut;

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

   494         shortcuts << d->alternateShortcuts;

   495     return shortcuts;

   496 }

   497 

   498 /*!

   499     \property QAction::shortcutContext

   500     \brief the context for the action's shortcut

   501 

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

   503     The default value is Qt::WindowShortcut.

   504 */

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

   506 {

   507     Q_D(QAction);

   508     if (d->shortcutContext == context)

   509         return;

   510     QAPP_CHECK("setShortcutContext");

   511     d->shortcutContext = context;

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

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

   514     d->sendDataChanged();

   515 }

   516 

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

   518 {

   519     Q_D(const QAction);

   520     return d->shortcutContext;

   521 }

   522 

   523 /*!

   524     \property QAction::autoRepeat

   525     \brief whether the action can auto repeat

   526     \since 4.2

   527 

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

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

   530     enabled on the system.

   531     The default value is true.

   532 */

   533 void QAction::setAutoRepeat(bool on)

   534 {

   535     Q_D(QAction);

   536     if (d->autorepeat == on)

   537         return;

   538     QAPP_CHECK("setAutoRepeat");

   539     d->autorepeat = on;

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

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

   542     d->sendDataChanged();

   543 }

   544 

   545 bool QAction::autoRepeat() const

   546 {

   547     Q_D(const QAction);

   548     return d->autorepeat;

   549 }

   550 #endif // QT_NO_SHORTCUT

   551 

   552 /*!

   553     \property QAction::font

   554     \brief the action's font

   555 

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

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

   558     consulted in all cases based upon application and style.

   559 

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

   561 

   562     \sa QAction::setText() QStyle

   563 */

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

   565 {

   566     Q_D(QAction);

   567     if (d->font == font)

   568         return;

   569 

   570     d->fontSet = true;

   571     d->font = font;

   572     d->sendDataChanged();

   573 }

   574 

   575 QFont QAction::font() const

   576 {

   577     Q_D(const QAction);

   578     return d->font;

   579 }

   580 

   581 #ifdef QT3_SUPPORT

   582 /*!

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

   584     argument and call setObjectName() instead.

   585 */

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

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

   588 {

   589     Q_D(QAction);

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

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

   592     if (d->group)

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

   594 }

   595 

   596 

   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(const QString &text, const QKeySequence &shortcut, QObject* parent, const char* name)

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

   603 {

   604     Q_D(QAction);

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

   606     d->text = text;

   607     setShortcut(shortcut);

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

   609     if (d->group)

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

   611 }

   612 

   613 /*!

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

   615     argument and call setObjectName() instead.

   616 */

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

   618                  QObject* parent, const char* name)

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

   620 {

   621     Q_D(QAction);

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

   623     d->text = text;

   624     setShortcut(shortcut);

   625     d->icon = icon;

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

   627     if (d->group)

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

   629 }

   630 #endif

   631 

   632 /*!

   633     Destroys the object and frees allocated resources.

   634 */

   635 QAction::~QAction()

   636 {

   637     Q_D(QAction);

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

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

   640         w->removeAction(this);

   641     }

   642 #ifndef QT_NO_GRAPHICSVIEW

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

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

   645         w->removeAction(this);

   646     }

   647 #endif

   648     if (d->group)

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

   650 #ifndef QT_NO_SHORTCUT

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

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

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

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

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

   656         }

   657     }

   658 #endif

   659 }

   660 

   661 /*!

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

   663   added to the group's list of actions.

   664 

   665   Actions within the group will be mutually exclusive.

   666 

   667   \sa QActionGroup, QAction::actionGroup()

   668 */

   669 void QAction::setActionGroup(QActionGroup *group)

   670 {

   671     Q_D(QAction);

   672     if(group == d->group)

   673         return;

   674 

   675     if(d->group)

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

   677     d->group = group;

   678     if(group)

   679         group->addAction(this);

   680 }

   681 

   682 /*!

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

   684   this action then 0 will be returned.

   685 

   686   \sa QActionGroup, QAction::setActionGroup()

   687 */

   688 QActionGroup *QAction::actionGroup() const

   689 {

   690     Q_D(const QAction);

   691     return d->group;

   692 }

   693 

   694 

   695 /*!

   696     \property QAction::icon

   697     \brief the action's icon

   698 

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

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

   701     icon.

   702 

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

   704     the icon of the action is cleared.

   705 */

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

   707 {

   708     Q_D(QAction);

   709     d->icon = icon;

   710     d->sendDataChanged();

   711 }

   712 

   713 QIcon QAction::icon() const

   714 {

   715     Q_D(const QAction);

   716     return d->icon;

   717 }

   718 

   719 #ifndef QT_NO_MENU

   720 /*!

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

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

   723   into toolbars to create buttons with popup menus.

   724 

   725   \sa QMenu::addAction()

   726 */

   727 QMenu *QAction::menu() const

   728 {

   729     Q_D(const QAction);

   730     return d->menu;

   731 }

   732 

   733 /*!

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

   735 */

   736 void QAction::setMenu(QMenu *menu)

   737 {

   738     Q_D(QAction);

   739     if (d->menu)

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

   741     d->menu = menu;

   742     if (menu)

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

   744     d->sendDataChanged();

   745 }

   746 #endif // QT_NO_MENU

   747 

   748 /*!

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

   750 

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

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

   753   ignored for separator actions.

   754 

   755   \sa QAction::isSeparator()

   756 */

   757 void QAction::setSeparator(bool b)

   758 {

   759     Q_D(QAction);

   760     if (d->separator == b)

   761         return;

   762 

   763     d->separator = b;

   764     d->sendDataChanged();

   765 }

   766 

   767 /*!

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

   769   returns false.

   770 

   771   \sa QAction::setSeparator()

   772 */

   773 bool QAction::isSeparator() const

   774 {

   775     Q_D(const QAction);

   776     return d->separator;

   777 }

   778 

   779 /*!

   780     \property QAction::text

   781     \brief the action's descriptive text

   782 

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

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

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

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

   787     used as text. There is no default text.

   788 

   789     \sa iconText

   790 */

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

   792 {

   793     Q_D(QAction);

   794     if (d->text == text)

   795         return;

   796 

   797     d->text = text;

   798     d->sendDataChanged();

   799 }

   800 

   801 QString QAction::text() const

   802 {

   803     Q_D(const QAction);

   804     QString s = d->text;

   805     if(s.isEmpty()) {

   806         s = d->iconText;

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

   808     }

   809     return s;

   810 }

   811 

   812 

   813 

   814 

   815 

   816 /*!

   817     \property QAction::iconText

   818     \brief the action's descriptive icon text

   819 

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

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

   822     label in the relevant tool button.

   823 

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

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

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

   827 

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

   829     used for the icon text.

   830 

   831     By default, this property contains an empty string.

   832 

   833     \sa setToolTip(), setStatusTip()

   834 */

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

   836 {

   837     Q_D(QAction);

   838     if (d->iconText == text)

   839         return;

   840 

   841     d->iconText = text;

   842     d->sendDataChanged();

   843 }

   844 

   845 QString QAction::iconText() const

   846 {

   847     Q_D(const QAction);

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

   849         return qt_strippedText(d->text);

   850     return d->iconText;

   851 }

   852 

   853 /*!

   854     \property QAction::toolTip

   855     \brief the action's tooltip

   856 

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

   858     the action's text is used.

   859 

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

   861 

   862     \sa setStatusTip() setShortcut()

   863 */

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

   865 {

   866     Q_D(QAction);

   867     if (d->tooltip == tooltip)

   868         return;

   869 

   870     d->tooltip = tooltip;

   871     d->sendDataChanged();

   872 }

   873 

   874 QString QAction::toolTip() const

   875 {

   876     Q_D(const QAction);

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

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

   879             return qt_strippedText(d->text);

   880         return qt_strippedText(d->iconText);

   881     }

   882     return d->tooltip;

   883 }

   884 

   885 /*!

   886     \property QAction::statusTip

   887     \brief the action's status tip

   888 

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

   890     action's top-level parent widget.

   891 

   892     By default, this property contains an empty string.

   893 

   894     \sa setToolTip() showStatusText()

   895 */

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

   897 {

   898     Q_D(QAction);

   899     if (d->statustip == statustip)

   900         return;

   901 

   902     d->statustip = statustip;

   903     d->sendDataChanged();

   904 }

   905 

   906 QString QAction::statusTip() const

   907 {

   908     Q_D(const QAction);

   909     return d->statustip;

   910 }

   911 

   912 /*!

   913     \property QAction::whatsThis

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

   915 

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

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

   918     "What's This?" text.

   919 

   920     \sa QWhatsThis Q3StyleSheet

   921 */

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

   923 {

   924     Q_D(QAction);

   925     if (d->whatsthis == whatsthis)

   926         return;

   927 

   928     d->whatsthis = whatsthis;

   929     d->sendDataChanged();

   930 }

   931 

   932 QString QAction::whatsThis() const

   933 {

   934     Q_D(const QAction);

   935     return d->whatsthis;

   936 }

   937 

   938 /*!

   939     \enum QAction::Priority

   940     \since 4.6

   941 

   942     This enum defines priorities for actions in user interface.

   943 

   944     \value LowPriority The action should not be prioritized in

   945     the user interface.

   946 

   947     \value NormalPriority

   948 

   949     \value HighPriority The action should be prioritized in

   950     the user interface.

   951 

   952     \sa priority

   953 */

   954 

   955 

   956 /*!

   957     \property QAction::priority

   958     \since 4.6

   959 

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

   961 

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

   963     in the user interface.

   964 

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

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

   967     labels.

   968 */

   969 void QAction::setPriority(Priority priority)

   970 {

   971     Q_D(QAction);

   972     if (d->priority == priority)

   973         return;

   974 

   975     d->priority = priority;

   976     d->sendDataChanged();

   977 }

   978 

   979 QAction::Priority QAction::priority() const

   980 {

   981     Q_D(const QAction);

   982     return d->priority;

   983 }

   984 

   985 /*!

   986     \property QAction::checkable

   987     \brief whether the action is a checkable action

   988 

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

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

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

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

   993     By default, this property is false.

   994 

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

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

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

   998     exclusive toggling, add the relevant toggle actions to a

   999     QActionGroup with the QActionGroup::exclusive property set to

  1000     true.

  1001 

  1002     \sa QAction::setChecked()

  1003 */

  1004 void QAction::setCheckable(bool b)

  1005 {

  1006     Q_D(QAction);

  1007     if (d->checkable == b)

  1008         return;

  1009 

  1010     d->checkable = b;

  1011     d->checked = false;

  1012     d->sendDataChanged();

  1013 }

  1014 

  1015 bool QAction::isCheckable() const

  1016 {

  1017     Q_D(const QAction);

  1018     return d->checkable;

  1019 }

  1020 

  1021 /*!

  1022     \fn void QAction::toggle()

  1023 

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

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

  1026 */

  1027 void QAction::toggle()

  1028 {

  1029     Q_D(QAction);

  1030     setChecked(!d->checked);

  1031 }

  1032 

  1033 /*!

  1034     \property QAction::checked

  1035     \brief whether the action is checked.

  1036 

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

  1038     (the action is unchecked).

  1039 

  1040     \sa checkable

  1041 */

  1042 void QAction::setChecked(bool b)

  1043 {

  1044     Q_D(QAction);

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

  1046         return;

  1047 

  1048     QPointer<QAction> guard(this);

  1049     d->checked = b;

  1050     d->sendDataChanged();

  1051     if (guard)

  1052         emit toggled(b);

  1053 }

  1054 

  1055 bool QAction::isChecked() const

  1056 {

  1057     Q_D(const QAction);

  1058     return d->checked;

  1059 }

  1060 

  1061 /*!

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

  1063 

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

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

  1066     action is disabled; otherwise it is enabled.

  1067 */

  1068 

  1069 /*!

  1070     \property QAction::enabled

  1071     \brief whether the action is enabled

  1072 

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

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

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

  1076     be displayed using only shades of gray.

  1077 

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

  1079     that the QAction::whatsThis property is set.

  1080 

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

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

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

  1084     shortcut.

  1085 

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

  1087 

  1088     \sa text

  1089 */

  1090 void QAction::setEnabled(bool b)

  1091 {

  1092     Q_D(QAction);

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

  1094         return;

  1095     d->forceDisabled = !b;

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

  1097         return;

  1098     QAPP_CHECK("setEnabled");

  1099     d->enabled = b;

  1100 #ifndef QT_NO_SHORTCUT

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

  1102 #endif

  1103     d->sendDataChanged();

  1104 }

  1105 

  1106 bool QAction::isEnabled() const

  1107 {

  1108     Q_D(const QAction);

  1109     return d->enabled;

  1110 }

  1111 

  1112 /*!

  1113     \property QAction::visible

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

  1115 

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

  1117     toolbars) and chosen by the user; if \e visible is false the

  1118     action cannot be seen or chosen by the user.

  1119 

  1120     Actions which are not visible are \e not grayed out; they do not

  1121     appear at all.

  1122 

  1123     By default, this property is true (actions are visible).

  1124 */

  1125 void QAction::setVisible(bool b)

  1126 {

  1127     Q_D(QAction);

  1128     if (b == d->visible && b != d->forceInvisible)

  1129         return;

  1130     QAPP_CHECK("setVisible");

  1131     d->forceInvisible = !b;

  1132     d->visible = b;

  1133     d->enabled = b && !d->forceDisabled && (!d->group || d->group->isEnabled()) ;

  1134 #ifndef QT_NO_SHORTCUT