Understanding form event handlers

Form event handlers define a unit of work to be performed in response to an event. Event handlers are defined for specific forms. They are not shared across forms.

Note: This topic presents information about the WinStudio form event model, as opposed to the Application Event system. The primary difference between the two is that form events are operational only within a single form, whereas application events can be used application-wide.

Event handler sequence

Event handlers are identified by the name of the event that they are handling and by a sequence number. You can define multiple event handlers for any event. These event handlers execute in sequence number order. By default, if any event handler reports a failure, the remaining event handlers in the sequence are skipped. You can override this default by setting the Ignore Failure parameter. If you set this attribute, the event handler will always be treated as successful.

Built-in responses

When you define additional event handlers for standard events that have built-in responses, the built-in responses always execute last. Consequently, you can cancel the built-in responses by reporting failure from a custom event handler for the same event.

Event handler messages

For any event handler, you can define messages to be displayed when the event handler fails or succeeds. You use the Error Message and Success Message parameters to define each message. The message definition may contain a string name and may also reference any of the standard substitution keywords. For example, you can use the %B substitution keyword to reference a message type parameter that is defined for an event handler of the Method Call response type.

By default, messages generated from event handlers are presented in a pop-up dialog box. Alternatively, you can specify that they be presented in the application status bar. To do so, use the Message on Status Line parameter.

Restricting event handler execution to specific collections

By default, event handlers execute regardless of the currently active collection or the specific collection operation that generated the event. If you are using multiple collections on a form, you may write event handlers that are specific to each collection. To do so, use the event handler's Only When Current Collection Is parameter.

When you specify a specific collection for an event handler, form-based events will be handled by this event handler only when the specified collection is active. Collection-based events will be handled by this event handler only when the event is generated by an operation on the specified collection.