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:
- External events from input devices; mouse, keyboard and joystick events.
- Internal events from components; e.g. component resizing or button clicks.
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.


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:
-
Mouse focus (EM_MOUSE_FOCUS): The mouse
focus will be set automatically by the scene. The component which is currently under the mouse
pointer will receive focus. For this reasen only objects which are descendants of
EM_COMPONENT can receive the mouse focus.
Note: Although you can set the mouse focus by hand with set_current_focus this will be overridden by the scene at the next mouse movement.
-
Keyboard focus (EM_KEYBOARD_FOCUS): The keyboard
focus is set by the scene if the mouse is clicked on a component. The clicked component will
receive keyboard focus unless it is set to ignore keyboard focus. If a component is clicked which
does not want the focus, the
default_focus receives the focus.
Since the default focus is set manually it can be set to any object which inherits from
EM_KEYBOARD_SENSITIVE. This means that a non-component object
can be set to handle keyboard input.
Note: If you have a default focus for a scene, remember to clear it when the scene changes.Note: Widgets are ignoring keyboard focus by default! Use set_keyboard_sensitive to change this behaviour.
-
Joystick focus (EM_JOYSTICK_FOCUS): The joystick
focus has to be set manually and thus has to be removed manually.
You can specify multiple objects to receive joystick events.
Use add_focus and
remove_focus to add and remove these objects.
Since the focus is set manually it can be set to any object which inherits from
EM_JOYSTICK_SENSITIVE. This means that a non-component object
can be set to handle joystick input.
Note: Most times after switching the scene you have to clear
or change the focus.
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.