Developers

Omnis Technical Note TNGI0013

Studio Event Management

For Omnis Studio 3.0+
By Geir Fjaerli

This tech note demonstrates the event model of Studio and is accompanied by an example library which you can download here. The library has a single window, with three entry fields and three OK buttons, and a list to show the events triggered.

The fields are:
HasFieldEvents : Has evBefore and evAfter handlers in the field $event
NoFieldEvents : Has no field $event method
PassEventToControl : Has evBefore and evAfter handlers in the field $event, and 'Pass to next handler'

The buttons are:
OKHasEvent : Has an evClick and and evOK handler in its $event
OKNoEvent : No field event handler
OKPassEvent : Has an evClick, and a 'Pass to next handler'

Then there are two window methods:
$control : Has evBefore, evAfter, evOK and evClick event handlers
$event : Has evBefore, evAfter, evOK and evClick event handlers

Open the window and try the following:
First, tab through the entry fields. You will get the following results: HasFieldEvents : evBefore and evAfter reported in the field event only. Since it has field event handlers for the events, they are not passed on to $control. NoFieldEvents : evBefore and evAfter reported in $control only, since it has no field event handlers, events are automatically passed to $control. PassEventToControl : evBefore and evAfter reported in both field event method and $control, since we explicitly do a 'Pass to next handler'

So the results tell us:
Field events are handled by the fields $event if any handler exists for that event, and if so is not passed on to $control. If the field has no event handler for the event, or if we explicitly do a 'Pass to next handler', the event will be handled by the $control of the window, if any. Field events do not get passed to the $event of the window.

Second, try clicking the OK buttons. You will get the following results: The OK buttons will trigger an evOK in addition to evBefore, evAfter and evClick, as follows:

OKHasEvent : The evClick is handled by the field $event, since it has an event handler for this event. It is not passed to $control. evBefore, evAfter is handled by $control, because there are no field event handlers for these events. evOK is not handled by the field event handler even if there is one, because it is not a field event, but a window event. evOK is therefore handled by the window $event.

OKNoEvent : The evClick is not handled by $control, since there is no local handler. evOK is still only handled by the window $event.

OKPassEvent : evClick is handled both locally and in $control. But evOK is still only handled by the window $event.

So this brings us to the following conclusion:
1. Studio events are split into field events and window events.
2. Field event handlers ($event) only handle field events like evBefore, evAfter, evClick etc., and never handle window events like evOK or evCancel.
3. The window $event only handles window events, like evClose, evOK, evCancel etc.
4. $control only handles field, never window events. Field events are only passeed to $control when:
a. There is no field $event,
b. The field $event has no event handler for that event, or
c. The field $event explicitely passes the event with a 'Pass to next handler' statement.

To see which events are field events and which are window events, look in the Catalog (F9) on the Events tab. You will find an entry for window events, and one for field events, in addition to entries for window controls that have specific events.