Events

The base Clutter::Actor has several signals that are emitted when the user interacts with the actor:

For instance, you can detect button clicks on an actor like so:

rect->signal_button_press_event().connect(&on_rect_button_press);

Alternatively, you might just handle signals from the parent Clutter::Stage and use Clutter::Stage::get_actor_at_pos() to discover which actor should be affected.

However, as a performance optimization, Clutter does not emit all event signals by default. For instance, to receive event signals for an actor instead of just the stage, you must call Clutter::Actor::set_reactive(). If you don't need the motion event signals (signal_motion_event(), signal_enter_event() and signal_leave_event()), you may call the global Clutter::set_motion_events_enabled() function with false to further optimize performance.

Your event signal handler should return true when it has fully handled the event, or false if you want the event to be sent also to the next actor in the event chain. Cluttermm first allows the stage to handle each event via the signal_captured_event() signal. But if the stage does not handle the event then it will be passed down to the child actor, first passing through the actor's parent containers, giving each actor in the hierarchy a chance to handle the event via a signal_captured_event() signal handler. If the event has still not been handled fully by any actor then the event will then be emitted via a specific signal (such as signal_button_press_event() or signal_key_press_event(). These specific signals are emitted first from the child actor, then by its parent, passing all they way back up to the stage if no signal handler returns true to indicate that it has handled the event fully.

Actors usually only receive keyboard events when the actor has key focus, but you can give an actor exclusive access to any events by grabbing either the pointer or the keyboard, using Clutter::grab_pointer() or Clutter::grab_keyboard().

Example

The following example demonstrates handing of clicks on an actor:

Figure 5.4. Actor Events

Actor Events

Source code