Widget Library

PreviousNext

Handling events

Overview

Event handling is one of the important tasks when programming a user interface. The interface has to react on user input in an intuitive and consistent manner.
This page describes the event mechanisms used in the Widget Library.

Events

There are two types of events:

Since external events are not triggered from a specific component, a designated focus will receive the event. How this focus is determined depends on the type of input device.

Internal events on the other hand are always triggered on the object where the event occured. These events are stored in a seperate event queue. Unless the event queue is set to be flushing internal events are not triggered right when they occur. This means that a call to set_dimension returns directly and does not notify registered agents on the resize events. However the event will be added to the event queue. The event queue is processed each frame between external events and drawing.

Hint: The special behavior of internal events can be deactivated by setting the event queue to be flushing, though normally you can leave the default behaviour.

Focus

For each input device a global focus exists. To access these the class EM_SHARED_FOCUS exists, which holds the singletons of the focus for all input devices. How the focus is set depends on the input device:

Listening to events

You can listen to an event by registering an agent on the event. This agent will then be called each time the event is triggered. To register an agent use subscribe. The type of parameters your agent needs is the generic tuple parameter of the event type object.

If you want to know which object an event triggered use closed arguments on your agent. If for example you have a feature to handle button clicks and you want to know which button was clicked you can do as follows:

button_1.clicked_event.subscribe (agent my_feature (button_1))
button_2.clicked_event.subscribe (agent my_feature (button_2))

Where my_feature takes a button as argument. Although the clicked event doesn't publish any arguments you know in my_feature which button triggered the event. With this method you can also give events integer or string ids by passing them as closed arguments to the agent.

Note: The compiler can not reliably check if your agent is allowed on an event! Because of the way tuples conform to each other it is possible to subscribe agents to an event which have more arguments than are passed by the event (An agent which takes an integer argument conforms to an agent which takes no arguments). These errors will result in runtime failure!