
Prev		Next

Connecting Events to Actions

Table of Contents

Event and Action Matching Rules

Events trigger actions. Actions perform the work of the application by making adjustments to the user interface or interacting with outside applications.

Every event has a name which is used as the matching trigger for actions. Events may also contain an optional data payload and a symbolic description of that payload in what is referred to as a format string. Events can be directed at a particular model element, contain position information to target a particular screen region (such as a press event) or be completely independent of the display state of the user interface.

Events fall into three broad categories:

Standard Input Events are generic input definitions and are pre-defined within Designer and as such are not user defined events. These events represent expected user interactions such mouse or touchscreen press, release and motion as well as keyboard input. There are other standard input events defined for managing UI state changes such as focus management, screen change notification and application state management.
These event definitions and their data payloads are defined in the header file iodefs.h and are also listed in the appendix Standard Event Definitions.
UI Events are events that are defined to be used just within the context of the user interface. UI events are considered user events as they are custom to your application and you define them for your specific application needs. In general these events are generated from within the application in order to trigger some additional follow up behavior within the Storyboard application. Examples of this include the events generated in response to timers or animations. User defined events that are sent within the application are also considered as UI events, for example an application might define its own PowerOn or PowerOff events that it sends when the user initiates a touchscreen interaction. In the Event Editor, these types of events are labeled Self Events.
External Events are also user events. These are events that you defined for the purpose of communicating information into and out of the user interface. These events will frequently represent the application programming interface between the user interface and the rest of the system. Due to the shared nature of these events, between the UI and the system, these events deserve a special level of diligence in their design as it requires a greater effort to change their meaning or data payloads once they are put to use. In the Event Editor, these types of events are either labeled Incoming or Outgoing Events.

The delivery of an event in a Storyboard application is what will trigger the execution of actions which, as we have mentioned, causes visual and behavioral changes in the application. Actions receive an association with an event when they are bound to a particular model element in the application hierarchy. For example the way in which a gre.press event triggers a Data Change action might look something like the following:

To add actions to your application model, right-click the application and select Add > Action menu to open the New Action dialog.

This dialog presents a three panel dialog containing the three pieces of information that you require to bind an action.

Trigger Event

This panel allows you select one or more events that you want to trigger actions. By default the list is populated with the standard events, but you can add your own user defined events as well at this point. Select the Add Event button to open the New Event dialog. In this dialog you can enter in the name of your new event and provide some optional descriptive information about the source and payload of this event. Once a new event is created it will be added to the list of available events shown the New Action dialog. All user defined events are stored in the project relative file events/custom.evt. This text file uses a simple formatting and can be edited directly if many user events need to be added all at one time.

Note

	Note
The name of an event is what is used to trigger actions, so event names should be carefully considered. All of the standard Storyboard event definitions are placed within a `gre.` prefixed namespace. As you develop your application and introduce your own custom events, you should take care to organize your events in a manner that allows them to be clearly identified and associated with specific functional domains within your overall product.

The name of an event is what is used to trigger actions, so event names should be carefully considered. All of the standard Storyboard event definitions are placed within a gre. prefixed namespace. As you develop your application and introduce your own custom events, you should take care to organize your events in a manner that allows them to be clearly identified and associated with specific functional domains within your overall product.

Action

The second panel in this dialog allows you to select one or more actions that you want to invoke when the triggering event is received. There are many different types of actions that you can draw from.

Action Parameters

This third panel's content will change based on the action selection and presents a user interface for adjusting the parameters of the selected action. If multiple actions are selected, then this panel will only show the parameters for the first action selection made, but all of the selected actions will be bound. The action arguments are presented for convenience in this dialog and can always be changed or reconfigured using the Properties View.

In order to complete the dialog at least one event and one action must be selected. The resulting actions are going to be bound to the selected model object, or if multiple objects were selected then bindings will be created for every one of the selections. You can verify that the action binding is being performed on the intended object by looking at the Action & Event Model Context information at the bottom of the New Action dialog.

After an action is bound to a model object, that action will show up in the Application View underneath the model object it has been bound to and will also be visible in the Action View when the model object is selected. The action's properties can be changed and re-configured by selecting the action in either of these contexts and then using the Properties View. For information about specific action parameters and properties, please refer to the Storyboard Action Definitions Appendix.

If you have mistakenly bound an action to the wrong model object or have it triggering on the wrong event, it is also possible to change this binding information from the Action View by double clicking on the field you want to change and making the required adjustment. Similarly you can also change the action that is being invoked when an event is matched by double clicking and selecting a new action from the drop down list. When the action is changed as many of the action parameters as possible will be transferred to the new action from the old action, but you should take care to double check your parameter settings when making this type of adjustment.