Embarcadero C++Builder: Managing an Application's Actions

	Managing an Application's Actions

Introduction to Action Lists

Overview

An action is the act of causing something to happen on an application. For example, a user can use a button to do something. A user can also use a menu item to display a dialog box. In previous lessons, to get the necessary actions of our applications, we created buttons and/or menu items.

To assist with this assignment and provide even more functionality, the VCL is equipped with special classes and objects intended to create actions. These objects and classes already provide all the basic functionality of regaulr actions, then they give some automatica effects you can get without writing a single line of code. Of course, you will still want to customize some of the default functionalities of these actions.

Practical Learning: Introducing Action Lists

Start Embarcadero RAD Studio
To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
Set the Caption of the form to Notice
Change the Name of the form to frmMain
Click the check box of the ShowHint field to set it to True
On the Tool Palette, click Win32
Double-click ImageList
On the form, double-click ImageList1
Click Add
Locate the resources that accompany our lessons. Click new.bmp
Click OK
In the same way, add the save.bmp bitmap

Creating an Action List

In previous lessons, we saw that an action can be created using a button. We also saw that actions can be grouped in a series of menu items, through a main or a popup menu. To help you create a list of actions, the VCL provides an object named an action list.

To visually create an action list, in the Standard section of the Tool Palette, click the ActionList button and click the form. An action list is based on the TActionList class. The TActionList class is based on the TCustomActionList, which is derived from TComponent:

TActionList Inheritance

Characteristics of an Action List

Introduction

An action is made to lay a foundation for menu, toolbars, and other objects that use action. To prepare such objects for an action, you should create an image listt that includes the bitmaps and/or icons that represent the types of actions you want to have in your menu(s) and toolbar(s). Once the image list is ready, you can assign it to the action list. To support this, the TCustomActionList class is equipped with a property named Images that is of type TCustomImageList.

Practical Learning: Creating an Action List

In the Tool Palette, click Standard
Click ActionList and click on the form
While ActionList1 is still selected, in the Object Inspector, click Images and select ImageList1

The Actions of an Action List

As its name suggests, an action list is made of action objects. After adding an action list to a form or other container, to visually create the actions, you use the Editing ActionList window. To display it:

Double-click the TActionList object on the form
Right-click the ActionList object and click Action List Editor...

This would open the Editing ActionList window:

Action List Editor

From the Editing ActionList window, to create an action:

Click the New Action button
Right-click anywhere in the Action List Editor and click New Action
Press Ins

After creating an action, to configure it, click it in the Editing ActionList window and use the options in the Object Inspector.

To support the actions, the TCustomActionList is equipped with a property named Actions, which is a collection and is of type TContainedAction:

__property Actnlist::TContainedAction * Actions = {read=GetAction,
                       				   write=SetAction};

The TContainedAction class is derived from the TBasicAction class, which itself is based on the TComponent class.

A Category for a Group of Actions

An action list can be made of a big single group of items. When it comes time to use them, you would have to find each action and use it as you see fit. For example, if you decide to use the actions in a main menu, you may have a hard time finding the right item for the right menu column. To address this issue, the action list allows you to create groups of items as you see fit. Normally, there is no fixed way to organize the items; only logic will guide you. Still, as you may know already, there are some understandings among most applications:

Actions that deal with files are grouped under a common list
Actions that deal with text in a document are grouped together
Actions related to the documents of an MDI are put in one group

The other items are grouped in a normal logic.

A group of actions in a list of actions is called a category. To support the categories, the TContainedAction class contains a property named Category:

To visually create a cateory, in the Editing window, first add an action. Select an existing action. In the Object Inspector, click Category and typee a name
To add an action to an existing category, in the Editing window, click that action. In the Object Inspector, click Category, then click the arrow of its combo box and select the desired category

When the categories have been created, their names display in the Categories list on the left side of the Editing ActionList window. From there, if you click a category, the items that are members of that group display in the Actions list.

Automatically Creating Actions

To assist you with creating a list of actions, C++Builder provides a collection of pre-configured actions. These items can appropriately respond to certain controls on your form without much code, provided the control is the type of action for which the action item was created. To get one of the pre-configured actions, display the Editing ActionList window. Then:

