In this chapter we investigate adding the command structure to the application framework we developed in Chapter 12. This consists of QAction objects that are added to toolbars and menu bars, and that can provide keyboard accelerators.
Creating QActions and populating your toolbars and menus with them is not an exciting task, but it is necessary for any GUI application. Let's take a deeper look at the possibilities of actions, toolbars and menus.
We first encountered the QAction class in Chapter 10. To recap briefly, QAction is a model of a well-defined action that a user can perpetrate against your application, or the data of your application models. This a very powerful concept. Previously, you would have to create menu items and connect them to slots, create toolbar items and connect them to slots, and create keyboard shortcuts and connect them to slots, too.
Keeping everything synchronized is difficult, and the whole process often leads to a horrible mess. Combine this with the possibility that you might want to disable some action—such as redo, when there's nothing to redo—and you're suddenly writing lots of duplicated code. And then, of course, you get to the point where your users want to modify the contents of the toolbar...
By bringing all the user-interface characteristics of actions together in the QAction class, most of the mess can be avoided. The QAction class tracks the following interface elements:
Pull-down menus text
For each of these properties, there is a set function; although you can also set some properties in the constructor of QAction. Here is an annotated example of a complete QAction definition:
Example 13-1. Defining a complex toggle action
planAction=QAction(self) planAction.setIconSet(QIconSet(QPixmap(plan))) planAction.setText("Plan") planAction.setMenuText("&Plan ...") planAction.setOn(0) planAction.setStatusTip("Enable the cunning plan") planAction.setToolTip("Enables the cunning plan") planAction.setWhatsThis( """Plan Selecting plan enables the cunning plan for this window.""") planAction.setAccel(QAccel.stringToKey("CTRL+C"),) planAction.setToggleAction(1)
One important parameter is the parent to the QAction. You can create groups of QActions — QActionGroups. A QActionGroup is a type of QAction that functions like a type of QGroupBox: it can group actions into mutually exclusive choices. The whole group of actions can be added to a menu.
The QAction class can emit two signals:
By connecting these signals to the correct slots (either directly in the document, or proxy slots defined in the application interface), you have encapsulated the entire behavior of your interface.
self.connect(planaction, SIGNAL("activated()"), self.slotExecuteCunningPlan)
or, for a toggle action:
self.connect(planaction, SIGNAL("toggled(bool)"), self.slotActivateCunningPlan)
All that remains, is to add the actions to pulldown menus or toolbars: