The on event instruction is used to register an event listener to an event source, so that events generated in the event source can be handled by a specified event handler.
For more information about Obix's event mechanism, please refer to the section called “Event”.
Table 8.21. on event syntax
| Production | Syntax | Links |
|---|---|---|
on_event_instruction | "on" "event" event_id_list ( "in" event_source ) ? "execute" event_handler ( "handler" ":" variable_id ) ? | the section called “on event instruction” |
event_id_list | ||
event_source |
| |
event_handler |
|
event_id_list specifies the list of events the listener wants to listen to. It is possible to specify more than one event handled by the same event handler. For example, one event handler could listen to events mouse_left_click and mouse_right_click in a GUI component. The list can be defined through:
mouse_left_click)mouse_left_click; mouse_right_click)* to listen to all eventsevent_source specifies the source of the event, which can be an object or service. If omitted, the event source defaults to the object or service that contains the on event instruction.
event_handler can be any object command or script with
handle_mouse_click_events listens to mouse_left_click_event and mouse_right_click_event events, the input argument of handle_mouse_click_events could be of type mouse_click_event which is the parent of types mouse_left_click_event and mouse_right_click_event.variable_id specifies an optional variable that holds a reference to the event listener. It can later be used in a stop event handler instruction to stop listening to events.
Example 8.24. Simple on event example
Suppose we want to create a tea_machine object by using the types and factories defined in Example 8.23, “Simple generate event example”, and then listen to event tea_ready. This can be done as follows:
service instruction_examples
command on_event_example
script
// create tea machine
const tea_machine tea_machine = fa_tea_machine.co_create
// listen to events 'tea_ready' in 'tea_machine' and use command 'tea_is_ready' as event handler
// each time a 'tea_ready' event is generated, command 'tea_is_ready' will be executed
on event tea_ready in c_tea_machine execute script co_tea_is_ready
// now make tea (will generate event 'tea_ready' and execute command 'tea_is_ready')
c_tea_machine.co_make_tea
end script
end command
command tea_is_ready
in event type:tea_ready_event end
script
se_console.co_message ( "Tea is ready." )
end script
end command
end serviceFor a more complete example, see also: Example 6.10, “Events in a television delivery stack”