Event and Action Mapping

Event and Action Mapping

In a typical user interface, a user can request a specific action in many different ways. For example, in the example application, a user can close the application by

• selecting Close from the main application window’s system menu
• selecting Exit from the main application window’s File menu
• pressing Ctrl+F4 in the main application window
• pressing Alt+F4 (in any window)
• selecting the Exit button from the tool bar

Each of these choices creates a different user interface “event”. For example, the first two produce a “click” event on different menu items. The third and fourth events are “accelerator” events. The last is a click on a push button. The code that handles the main application window can be programmed to react to each of these events. The code is identical for each case, since each of these events is another way to tell the main application window to “exit the application”. That is, “exit the application” is the “action” that the user is requesting the main application window to take.

The Framework provides support for event to action mapping through a table (called EventAction) that maps user interface events to action names. A program, pGetAction, can be called to do a FORM INPUT and translate the user interface event into an action name. This enables window management programs to be written to handle actions rather than specific user interface events and greatly simplifies the code.

The example application code in Using the Framework – Examples (beginning with Simple Event Loop and Main Windows) illustrates the usefulness of mapping different interface events to a common action name. It is very common to provide users with different ways to invoke the same action. For example, it is not uncommon to enable an action to be invoked by selecting a specific menu item, by pressing an accelerator key, and by clicking on a push button. Application code can be greatly simplified if it only needs to respond to unique actions without being concerned about how those actions were invoked.

The Framework supports event/action mapping through

• an EntitySet called EventAction in which event to action mapping is defined
• pGetAction, a Framework program that uses EventAction to map a user interface event into an action. pGetAction is also integrated with the Message Queue facilities in the Process Manager
• standard mappings to facilitate common actions

Each of these is described briefly below. For more information, see the Reference Guide.

EventAction

EventAction is an EntitySet defined in $DeployServices. Each Zim database has its own copy of EventAction. The main fields of EventAction are WindowTag, ObjectTag, EventType, EventName, Action, Macro, Comment, and EventActionOwner.

PGetAction

pGetAction is called to get the next action. It is integrated with the Message Queue. If any actions are on the Message Queue, the next action on the queue is returned. If the Message Queue is empty, pGetAction does a FORM INPUT and reads EventAction to map the user interface event to an action.

Standard Event/Action Mapping

The standard contents of EventAction provide predefined event to action mappings.

• One group of entries provides standard mappings for certain accelerator keys. For example, Escape is mapped to the Discard action.
• Another group of mappings translate several common window events to actions whose names more closely indicate what happened (e.g. ENTERWINDOW versus GotFocus on a Window).
• Similarly, the FormField and MenuItem event mappings provide meaningful action names for these events.
• Another group of event mappings is for windows whose tag is ToolBar. These windows are intended for use a floating tool bars and are managed by the Framework program pToolBarManager. A tool bar windows and related forms is created for you in every database.
• The final group of event/action mappings provides callbacks for menu items that have special tags.

In effect, by attaching one of these tags to a menu item, the indicated callback is automatically called when you select that menu item. All of these mappings tend to enforce consistent usage in different applications.