Chapter 3. Events

Crossing into established events is strictly forbidden. Except for cheap tricks.

The Tenth Doctor (David Tennant)

1. Introduction

Once you have set up a scene on the stage, in order to respond to user interaction you will have to handle events coming from the underlying platform.

Events are relayed to actors by Clutter in form of signals; signals are a facility provided by the GObject framework to call functions depending on a unique name. A signal can be thought as a message that an object instance broadcasts to various listener functions.

There are various events that Clutter will handle: mostly, they deal with input devices, like a mouse pointer or a keyboard; but they can also come from the windowing system, like the delete-event signal that is emitted when the user closes the window of the stage.

Each event has a particular source, that is the actor that received the event. The event handling sequence is divided in two phases:

  1. the capture phase, which consists in an emission of the captured-event signal starting from the stage to, following the parent-child relationship, the source of the event;

  2. the bubble phase, which consists in an emission of the event signal starting from the source of the event to, following the parent-child relationship, the stage.

At any point during the event emission sequence a handler of either the captured-event or the event signals can stop it, by returning a boolean value of true, which means that the event has been handled. If an event hasn't been handled, a boolean value of false should be returned instead.


Clutter provides two useful macros to avoid remembering which boolean value should be used in an event signal handler: CLUTTER_EVENT_PROPAGATE, equivalent to FALSE; and CLUTTER_EVENT_STOP, equivalent to TRUE.