Click the arrow of the New Action button and click New Standard Action...
Right-click anywhere in the body of the Editing ActionList window and click New Standard Action...
Press Ctrl + Ins

Any of these actions would display the Standard Action Classs dialog box. The Standard Action Classes provides a long list of actions:

There are various ways you can select one or more items:

To select a group of actions, click its main node
To get an individual action, click it under its group
To select a range of items, click an item at one end of the desired range. Press and hold Shift. Click the item at the other end. Release Shift
To select individual actions, click one item. Press and hold Ctrl. Click the other items one at a time. When you have selected the desired items, release Ctrl

After making the selection(s), click OK.

Practical Learning: Configuring the Actions

On the form, double-click ActionList1 to open the Editing window
On the toolbar of the Editing window, click the New Action button
While the new Action1 item is still selected, in the Object Inspector, click Name and type FileNew
Click Caption and type &New
Click Category and type File
Click Hint and type New|Creates a new document
Click Shortcut, then click the arrow of its combo box and select Ctrl + N
In the ImageIndex combo box, select 0
Right-click the left frame of the Editing window and click New Action
While the new Action1 item is still selected, on the Object Inspector, click Caption and type &Save
In the Category combo box, select File
Click Name and type FileSave
Click Hint and type Save|Saves the current document
Set its ImageIndex to 1
Click Shortcut, then click the arrow of its combo box and select Ctrl + S
On the toolbar of the Action List Editor, click the arrow of the New Action button
Click New Standard Action…
In the Standard Action Classes dialog box, scroll down to the Internet node and double-click TSendMail
Right-click the right frame of the editor and click New Standard Action…
In the Standard Action Classes dialog box, scroll down to the File node and click TFileOpen
Press and hold Ctrl
Click TFileSaveAs
Click TFilePrintSetup
Click TFileExit
Release Ctrl
Click OK
On the left frame of the Action List Editor, click File to display its list of related actions
On the right frame, click FileSaveAs1 to select it. Using the Object Inspector, set its Shortcut to F12
While the File node is still selected in the left frame, in the right frame, click FileOpen1 to select it
On the toolbar of the Editing window, click the Move Up button
Click File again to see the result
Right-click one of the frames of the Editing window and click New Standard Action…
Click TEditCut
Press and hold Shift
Click TEditDelete
Release Shift
Click OK
Move the EditUndo1 item to be on top of the list
Move the EditDelete1 item and place it under EditPaste1
Close the Editing window
From the Standard section of the Tool Palette, click MainMenu and click the form
While the MainMenu1 icon is still selected, on the Object Inspector, set its Images property to ImageList1
On the form, double-click MainMenu1 to open the Menu Editor
Right-click the selected box on the Menu Editor and click Insert From Template…
On the Insert Template dialog box, double-click File Menu
Click the empty box on the right side of File to select it
Right-click the Menu Designer window and click Insert From Template
Double-click Edit Menu
Click Repeat <command> and press Delete
Click Paste Special and press Delete
Click Go To and press Delete
Click the separator under Replace and press Delete
Click Links and press Delete
Clcik Object and press Delete
In the Menu Designer, click File and click New to select it
In the Object Inspector, click the Action field and select FileNew from its combo box

In the same way, selecting the menu items and using the Action field from the Object Inspector, associate the menu items to their corresponding actions as follows:

Menu Item	Action
Open…	FileOpen1
Save	FileSave
Save As…	FileSaveAs1
Print Setup…	PrintSetup1
Exit	FileExit1
Undo	EditUndo1
Cut	EditCut1
Copy	EditCopy1
Paste	EditPaste1

IIn the Edit menu, click the separator under Paste and press Insert. Set its Action to EditDelete1
Close the Menu Designer
In the Tool Palette, click Win32
Click TToolBar and click an empty area on the form
Using the Object Inspector, set the Height value to 40
Change the Name of the toolbar to tbrStandard
Set the ShowCaptions property to True
Set its Image property to ImageList1
Right-click the toolbar and click New Button
In the Object Inspector, click Action, click its combo box and select FileNew
Complete the buttons as follows:
Press F9 to execute
Close the form and return to your programming environment
On the main menu, click File -> Close All
When asked whether you want to save, click No

