How Do Actions Work?

For the code to work, we must first insert an addtional menu with the title Settings in the Designer, which we will call settingsMenu. The Settings menu here belongs in front of the Help menu, since the latter should always be the last entry in the menu bar.

This results in a selectable entry being located in the tool bars submenu. All visible bars are prefixed with a checkmark. You can see here why toolbars should always be given a name.

4.6 How Do Actions Work?

We have already made contact with the QAction class. So far however, the Designer generated the appropriate code. So to get a better picture, we should not forget to mention how actions work and how you can use them “manually.” Those not interested in these details can continue reading on page 130.

Each QAction object encapsulates information involving a user interface action.¹¹ All important properties are summarized in Table 4.2 on page 129.

11 In Qt 3, actions (also called QActions) were active objects that selected the matching display method themselves, dependent on the object in which they were included. In Qt 4 Trolltech has reversed this principle: Now widgets decide on the display form of the actions presented.

4.6.1 How to Instantiate QAction Manually

We do not have to use the Designer every time, of course, to create QAction objects.

The following example demonstrates how you can create actions yourself in the constructor of a QMainWindow subclass.

First we instantiate the desired action with an icon and name, and assign it to the main window as a parent object. The QIcon() class encapsulates an icon:

QAction *action_open;

action_open = new QAction(QIcon(":/pics/fileopen.png"), tr("&Open"), this);

action_open->setShortcut(tr("Ctrl+O"));

action_open->setStatusTip(tr("Opens an existing file."));

In contrast to QPixmap, an action can take in images for various states (normal, active, and grayed out) and stages (selected or not selected). If the class contains just one image—as in this case—it tries to calculate the icons for the other states and stages from the icon specified.

By means of setShortcut() we can set the corresponding key binding as a string.

Together with the translation function tr(), this has the advantage that the trans-lators can select an appropriate shortcut for the Open action in the respective language. setStatusTip() sets the text that appears in the status bar if the mouse is held over the action.

To integrate actions directly into the menu bar, the following code suffices:

menuBar()->addAction(action_open);

menuBar(), a method of QMainWindow returns the main windows menu bar. The procedure just shown is rather unusual, however. Normally menus are first inserted into the menu bar, and then the actions are integrated. The QMenu instance repre-senting the menu can be generated via the addMenu()Factory Method. We insert the Open action into this as follows:

QMenu *menu_Datei = menuBar()->addMenu(tr("&File"));

menu_Datei->addAction(action_open);

For actions that are used as information carriers for various widgets simultaneously, you should particularly think about the parenthood in the object model of Qt. The main window, as the father of all other widgets, is always the last to be deleted.

So that Qt will delete action objects as late as possible, it is best to turn them into direct descendants of the main window.

If actions are used in several windows simultaneously, there are basically two al-ternatives: Either you duplicate all actions for each window, or you turn them into children of QApplication. In this case you can simply pass qApp as a parent to the QAction constructor.

4.6.2 Selectable Actions

Some actions contain a binary state. A typical example of this is a word-wrap function in CuteEdit. So that the user can see whether this is active or not, we convert it to a selectable action with setCheckable():

QAction *action_linebreak;

action_linebreak = new QAction(tr("&Line break"), this);

action_linebreak->setCheckable(true);

Its status can be queried with isChecked(). Although a selectable action automati-cally changes its state every time it is selected, you can alternatively change it with setChecked() instead.

4.6.3 Grouped Actions

Several selectable actions can be grouped together so that the user can always ac-tivate only one of them. This function is particularly familiar from word processing programs, in which you can exclusively select from text alignment to the left, to the right, or centered. If you select one of these actions, the others are automatically deactivated.

To implement this in Qt, all states must be available as QAction instances. But first we create a QActionGroup object, which we pass to the QAction constructor as a parent widget. This causes the action to be automatically inserted into the action group. If we now make each individual element in the group selectable, the actions are linked to each other:

QAction *act_alignleft;

QAction *act_alignright;

QAction *act_aligncenter;

QActionGroup *aligngroup = new QActionGroup(this);

act_alignleft = new QAction(tr("Align &right"), aligngroup);

act_alignright = new QAction(tr("Align &left"), aligngroup);

act_aligncenter = new QAction(tr("&Center"), aligngroup);

act_alignleft->setCheckable(true);

act_alignright->setCheckable(true);

act_aligncenter->setCheckable(true);

Since QActionGroup is just an administration class, we must insert the individual actions manually, with addAction(), into the appropriate menu or toolbar. If the user now selects an action, the class emits the triggered() signal with the selected action as an argument. With this, a matching slot can decide how to react to the corresponding action, such as by comparing the pointer to the passed on QAction instance with the actions produced.

Table 4.2:

Important properties ofQAction

Property Get method Set method Description

text text() setText(const

QString&) Short description of ac-tion, used as a menu text, for example

icon icon() setIcon(const

QIcon&) Icon that symbolizes the action

iconText iconText() setIconText(const

QString&) Text that fits in the icon or underneath the icon;

if not set, text() is used shortcut shortcut() setShortcut(const

QKeySequence&) Shortcut statusTip statusTip() setStatusTip(const

QString&) Longer text that the sta-tus bar shows when the mouse passes over it whatsThis whatsThis() setWhatsThis(const

QString&) Extensive help text that is displayed in the What’s This? mode¹²

QFont&) Specifies the font prop-erties for menu entries enabled isEnabled() setEnabled(bool) If this is false, the action

is grayed and cannot be selected

visible isVisible() setVisible(bool) If this is false, the action is not displayed

checkable isCheckable() setCheckable(bool) If this is true, the action can be switched on and off (toggled) (for ex-ample, bold typeface in a word processing pro-gram)

12 In theWhat’s This?mode the application displays an information text for each selected entry, which can be defined for each widget and for each QAction with setWhatsThis(). Users can navigate to the What’s This? mode via✞

✝ ☎

✆

Shift +✞

✝ ☎

✆

F1 or via a QAction, which generates the call QWhatsThis().createAction(). It must be inserted explicitly into the Help menu.

continued

Property Get method Set method Description

checked isChecked() setChecked(bool) Defines whether a tog-gled action is on (true) or off