How to use action lists?
Action lists maintain a list of actions that your application can take in response to something a user does. By using action objects, you centralize the functions performed by your application from the user interface. This lets you share common code for performing actions (for example, when a toolbar button and menu item do the same thing), as well as providing a single, centralized way to enable and disable actions depending on the state of your application.
Note: The contents of this section apply to setting up toolbars and menus for cross-platform development. For Windows development you can also use the methods described here. However, using action bands instead is simpler and offers more options. The action lists will be handled automatically by the Action Manager. See Organizing actions for toolbars and menus for details.
How to set up action lists?
Setting up action lists is fairly easy once you understand the basic steps involved:
- Create the action list.
- Add actions to the action list.
- Set properties on the actions.
- Attach clients to the action.
Here are the steps in more detail:
- Drop a TActionList object onto your form or data module. (ActionList is on the Standard page of the Component palette.)
- Double-click the TActionList object to display the Action List editor.
Use one of the predefined actions listed in the editor: right-click and choose New Standard Action.
The predefined actions are organized into categories (such as Dataset, Edit, Help, and Window) in the Standard Action Classes dialog box. Select all the standard actions you want to add to the action list and click OK.
Create a new action of your own: right-click and choose New Action.
- Set the properties of each action in the Object Inspector. (The properties you set affect every client of the action.)
The Name property identifies the action, and the other properties and events (Caption, Checked, Enabled, HelpContext, Hint, ImageIndex, ShortCut, Visible, and Execute) correspond to the properties and events of its client controls. The client’s corresponding properties are typically, but not necessarily, the same name as the corresponding client property. For example, an action’s Enabled property corresponds to a TToolButton’s Enabled property. However, an action’s Checked property corresponds to a TToolButton’s Down property.
- If you use the predefined actions, the action includes a standard response that occurs automatically. If creating your own action, you need to write an event handler that defines how the action responds when fired. See What happens when an action fires for details.
- Attach the actions in the action list to the clients that require them:
- Click on the control (such as the button or menu item) on the form or data module. In the Object Inspector, the Action property lists the available actions.
- Select the one you want.
The standard actions, such as TEditDelete or TDataSetPost, all perform the action you would expect. You can look at the online reference Help for details on how all of the standard actions work if you need to. If writing your own actions, you’ll need to understand more about what happens when the action is fired. See What happens when an action fires for details.
How to hide unused items and categories in action bands?
One benefit of using ActionBands is that unused items and categories can be hidden from the user. Over time, the action bands become customized for the application users, showing only the items that they use and hiding the rest from view. Hidden items can become visible again when the user presses a drop-down button. Also, the user can restore the visibility of all action band items by resetting the usage statistics from the customization dialog. Item hiding is the default behavior of action bands, but that behavior can be changed to prevent hiding of individual items, all the items in a particular collection (like the File menu), or all of the items in a given action band.
The action manager keeps track of the number of times an action has been called by the user, which is stored in the associated TActionClientItem’s UsageCount field. The action manager also records the number of times the application has been run, which we shall call the session number, as well as the session number of the last time an action was used. The value of UsageCount is used to look up the maximum number of sessions the item can go unused before it becomes hidden, which is then compared with the difference between the current session number and the session number of the last use of the item. If that difference is greater than the number determined in PrioritySchedule, the item is hidden. The default values of PrioritySchedule are shown in the table below:
|Number of sessions in which an action band item was used
||Number of sessions an item will remain unhidden after its last use
|25 or more
It is possible to disable item hiding at design time. To prevent a specific action (and all the collections containing it) from becoming hidden, find its TActionClientItem object and set its UsageCount to -1. To prevent hiding for an entire collection of items, such as the File menu or even the main menu bar, find the TActionClients object associated with the collection and set its HideUnused property to false.