Action Lists Messages and Events

As their name implies, the actions of a list are simply meant to perform common actions that other objects may need. To manage their behavior, the actions are usually implemented through a function pointer called TActionEvent. This function pointer is defined as follows:

typedef void __fastcall (__closure *TActionEvent)
			(Classes::TBasicAction* Action,
			 bool &Handled);

This means that an event created from this function will require two arguments. The first argument, Action, is in fact a pointer to the TBasicAction class. The TBasicAction class holds information about the action that needs to be carried. Information can be used to specify whether the action must be executed anew or only updated, whether there was a change to take into consideration or the change that occurred must be dismissed.

The Handled argument specifies how the action will be carried, whether it will execute or simply update the action.

When an action needs to be carried, the object that initiates the action fires an OnExecute() event, which is a TActionEvent type. If the action needs to be updated, the OnUpdate() event fires, which also is a TActionEvent type. When a change occurs in the action list, an OnChange() event is fired. This is a TNotifyEvent type.

An Action Manager

Introduction

An action manager is a central point from which you create and maintain the actions of an application. As reviewed for an action list, an action manager holds all the actions commonly used by a main menu, one or more toolbars, and other action-based controls such as buttons.

Practical Learning: Introducing Action Managers

To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
In the Object Inspector, change the following properties:
Caption: Picture Viewer
FormStyle: fsMDIForm
Name: frmMainFrame
Position: poScreenCenter
ShowHint: True
On the Tool Palette, click Win32
Double-click ImageList
On the form, double-click ImageList1
Click Add
Locate the resources that accompany our lessons
Click new.bmp
Press and hold Ctrl
Click save.bmp
Click print.bmp
Release Ctrl
Click OK

Creating an Action Manager

To give you a common area to manage actions, the VCL provides an action manager through a class named TActionManager. To visually create an action manager, in the Additional section of the Tool Palette, click the TActionManager button and click the form or a container. The TActionManager class is based on the TCustomActionManager class, which itself is derived from TCustomActionList, which is the same parent as the TActionList class.

Like an action list, an action manager can benefit from an image list. Therefore, before configuring an action manager, create and add an image list to your application. You don't even have to add images to it. After creating an image list, to assign it to an action manager, access the Object Inspector for the action manager and select the image list from its Images field.

Practical Learning: Creating an Action Manager

On the Tool Palette, click Additional
Click TActionManager button and click the form
In the Object Inspector, click Images, then click the arrow of its box and select ImageList1

Using an Action Manager

After adding an action manager to a form or container, you should (must) create its action. To do this visually:

Double-click the icon of the action manager
Right-click the action manager and click Customize...

Any of these action would open the Editon ActionManager dialog box:

Editing Action Manager

From the Editing ActionManager, to create an action:

Click the New Action button
Right-click anywhere in the Editing dialog box and click New Action
Press Ins

After creating an action, to configure it, click it in the Editing dialog box and use the options in the Object Inspector.

The actions of an action manager are primarily the same as those of an action list. This means that each action is an object of type TAction, which is represented in the Actions property of the TCustomActionList class, the collection class that holds the items of the list.

As mentioned for an action list, the VCL ships with an impressive collection of ready-made actions. To get them, in the Editing dialog box:

Click the arrow of the New Action button and click New Standard Action...
Right-click anywhere in the body of the Editing dialog box and click New Standard Action...
Press Ctrl + Ins

You configure the action using the exact same techniques of the action list.

Practical Learning: Creating an Action Manager

