The base Clutter::Actor
has several signals that are emitted when the
user interacts with the actor:
signal_button_press_event()
: Emitted when the user presses the mouse over the actor.
signal_button_release_event()
: Emitted when the user releases the mouse over the actor.
signal_motion_event()
: Emitted when the user moves the mouse over the actor.
signal_enter_event()
: Emitted when the user moves the mouse in to the actor's area.
signal_leave_event()
: Emitted when the user moves the mouse out of the actor's area.
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()
.
The following example demonstrates handing of clicks on an actor: