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 Qt3Support 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 "q3action.h"

    43 

    44 #ifndef QT_NO_ACTION

    45 

    46 #include "qevent.h"

    47 #include "q3toolbar.h"

    48 #include "qlist.h"

    49 #include "q3popupmenu.h"

    50 #include "q3accel.h"

    51 #include "qtoolbutton.h"

    52 #include "qcombobox.h"

    53 #include "qtooltip.h"

    54 #include "qwhatsthis.h"

    55 #include "qstatusbar.h"

    56 #include "qaction.h"

    57 

    58 QT_BEGIN_NAMESPACE

    59 

    60 /*!

    61     \class Q3Action

    62     \brief The Q3Action class provides an abstract user interface

    63     action that can appear both in menus and tool bars.

    64 

    65     \compat

    66 

    67     In GUI applications many commands can be invoked via a menu

    68     option, a toolbar button and a keyboard accelerator. Since the

    69     same action must be performed regardless of how the action was

    70     invoked, and since the menu and toolbar should be kept in sync, it

    71     is useful to represent a command as an \e action. An action can be

    72     added to a menu and a toolbar and will automatically keep them in

    73     sync. For example, if the user presses a Bold toolbar button the

    74     Bold menu item will automatically be checked.

    75 

    76     A Q3Action may contain an icon, a menu text, an accelerator, a

    77     status text, a "What's This?" text and a tool tip. Most of these can

    78     be set in the constructor. They can also be set independently with

    79     setIconSet(), setText(), setMenuText(), setToolTip(),

    80     setStatusTip(), setWhatsThis() and setAccel().

    81 

    82     An action may be a toggle action e.g. a Bold toolbar button, or a

    83     command action, e.g. 'Open File' to invoke an open file dialog.

    84     Toggle actions emit the toggled() signal when their state changes.

    85     Both command and toggle actions emit the activated() signal when

    86     they are invoked. Use setToggleAction() to set an action's toggled

    87     status. To see if an action is a toggle action use

    88     isToggleAction(). A toggle action may be "on", isOn() returns

    89     true, or "off", isOn() returns false.

    90 

    91     Actions are added to widgets (menus or toolbars) using addTo(),

    92     and removed using removeFrom(). Note that when using Q3ToolBar and

    93     Q3PopupMenu, their actions must be Q3Actions.

    94 

    95     Once a Q3Action has been created it should be added to the relevant

    96     menu and toolbar and then connected to the slot which will perform

    97     the action.

    98 

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

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

   101     the application's main window.

   102 

   103     To prevent recursion, don't create an action as a child of a

   104     widget that the action is later added to.

   105 */

   106 

   107 class Q3ActionPrivate

   108 {

   109 public:

   110     Q3ActionPrivate(Q3Action *act);

   111     ~Q3ActionPrivate();

   112     QIcon *icon;

   113     QString text;

   114     QString menutext;

   115     QString tooltip;

   116     QString statustip;

   117     QString whatsthis;

   118 #ifndef QT_NO_ACCEL

   119     QKeySequence key;

   120     Q3Accel* accel;

   121     int accelid;

   122 #endif

   123     uint enabled : 1;

   124     uint visible : 1;

   125     uint toggleaction : 1;

   126     uint on : 1;

   127     uint forceDisabled : 1;

   128     uint forceInvisible : 1;

   129     Q3ActionGroupPrivate* d_group;

   130     Q3Action *action;

   131 

   132     struct MenuItem {

   133         MenuItem():popup(0),id(0){}

   134         Q3PopupMenu* popup;

   135         int id;

   136     };

   137     // ComboItem is only necessary for actions that are

   138     // in dropdown/exclusive actiongroups. The actiongroup

   139     // will clean this up

   140     struct ComboItem {

   141         ComboItem():combo(0), id(0) {}

   142         QComboBox *combo;

   143         int id;

   144     };

   145     //just bindings to the Qt4.0 widgets

   146     struct Action4Item {

   147         Action4Item():widget(0){}

   148         QWidget* widget;

   149         static QAction *action;

   150     };

   151     QList<Action4Item *> action4items;

   152     QList<MenuItem *> menuitems;

   153     QList<QToolButton *> toolbuttons;

   154     QList<ComboItem *> comboitems;

   155 

   156     enum Update { Icons = 1, Visibility = 2, State = 4, EverythingElse = 8 };

   157     void update(uint upd = EverythingElse);

   158 

   159     QString menuText() const;

   160     QString toolTip() const;

   161     QString statusTip() const;

   162 };

   163 QAction *Q3ActionPrivate::Action4Item::action = 0;

   164 

   165 Q3ActionPrivate::Q3ActionPrivate(Q3Action *act)

   166     : icon(0),

   167 #ifndef QT_NO_ACCEL

   168       key(0), accel(0), accelid(0),

   169 #endif

   170       enabled(true), visible(true), toggleaction(false), on(false),

   171       forceDisabled(false), forceInvisible(false)

   172       , d_group(0), action(act)

   173 {

   174 }

   175 

   176 Q3ActionPrivate::~Q3ActionPrivate()

   177 {

   178     QList<QToolButton*>::Iterator ittb(toolbuttons.begin());

   179     QToolButton *tb;

   180 

   181     while (ittb != toolbuttons.end()) {

   182         tb = *ittb;

   183         ++ittb;

   184         delete tb;

   185     }

   186 

   187     QList<Q3ActionPrivate::MenuItem*>::Iterator itmi(menuitems.begin());

   188     Q3ActionPrivate::MenuItem* mi;

   189     while (itmi != menuitems.end()) {

   190         mi = *itmi;

   191         ++itmi;

   192         Q3PopupMenu* menu = mi->popup;

   193         if (menu->findItem(mi->id))

   194             menu->removeItem(mi->id);

   195     }

   196     qDeleteAll(menuitems);

   197 

   198     QList<Q3ActionPrivate::Action4Item*>::Iterator itmi4(action4items.begin());

   199     Q3ActionPrivate::Action4Item* mi4;

   200     while (itmi4 != action4items.end()) {

   201         mi4 = *itmi4;

   202         ++itmi4;

   203         mi4->widget->removeAction(mi4->action);

   204     }

   205     delete Q3ActionPrivate::Action4Item::action;

   206     Q3ActionPrivate::Action4Item::action = 0;

   207     qDeleteAll(action4items);

   208 

   209     QList<Q3ActionPrivate::ComboItem*>::Iterator itci(comboitems.begin());

   210     Q3ActionPrivate::ComboItem* ci;

   211     while (itci != comboitems.end()) {

   212         ci = *itci;

   213         ++itci;

   214         QComboBox* combo = ci->combo;

   215         combo->clear();

   216         Q3ActionGroup *group = qobject_cast<Q3ActionGroup*>(action->parent());

   217         if (group) {

   218             QObjectList siblings = group->queryList("Q3Action");

   219 

   220             for (int i = 0; i < siblings.size(); ++i) {

   221                 Q3Action *sib = qobject_cast<Q3Action*>(siblings.at(i));

   222                 sib->removeFrom(combo);

   223             }

   224             for (int i = 0; i < siblings.size(); ++i) {

   225                 Q3Action *sib = qobject_cast<Q3Action*>(siblings.at(i));

   226                 if (sib == action)

   227                     continue;

   228                 sib->addTo(combo);

   229             }

   230         }

   231     }

   232     qDeleteAll(comboitems);

   233 

   234 #ifndef QT_NO_ACCEL

   235     delete accel;

   236 #endif

   237     delete icon;

   238 }

   239 

   240 class Q3ActionGroupPrivate

   241 {

   242 public:

   243     uint exclusive: 1;

   244     uint dropdown: 1;

   245     QList<Q3Action*> actions;

   246     Q3Action* selected;

   247     Q3Action* separatorAction;

   248 

   249     struct MenuItem {

   250         MenuItem():popup(0),id(0){}

   251         Q3PopupMenu* popup;

   252         int id;

   253     };

   254     struct Action4Item {

   255         Action4Item():widget(0){}

   256         QWidget* widget;

   257         static QAction *action;

   258     };

   259     QList<Action4Item *> action4items;

   260     QList<QComboBox*> comboboxes;

   261     QList<QToolButton*> menubuttons;

   262     QList<MenuItem*> menuitems;

   263     QList<Q3PopupMenu*> popupmenus;

   264 

   265     void update(const Q3ActionGroup *);

   266 };

   267 QAction *Q3ActionGroupPrivate::Action4Item::action = 0;

   268 

   269 void Q3ActionPrivate::update(uint upd)

   270 {

   271     for (QList<MenuItem*>::Iterator it(menuitems.begin()); it != menuitems.end(); ++it) {

   272         MenuItem* mi = *it;

   273         QString t = menuText();

   274 #ifndef QT_NO_ACCEL

   275         if (key)

   276             t += QLatin1Char('\t') + (QString)QKeySequence(key);

   277 #endif

   278         if (upd & State) {

   279             mi->popup->setItemEnabled(mi->id, enabled);

   280             if (toggleaction)

   281                 mi->popup->setItemChecked(mi->id, on);

   282         }

   283         if (upd & Visibility)

   284             mi->popup->setItemVisible(mi->id, visible);

   285 

   286         if (upd & Icons) {

   287             if (icon)

   288                 mi->popup->changeItem(mi->id, *icon, t);

   289             else

   290                 mi->popup->changeItem(mi->id, QIcon(), t);

   291         }

   292         if (upd & EverythingElse) {

   293             mi->popup->changeItem(mi->id, t);

   294             if (!whatsthis.isEmpty())

   295                     mi->popup->setWhatsThis(mi->id, whatsthis);

   296             if (toggleaction) {

   297                 mi->popup->setCheckable(true);

   298                 mi->popup->setItemChecked(mi->id, on);

   299             }

   300         }

   301     }

   302     if(QAction *act = Action4Item::action) {

   303         if (upd & Visibility)

   304             act->setVisible(visible);

   305         if (upd & Icons) {

   306             if (icon)

   307                 act->setIcon(*icon);

   308             else

   309                 act->setIcon(QIcon());

   310         }

   311         if (upd & EverythingElse) {

   312             QString text = action->menuText();

   313 #ifndef QT_NO_ACCEL

   314             if (key)

   315                 text += QLatin1Char('\t') + (QString)QKeySequence(key);

   316 #endif

   317             act->setText(text);

   318             act->setToolTip(statusTip());

   319             act->setWhatsThis(whatsthis);

   320         }

   321     }

   322     for (QList<QToolButton*>::Iterator it2(toolbuttons.begin()); it2 != toolbuttons.end(); ++it2) {

   323         QToolButton* btn = *it2;

   324         if (upd & State) {

   325             btn->setEnabled(enabled);

   326             if (toggleaction)

   327                 btn->setOn(on);

   328         }

   329         if (upd & Visibility)

   330             visible ? btn->show() : btn->hide();

   331         if (upd & Icons) {

   332             if (icon)

   333                 btn->setIconSet(*icon);

   334             else

   335                 btn->setIconSet(QIcon());

   336         }

   337         if (upd & EverythingElse) {

   338             btn->setToggleButton(toggleaction);

   339             if (!text.isEmpty())

   340                 btn->setTextLabel(text, false);

   341 #ifndef QT_NO_TOOLTIP

   342             btn->setToolTip(toolTip());

   343 #endif

   344 #ifndef QT_NO_STATUSTIP

   345             btn->setStatusTip(statusTip());

   346 #endif

   347 #ifndef QT_NO_WHATSTHIS

   348             QWhatsThis::remove(btn);

   349             if (!whatsthis.isEmpty())

   350                 QWhatsThis::add(btn, whatsthis);

   351 #endif

   352         }

   353     }

   354 #ifndef QT_NO_ACCEL

   355     if (accel) {

   356         accel->setEnabled(enabled && visible);

   357         if (!whatsthis.isEmpty())

   358             accel->setWhatsThis(accelid, whatsthis);

   359     }

   360 #endif

   361     // Only used by actiongroup

   362     for (QList<ComboItem*>::Iterator it3(comboitems.begin()); it3 != comboitems.end(); ++it3) {

   363         ComboItem *ci = *it3;

   364         if (!ci->combo)

   365             return;

   366         if (ci->id == -1) {

   367             ci->id = ci->combo->count();

   368             if (icon)

   369                 ci->combo->insertItem(icon->pixmap(), text);

   370             else

   371                 ci->combo->insertItem(text);

   372         } else {

   373             if (icon)

   374                 ci->combo->changeItem(icon->pixmap(), text, ci->id);

   375             else

   376                 ci->combo->changeItem(text, ci->id);

   377         }

   378     }

   379 }

   380 

   381 QString Q3ActionPrivate::menuText() const

   382 {

   383     if (menutext.isNull()) {

   384         QString t(text);

   385         t.replace(QLatin1Char('&'), QLatin1String("&&"));

   386         return t;

   387     }

   388     return menutext;

   389 }

   390 

   391 QString Q3ActionPrivate::toolTip() const

   392 {

   393     if (tooltip.isNull()) {

   394 #ifndef QT_NO_ACCEL

   395         if (accel)

   396             return text + QLatin1String(" (") + (QString)QKeySequence(accel->key(accelid)) + QLatin1Char(')');

   397 #endif

   398         return text;

   399     }

   400     return tooltip;

   401 }

   402 

   403 QString Q3ActionPrivate::statusTip() const

   404 {

   405     if (statustip.isNull())

   406         return toolTip();

   407     return statustip;

   408 }

   409 

   410 /*

   411   internal: guesses a descriptive text from a menu text

   412  */

   413 static QString qt_stripMenuText(QString s)

   414 {

   415     s.remove(QLatin1String("..."));

   416     s.remove(QLatin1Char('&'));

   417     return s.trimmed();

   418 }

   419 

   420 /*!

   421     Constructs an action called \a name with parent \a parent.

   422 

   423     If \a parent is a Q3ActionGroup, the new action inserts itself into

   424     \a parent.

   425 

   426     For accelerators and status tips to work, \a parent must either be

   427     a widget, or an action group whose parent is a widget.

   428 

   429     \warning To prevent recursion, don't create an action as a child

   430     of a widget that the action is later added to.

   431 */

   432 Q3Action::Q3Action(QObject* parent, const char* name)

   433     : QObject(parent, name)

   434 {

   435     d = new Q3ActionPrivate(this);

   436     init();

   437 }

   438 

   439 /*!

   440     Constructs an action called \a name with parent \a parent.

   441 

   442     If \a toggle is true the action will be a toggle action, otherwise

   443     it will be a command action.

   444 

   445     If \a parent is a Q3ActionGroup, the new action inserts itself into

   446     \a parent.

   447 

   448     For accelerators and status tips to work, \a parent must either be

   449     a widget, or an action group whose parent is a widget.

   450 */

   451 Q3Action::Q3Action(QObject* parent, const char* name, bool toggle)

   452     : QObject(parent, name)

   453 {

   454     d = new Q3ActionPrivate(this);

   455     d->toggleaction = toggle;

   456     init();

   457 }

   458 

   459 

   460 #ifndef QT_NO_ACCEL

   461 

   462 /*!

   463     This constructor creates an action with the following properties:

   464     the icon or icon \a icon, the menu text \a menuText and

   465     keyboard accelerator \a accel. It is a child of \a parent and

   466     called \a name.

   467 

   468     If \a parent is a Q3ActionGroup, the action automatically becomes

   469     a member of it.

   470 

   471     For accelerators and status tips to work, \a parent must either be

   472     a widget, or an action group whose parent is a widget.

   473 

   474     The action uses a stripped version of \a menuText (e.g. "\&Menu

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

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

   477     description with setText(). The same text and \a accel will be

   478     used for tool tips and status tips unless you provide text for

   479     these using setToolTip() and setStatusTip().

   480 

   481     Call setToggleAction(true) to make the action a toggle action.

   482 

   483     \warning To prevent recursion, don't create an action as a child

   484     of a widget that the action is later added to.

   485 */

   486 Q3Action::Q3Action(const QIcon& icon, const QString& menuText, QKeySequence accel,

   487                   QObject* parent, const char* name)

   488     : QObject(parent, name)

   489 {

   490     d = new Q3ActionPrivate(this);

   491     if (!icon.isNull())

   492         setIconSet(icon);

   493     d->text = qt_stripMenuText(menuText);

   494     d->menutext = menuText;

   495     setAccel(accel);

   496     init();

   497 }

   498 

   499 /*!

   500     This constructor results in an icon-less action with the menu

   501     text \a menuText and keyboard accelerator \a accel. It is a child

   502     of \a parent and called \a name.

   503 

   504     If  \a parent is a Q3ActionGroup, the action automatically becomes

   505     a member of it.

   506 

   507     For accelerators and status tips to work, \a parent must either be

   508     a widget, or an action group whose parent is a widget.

   509 

   510     The action uses a stripped version of \a menuText (e.g. "\&Menu

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

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

   513     description with setText(). The same text and \a accel will be

   514     used for tool tips and status tips unless you provide text for

   515     these using setToolTip() and setStatusTip().

   516 

   517     Call setToggleAction(true) to make the action a toggle action.

   518 

   519     \warning To prevent recursion, don't create an action as a child

   520     of a widget that the action is later added to.

   521 */

   522 Q3Action::Q3Action(const QString& menuText, QKeySequence accel,

   523                   QObject* parent, const char* name)

   524     : QObject(parent, name)

   525 {

   526     d = new Q3ActionPrivate(this);

   527     d->text = qt_stripMenuText(menuText);

   528     d->menutext = menuText;

   529     setAccel(accel);

   530     init();

   531 }

   532 

   533 /*!

   534     This constructor creates an action with the following properties:

   535     the description \a text, the icon or icon \a icon, the menu

   536     text \a menuText and keyboard accelerator \a accel. It is a child

   537     of \a parent and called \a name. If \a toggle is true the action

   538     will be a toggle action, otherwise it will be a command action.

   539 

   540     If  \a parent is a Q3ActionGroup, the action automatically becomes

   541     a member of it.

   542 

   543     For accelerators and status tips to work, \a parent must either be

   544     a widget, or an action group whose parent is a widget.

   545 

   546     The \a text and \a accel will be used for tool tips and status

   547     tips unless you provide specific text for these using setToolTip()

   548     and setStatusTip().

   549 */

   550 Q3Action::Q3Action(const QString& text, const QIcon& icon, const QString& menuText, QKeySequence accel, QObject* parent, const char* name, bool toggle)

   551     : QObject(parent, name)

   552 {

   553     d = new Q3ActionPrivate(this);

   554     d->toggleaction = toggle;

   555     if (!icon.isNull())

   556         setIconSet(icon);

   557 

   558     d->text = text;

   559     d->menutext = menuText;

   560     setAccel(accel);

   561     init();

   562 }

   563 

   564 /*!

   565     This constructor results in an icon-less action with the

   566     description \a text, the menu text \a menuText and the keyboard

   567     accelerator \a accel. Its parent is \a parent and it is called \a

   568     name. If \a toggle is true the action will be a toggle action,

   569     otherwise it will be a command action.

   570 

   571     The action automatically becomes a member of \a parent if \a

   572     parent is a Q3ActionGroup.

   573 

   574     For accelerators and status tips to work, \a parent must either be

   575     a widget, or an action group whose parent is a widget.

   576 

   577     The \a text and \a accel will be used for tool tips and status

   578     tips unless you provide specific text for these using setToolTip()

   579     and setStatusTip().

   580 */

   581 Q3Action::Q3Action(const QString& text, const QString& menuText, QKeySequence accel, QObject* parent, const char* name, bool toggle)

   582     : QObject(parent, name)

   583 {

   584     d = new Q3ActionPrivate(this);

   585     d->toggleaction = toggle;

   586     d->text = text;

   587     d->menutext = menuText;

   588     setAccel(accel);

   589     init();

   590 }

   591 #endif

   592 

   593 /*!

   594   \internal

   595 */

   596 void Q3Action::init()

   597 {

   598     if (qobject_cast<Q3ActionGroup*>(parent()))

   599         ((Q3ActionGroup*) parent())->add(this);                // insert into action group

   600 }

   601 

   602 /*!

   603     Destroys the object and frees allocated resources.

   604 */

   605 

   606 Q3Action::~Q3Action()

   607 {

   608     delete d;

   609 }

   610 

   611 /*!

   612     \property Q3Action::iconSet

   613     \brief  the action's icon

   614 

   615     The icon is used as the tool button icon and in the menu to the

   616     left of the menu text. There is no default icon.

   617 

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

   619     the icon of the action is cleared.

   620 

   621     (See the action/toggleaction/toggleaction.cpp example.)

   622 

   623 */

   624 void Q3Action::setIconSet(const QIcon& icon)

   625 {

   626     register QIcon *i = d->icon;

   627     if (!icon.isNull())

   628         d->icon = new QIcon(icon);

   629     else

   630         d->icon = 0;

   631     delete i;

   632     d->update(Q3ActionPrivate::Icons);

   633 }

   634 

   635 QIcon Q3Action::iconSet() const

   636 {

   637     if (d->icon)

   638         return *d->icon;

   639     return QIcon();

   640 }

   641 

   642 /*!

   643     \property Q3Action::text

   644     \brief the action's descriptive text

   645 

   646     \sa setMenuText() setToolTip() setStatusTip()

   647 */

   648 void Q3Action::setText(const QString& text)

   649 {

   650     d->text = text;

   651     d->update();

   652 }

   653 

   654 QString Q3Action::text() const

   655 {

   656     return d->text;

   657 }

   658 

   659 

   660 /*!

   661     \property Q3Action::menuText

   662     \brief the action's menu text

   663 

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

   665     the icon (if there is one), the menu text and the accelerator (if

   666     there is one). If the menu text is not explicitly set in the

   667     constructor or by using setMenuText() the action's description

   668     text will be used as the menu text. There is no default menu text.

   669 

   670     \sa text

   671 */

   672 void Q3Action::setMenuText(const QString& text)

   673 {

   674     if (d->menutext == text)

   675         return;

   676 

   677     d->menutext = text;

   678     d->update();

   679 }

   680 

   681 QString Q3Action::menuText() const

   682 {

   683     return d->menuText();

   684 }

   685 

   686 /*!

   687     \property Q3Action::toolTip

   688     \brief the action's tool tip

   689 

   690     This text is used for the tool tip. If no status tip has been set

   691     the tool tip will be used for the status tip.

   692 

   693     If no tool tip is specified the action's text is used, and if that

   694     hasn't been specified the description text is used as the tool tip

   695     text.

   696 

   697     There is no default tool tip text.

   698 

   699     \sa setStatusTip() setAccel()

   700 */

   701 void Q3Action::setToolTip(const QString& tip)

   702 {

   703     if (d->tooltip == tip)

   704         return;

   705 

   706     d->tooltip = tip;

   707     d->update();

   708 }

   709 

   710 QString Q3Action::toolTip() const

   711 {

   712     return d->toolTip();

   713 }

   714 

   715 /*!

   716     \property Q3Action::statusTip

   717     \brief the action's status tip

   718 

   719     The statusTip is displayed on all status bars that this action's

   720     top-level parent widget provides.

   721 

   722     If no status tip is defined, the action uses the tool tip text.

   723 

   724     There is no default statusTip text.

   725 

   726     \sa setToolTip()

   727 */

   728 void Q3Action::setStatusTip(const QString& tip)

   729 {

   730     // Old comment: ### Please reimp for Q3ActionGroup!

   731     // For consistency reasons even action groups should show

   732     // status tips (as they already do with tool tips)

   733     // Please change Q3ActionGroup class doc appropriately after

   734     // reimplementation.

   735 

   736     if (d->statustip == tip)

   737         return;

   738 

   739     d->statustip = tip;

   740     d->update();

   741 }

   742 

   743 QString Q3Action::statusTip() const

   744 {

   745     return d->statusTip();

   746 }

   747 

   748 /*!

   749     \property Q3Action::whatsThis

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

   751 

   752     The whats this text is used to provide a brief description of the

   753     action. The text may contain rich text (HTML-like tags -- see

   754     QStyleSheet for the list of supported tags). There is no default

   755     "What's This?" text.

   756 

   757     \sa QWhatsThis

   758 */

   759 void Q3Action::setWhatsThis(const QString& whatsThis)

   760 {

   761     if (d->whatsthis == whatsThis)

   762         return;

   763     d->whatsthis = whatsThis;

   764     d->update();

   765 }

   766 

   767 QString Q3Action::whatsThis() const

   768 {

   769     return d->whatsthis;

   770 }

   771 

   772 

   773 #ifndef QT_NO_ACCEL

   774 /*!

   775     \property Q3Action::accel

   776     \brief the action's accelerator key

   777 

   778     The keycodes can be found in \l Qt::Key and \l Qt::Modifier. There

   779     is no default accelerator key.

   780 */

   781 //#### Please reimp for Q3ActionGroup!

   782 //#### For consistency reasons even Q3ActionGroups should respond to

   783 //#### their accelerators and e.g. open the relevant submenu.

   784 //#### Please change appropriate Q3ActionGroup class doc after

   785 //#### reimplementation.

   786 void Q3Action::setAccel(const QKeySequence& key)

   787 {

   788     if (d->key == key)

   789         return;

   790 

   791     d->key = key;

   792     delete d->accel;

   793     d->accel = 0;

   794 

   795     if (!(int)key) {

   796         d->update();

   797         return;

   798     }

   799 

   800     QObject* p = parent();

   801     while (p && !p->isWidgetType()) {

   802         p = p->parent();

   803     }

   804     if (p) {

   805         d->accel = new Q3Accel((QWidget*)p, this, "qt_action_accel");

   806         d->accelid = d->accel->insertItem(d->key);

   807         d->accel->connectItem(d->accelid, this, SLOT(internalActivation()));

   808     } else

   809         qWarning("Q3Action::setAccel() (%s) requires widget in parent chain", objectName().toLocal8Bit().data());

   810     d->update();

   811 }

   812 

   813 

   814 QKeySequence Q3Action::accel() const

   815 {

   816     return d->key;

   817 }

   818 #endif

   819 

   820 

   821 /*!

   822     \property Q3Action::toggleAction

   823     \brief whether the action is a toggle action

   824 

   825     A toggle action is one which has an on/off state. For example a

   826     Bold toolbar button is either on or off. An action which is not a

   827     toggle action is a command action; a command action is simply

   828     executed, e.g. file save. This property's default is false.

   829 

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

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

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

   833     exclusive toggling, add the relevant toggle actions to a

   834     Q3ActionGroup with the \l Q3ActionGroup::exclusive property set to

   835     true.

   836 */

   837 void Q3Action::setToggleAction(bool enable)

   838 {

   839     if (enable == (bool)d->toggleaction)

   840         return;

   841 

   842     if (!enable)

   843         d->on = false;

   844 

   845     d->toggleaction = enable;

   846     d->update();

   847 }

   848 

   849 bool Q3Action::isToggleAction() const

   850 {

   851     return d->toggleaction;

   852 }

   853 

   854 /*!

   855     Activates the action and executes all connected slots.

   856     This only works for actions that are not toggle actions.

   857 

   858     \sa toggle()

   859 */

   860 void Q3Action::activate()

   861 {

   862     if (isToggleAction()) {

   863 #if defined(QT_CHECK_STATE)

   864         qWarning("Q3Action::%s() (%s) Toggle actions "

   865                   "can not be activated", "activate", objectName().toLocal8Bit().data());

   866 #endif

   867         return;

   868     }

   869     emit activated();

   870 }

   871 

   872 /*!

   873     Toggles the state of a toggle action.

   874 

   875     \sa on, activate(), toggled(), isToggleAction()

   876 */

   877 void Q3Action::toggle()

   878 {

   879     if (!isToggleAction()) {

   880         qWarning("Q3Action::%s() (%s) Only toggle actions "

   881                   "can be switched", "toggle", objectName().toLocal8Bit().data());

   882         return;

   883     }

   884     setOn(!isOn());

   885 }

   886 

   887 /*!

   888     \property Q3Action::on

   889     \brief whether a toggle action is on

   890 

   891     This property is always on (true) for command actions and

   892     \l{Q3ActionGroup}s; setOn() has no effect on them. For action's

   893     where isToggleAction() is true, this property's default value is

   894     off (false).

   895 

   896     \sa toggleAction

   897 */

   898 void Q3Action::setOn(bool enable)

   899 {

   900     if (!isToggleAction()) {

   901         if (enable)

   902             qWarning("Q3Action::%s() (%s) Only toggle actions "

   903                       "can be switched", "setOn", objectName().toLocal8Bit().data());

   904         return;

   905     }

   906     if (enable == (bool)d->on)

   907         return;

   908     d->on = enable;

   909     d->update(Q3ActionPrivate::State);

   910     emit toggled(enable);

   911 }

   912 

   913 bool Q3Action::isOn() const

   914 {

   915     return d->on;

   916 }

   917 

   918 /*!

   919     \property Q3Action::enabled

   920     \brief whether the action is enabled

   921 

   922     Disabled actions can't be chosen by the user. They don't disappear

   923     from the menu/tool bar but are displayed in a way which indicates

   924     that they are unavailable, e.g. they might be displayed grayed

   925     out.

   926 

   927     What's this? help on disabled actions is still available provided

   928     the \l Q3Action::whatsThis property is set.

   929 */

   930 void Q3Action::setEnabled(bool enable)

   931 {

   932     d->forceDisabled = !enable;

   933 

   934     if ((bool)d->enabled == enable)

   935         return;

   936 

   937     d->enabled = enable;

   938     d->update(Q3ActionPrivate::State);

   939 }

   940 

   941 bool Q3Action::isEnabled() const

   942 {

   943     return d->enabled;

   944 }

   945 

   946 /*!

   947     Disables the action if \a disable is true; otherwise

   948     enables the action.

   949 

   950     See the \l enabled documentation for more information.

   951 */

   952 void Q3Action::setDisabled(bool disable)

   953 {

   954     setEnabled(!disable);

   955 }

   956 

   957 /*!

   958     \property Q3Action::visible

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

   960 

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

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

   963     action cannot be seen or chosen by the user.

   964 

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

   966     appear at all.

   967 */

   968 void Q3Action::setVisible(bool visible)

   969 {

   970     d->forceInvisible = !visible;

   971 

   972     if ((bool)d->visible == visible)

   973         return;

   974 

   975     d->visible = visible;

   976     d->update(Q3ActionPrivate::Visibility);

   977 }

   978 

   979 /*

   980     Returns true if the action is visible (e.g. in menus and

   981     toolbars); otherwise returns false.

   982 */

   983 bool Q3Action::isVisible() const

   984 {

   985     return d->visible;

   986 }

   987 

   988 /*! \internal

   989 */

   990 void Q3Action::internalActivation()

   991 {

   992     if (isToggleAction())

   993         setOn(!isOn());

   994     emit activated();

   995 }

   996 

   997 /*! \internal

   998 */

   999 void Q3Action::toolButtonToggled(bool on)

  1000 {

  1001     if (!isToggleAction())

  1002         return;

  1003     setOn(on);

  1004 }

  1005 

  1006 /*!

  1007     Adds this action to widget \a w.

  1008 

  1009     Currently actions may be added to Q3ToolBar and Q3PopupMenu widgets.

  1010 

  1011     An action added to a tool bar is automatically displayed as a tool

  1012     button; an action added to a pop up menu appears as a menu option.

  1013 

  1014     addTo() returns true if the action was added successfully and

  1015     false otherwise. (If \a w is not a Q3ToolBar or Q3PopupMenu the

  1016     action will not be added and false will be returned.)

  1017 

  1018     \sa removeFrom()

  1019 */

  1020 bool Q3Action::addTo(QWidget* w)

  1021 {

  1022 #ifndef QT_NO_TOOLBAR

  1023     if (qobject_cast<Q3ToolBar*>(w)) {

  1024         if (objectName() == QLatin1String("qt_separator_action")) {

  1025             ((Q3ToolBar*)w)->addSeparator();

  1026         } else {

  1027             QString bname = objectName() + QLatin1String("_action_button");

  1028             QToolButton* btn = new QToolButton((Q3ToolBar*) w);

  1029             btn->setObjectName(bname);

  1030             addedTo(btn, w);

  1031             btn->setToggleButton(d->toggleaction);

  1032             d->toolbuttons.append(btn);

  1033             if (d->icon)

  1034                 btn->setIconSet(*d->icon);

  1035             d->update(Q3ActionPrivate::State | Q3ActionPrivate::Visibility | Q3ActionPrivate::EverythingElse) ;

  1036             connect(btn, SIGNAL(clicked()), this, SIGNAL(activated()));

  1037             connect(btn, SIGNAL(toggled(bool)), this, SLOT(toolButtonToggled(bool)));

  1038             connect(btn, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));

  1039         }

  1040     } else

  1041 #endif

  1042     if (qobject_cast<Q3PopupMenu*>(w)) {

  1043         Q3ActionPrivate::MenuItem* mi = new Q3ActionPrivate::MenuItem;

  1044         mi->popup = (Q3PopupMenu*) w;

  1045         QIcon* dicon = d->icon;

  1046         if (objectName() == QLatin1String("qt_separator_action"))

  1047             mi->id = ((Q3PopupMenu*)w)->insertSeparator();

  1048         else if (dicon)

  1049             mi->id = mi->popup->insertItem(*dicon, QString::fromLatin1(""));

  1050         else

  1051             mi->id = mi->popup->insertItem(QString::fromLatin1(""));

  1052         addedTo(mi->popup->indexOf(mi->id), mi->popup);

  1053         mi->popup->connectItem(mi->id, this, SLOT(internalActivation()));

  1054         d->menuitems.append(mi);

  1055         d->update(Q3ActionPrivate::State | Q3ActionPrivate::Visibility | Q3ActionPrivate::EverythingElse);

  1056         connect(mi->popup, SIGNAL(highlighted(int)), this, SLOT(menuStatusText(int)));

  1057         connect(mi->popup, SIGNAL(aboutToHide()), this, SLOT(clearStatusText()));

  1058         connect(mi->popup, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));

  1059     // Makes only sense when called by Q3ActionGroup::addTo

  1060     } else if (qobject_cast<QComboBox*>(w)) {

  1061         Q3ActionPrivate::ComboItem *ci = new Q3ActionPrivate::ComboItem;

  1062         ci->combo = (QComboBox*)w;

  1063         connect(ci->combo, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));

  1064         ci->id = ci->combo->count();

  1065         if (objectName() == QLatin1String("qt_separator_action")) {

  1066             if (d->icon)

  1067                 ci->combo->insertItem(d->icon->pixmap(), text());

  1068             else

  1069                 ci->combo->insertItem(text());

  1070         } else {

  1071             ci->id = -1;

  1072         }

  1073         d->comboitems.append(ci);

  1074         d->update(Q3ActionPrivate::State | Q3ActionPrivate::EverythingElse);

  1075     } else if(qobject_cast<QMenu*>(w)) {

  1076         Q3ActionPrivate::Action4Item *act = new Q3ActionPrivate::Action4Item;

  1077         if(!act->action) { //static

  1078             act->action = new QAction(this);

  1079             if (objectName() == QLatin1String("qt_separator_action"))

  1080                 act->action->setSeparator(true);

  1081         }

  1082         act->widget = w;

  1083         act->widget->addAction(act->action);

  1084         d->action4items.append(act);

  1085         d->update(Q3ActionPrivate::State | Q3ActionPrivate::EverythingElse);

  1086     } else {

  1087         qWarning("Q3Action::addTo(), unknown object");

  1088         return false;

  1089     }

  1090     return true;

  1091 }

  1092 

  1093 /*!

  1094     This function is called from the addTo() function when it has

  1095     created a widget (\a actionWidget) for the action in the \a

  1096     container.

  1097 */

  1098 

  1099 void Q3Action::addedTo(QWidget *actionWidget, QWidget *container)

  1100 {

  1101     Q_UNUSED(actionWidget);

  1102     Q_UNUSED(container);

  1103 }

  1104 

  1105 /*!

  1106     \overload

  1107 

  1108     This function is called from the addTo() function when it has

  1109     created a menu item at the index position \a index in the popup

  1110     menu \a menu.

  1111 */

  1112 

  1113 void Q3Action::addedTo(int index, Q3PopupMenu *menu)

  1114 {

  1115     Q_UNUSED(index);

  1116     Q_UNUSED(menu);

  1117 }

  1118 

  1119 /*!

  1120     Sets the status message to \a text

  1121 */

  1122 void Q3Action::showStatusText(const QString& text)

  1123 {

  1124 #ifndef QT_NO_STATUSBAR

  1125     // find out whether we are clearing the status bar by the popup that actually set the text

  1126     static Q3PopupMenu *lastmenu = 0;

  1127     QObject *s = (QObject*)sender();

  1128     if (s) {

  1129         Q3PopupMenu *menu = qobject_cast<Q3PopupMenu*>(s);

  1130         if (menu && text.size())

  1131             lastmenu = menu;

  1132         else if (menu && text.isEmpty()) {

  1133             if (lastmenu && menu != lastmenu)

  1134                 return;