On the form, right-click TActionManager1 and click Customize...
On the toolbar of the Editing ActionManager dialog box, click the New Action button
While the new Action1 item is still selected, in the Object Inspector, change the following properties:
Caption: &New
Category: File
ImageIndex: 0
Name: FileNew
Shortcut: Ctrl + N
Right-click the left frame of the Editing ActionManager dialog box and click New Action
In the Object Inspector, make the following changes:
Caption: &Save
CCategory: File
ImageIndex: 1
Name: FileSave
Shortcut: Ctrl + S
Right-click the left frame of the Editing ActionManager dialog box and click New Action
In the Object Inspector, make the following changes:
Caption: &Print...
CCategory: File
ImageIndex: 2
Name: FilePrint
Shortcut: Ctrl + P
On the toolbar of the Editing Actionmanager dialog box, click the arrow of the New Action button
Click New Standard Action…
In the Standard Action Classes dialog box, click TEditCut
Press and hold Ctrl
Click TEditCopy, TEditPaste, TEditSelectAll, TEditUndo, TEditDelete, TWindowClose, TWindowCascade, TWindowTileHorizontal, TWindowTileVertical, TWindowMinizeAll, TWindowArrange, TFileOpen, TFileSaveAs, TFilePrintSetup, TFilePageSetup, TFileExit, and TCustomizeActionBars
Release Ctrl
Click OK
In the Categories list of the Editing ActionManager, click File
Using the Move Up and the Move Down buttons, arrange the order of items to New, Open, Save, Save As..., Print..., Print Setup, Page Setup, and Exit
Click OK (you can leave the Editing ActionManager dialog box on the screen)

The Action Main Menu

Description

When creating an SDI or an MDI application, if you want to mange its menu(s) and/or toolbar(s), you should use an action because we saw that it provides a convenient central point. To make this possible, the VCL provides an object named an action menu bar. It is an object to which you primarily add the desired menu items using the objects available from an action manager, which is extremely create to create. The advantage is convenience of maintenance.

Creating and Using an Action Main Menu

The action main menu is available through a class named TActionMainMenuBar. To get it, in the Additional section of the Tool Palette, click the TActionMainMenuBar button and click the form. You must then assign it to an action manager. This is visually done in the Object Inspector where you would select the TActionManager object in the ActionManager property of the TActionMainMenuBar object.

After associating the action manager to the action main menu, to manage it, you use the Editing dialog box. To visually do this, on the form or container, double-click the TActionManager object. To create a top menu item, in the Categories list of the Editing ActionManager dialog box, drag the desired category and drop it in the main menu area on the form. To configure a menu item, click it on the main menu to select it. Then use the Object Inspector and change the desired options.

The Editing ActionManager dialog box allows you to change the order (or sequence) of items in the Actions list. If you drag a category from the Categories list and drop it on the main menu of your form, the order of items would be kept. If you change the order of items in the Editing ActionManager dialog box, the main menu on your form would not be automatically changed. In the same way, if you add a new item to a group in the Editing ActionManager dialog box, the main menu on your form will not be updated. To solve this problem, you have two options. If you have not written any code for the menu items, you can simply delete the whole menu category on the main menu of the form. The other potion, which is better, is to drag the new item from the Editing ActionManager dialog box and drop it in the appropriate category on the main menu of your form.

The Editing ActionManager dialog box does not allow you to create separators. To create a separator, in the bottom section of the Editing ActionManager, drag the Drag To Create Separator button and drop it in the desired section on the main menu on your form.

Practical Learning: Creating an Action Main Menu

In the Additional section of the Tool Palette, click the TActionMainMenuBar button and click the form
In the Object Inspector, click ActionManager, then click the arrow of its field and select ActionManager1
(If you had closed the action manager, re-open it)
In the Categories list of the action manager, drag File to the main menu on the form:
Release the mouse
In the Categories list of the action manager, drag Edit to the main menu on the form on the right side of File
In the Categories list of the action manager, drag Tools to the main menu on the form on the right side of Edit
In the Categories list of the action manager, drag Windows to the main menu on the form on the right side of Tools

The Action Toolbar

Description

An action is primarily a normal toolbar. The "action" addition indicates that the object can be managed through an action list, allowing you to perform programmatic operations from a central object. Probably the main advantage is that, as seen with the user of an action list, an action toolbar can use the same objects as an action main menu; that is, the actions are stored in an action manager that takes over the whole concern about the common functionalities of objects.

Creating and Using an Action Toolbar

To support action toolbars, the VCL provides the TActionToolBar class. To visually create it, in the Additional section of the Tool Palette, click the TActionToolBar button and click the form. You use an action toolbar through an action manager. Therefore, after creating an action toolbar, to visually specify its action manager, in the Object Inspector, click the ActionManager field and select the action manager object.

To configure an action toolbar, you use the action manager. After assigning an action manager to an action toolbar, on the form, right-click the action manager and click Customize. To add action to the toolbar, drag that action from the Actions list of the Editing ActionManager dialog box and drop it on the toolbar in the form.

As mentioned for the action main menu, if you want to add a separator to a toolbar, drag the Drag To Create Separator button and drop it in the desired spot on the toolbar on your form.

Practical Learning: Creating an Action Toolbar

In the Additional section of the Tool Palette, click the TActionToolBar button and click the form
In the Object Inspector, click ActionManager, then click the arrow of its field and select ActionManager1
In the Categories list of the action manager, click File
In the Actions list, drag New to the toolbar on the form:
Release the mouse
While the new button is still selected on the toolbar, in the Object Inspector, click the check box of ShowCaption to set it to False
From the Actions section of the Editing ActionManager, drag Open and drop it to the right of New
In the Object Inspector, set its ShowCaption property to False
From the Actions list of the Editing dialog box, drag Save and drop it to the right of Open
In the bottom section of the Editing ActionManager dialog box, drag the Drag To Create Separators button and drop it on the toolbar of the form on the right side of Save
In the Categories list of the action manager, click Edit
In the Actions list, drag Cut and drop it on the toolbar of the form to the right side of the separactor
Click the Cut button on the toolbar of the form to select it
In the Object Inspector, set its ShowCaption property to False

Introduction to the Customize Dialog Box

Description

Most modern SDI and MDI applications that include menus and dialog box give you options to customize the menu items and the buttons on toolbars. Here is an example: the Customize dialog box from Embarcadero RAD Studio:

Customize Dialog Box

A Customize dialog box allows you to add items and/or buttons, move items and/or button, or remove (or hide the objects. A Customize dialog box is usually made of three property pages that contain the actions and options that can be configured.

The functionality of a Customize dialog box is usually too complex and tiresome to implement: not in the VCL.

Creating a Customize Dialog Box

To help you create a Customize dialog box, the VCL includes a class and control named TCustomizeDlg. During design, to get it, in the Additional section of the Tool Palette, click the TCustomizeDlg button and click the form or a container.

Practical Learning: Adding a Customize Dialog Box

In the Additional section of the Tool Palette, click the TCustomizeDlg button and click the form
In the Object Inspector, click ActionManager, then click the arrow of its field and select ActionManager1
To see the result, press F9
On the main menu, click Tools -> Customize...
Close the dialog box
Close the form and return to your programming environment

Characteristics of a Customize Dialog Box

Showing the Dialog Box

When you have equipped your application with a Customize dialog box, you should create a menu item or a button from which the user can display it. To let you display the Customize dialog box, the TCustomizeDlg class is equipped with a method named Show. Its syntax is:

void __fastcall Show(void);

As you can see, this method takes no argument and doesn't do anything significant other that displaying the dialog box. Also notice that, based on its name, the dialog box would be displayed as modeless object. When you call the Show() method, the dialog box fires an OnShow event. This event is of type TNotifyEvent.

The Action Manager

To make it easy to implement its functionality, a TCustomizeDlg object needs an action manager. Therefore, before configuring it, first create an action manager. The action manager doesn't have to be complete. That is, you can start it and change it little by little.

After creating an action manager, to let you assign it to a Customize dialog box, the TCustomizeDlg class is equipped with a property named ActionManager, which is of type TCustomActionManager, the parent of the TActionManager class:

__property Actnman::TCustomActionManager * ActionManager = {read=FActionManager,
							  write=SetActionManager};

To visually specify the action manager of the Customize dialog box, access its Object Inspector and select the object from the ActionManager field.

Staying On Top

A Customize dialog box must be a modeless dialog box in order to accomplish its role. That is, the parent application of a Customize dialog box must be "physically" accessible while the dialog box is displaying. To make this possible, the TCustomizeDlg class is equipped with a Boolean property named StayOnTop:

__property bool StayOnTop = {read=FStayOnTop,write=SetStayOnTop};

Closing the Dialog Box

After using the dialog box, the user can close it by clicking its system Close button. When this happens, the dialog box fires an OnClose event, which is of type TNotifyEvent. If necessay, you can use this event to take any action when the user decides to close the object.