Events

## Events Events — User and window system events |

## Synopsis

    #define             CLUTTER_CURRENT_TIME
    #define             CLUTTER_PRIORITY_EVENTS
    enum                ClutterModifierType;
    enum                ClutterScrollDirection;
    enum                ClutterStageState;
    enum                ClutterEventType;
    union               ClutterEvent;
    enum                ClutterEventFlags;
                        ClutterButtonEvent;
                        ClutterKeyEvent;
                        ClutterMotionEvent;
                        ClutterScrollEvent;
                        ClutterStageStateEvent;
                        ClutterCrossingEvent;
                        ClutterInputDevice;
    ClutterEvent *      clutter_event_new                   (ClutterEventType type);
    ClutterEvent *      clutter_event_copy                  (ClutterEvent *event);
    void                clutter_event_free                  (ClutterEvent *event);
    ClutterEventType    clutter_event_type                  (ClutterEvent *event);

    void                clutter_event_get_coords            (ClutterEvent *event,
                                                             gfloat *x,
                                                             gfloat *y);
    ClutterModifierType  clutter_event_get_state            (ClutterEvent *event);
    guint32             clutter_event_get_time              (ClutterEvent *event);
    ClutterActor *      clutter_event_get_source            (ClutterEvent *event);
    ClutterStage *      clutter_event_get_stage             (ClutterEvent *event);
    ClutterEventFlags   clutter_event_get_flags             (ClutterEvent *event);

    ClutterEvent *      clutter_event_get                   (void);
    ClutterEvent *      clutter_event_peek                  (void);
    void                clutter_event_put                   (ClutterEvent *event);
    gboolean            clutter_events_pending              (void);

    guint32             clutter_event_get_button            (ClutterEvent *event);
    guint               clutter_event_get_click_count       (ClutterEvent *event);

    guint               clutter_event_get_key_symbol        (ClutterEvent *event);
    guint16             clutter_event_get_key_code          (ClutterEvent *event);
    guint32             clutter_event_get_key_unicode       (ClutterEvent *event);
    guint32             clutter_keysym_to_unicode           (guint keyval);

    ClutterActor *      clutter_event_get_related           (ClutterEvent *event);

    ClutterScrollDirection  clutter_event_get_scroll_direction
                                                            (ClutterEvent *event);

    enum                ClutterInputDeviceType;
    ClutterInputDevice * clutter_event_get_device           (ClutterEvent *event);
    gint                clutter_event_get_device_id         (ClutterEvent *event);
    ClutterInputDeviceType  clutter_event_get_device_type   (ClutterEvent *event);
    ClutterInputDevice * clutter_get_input_device_for_id    (gint id);
    gint                clutter_input_device_get_device_id  (ClutterInputDevice *device);
    ClutterInputDeviceType  clutter_input_device_get_device_type
                                                            (ClutterInputDevice *device);

    guint32             clutter_get_current_event_time      (void);

## Description

Windowing events handled by Clutter.

The events usually come from the windowing backend, but can also be synthesized by Clutter itself or by the application code.

## Details

### CLUTTER_CURRENT_TIME

    #define CLUTTER_CURRENT_TIME    0L

Default value for "now".

Since 0.4

### CLUTTER_PRIORITY_EVENTS

    #define CLUTTER_PRIORITY_EVENTS (G_PRIORITY_DEFAULT)

Priority for event handling.

Since 0.4

### enum ClutterModifierType

    typedef enum {
      CLUTTER_SHIFT_MASK    = 1 << 0,
      CLUTTER_LOCK_MASK     = 1 << 1,
      CLUTTER_CONTROL_MASK  = 1 << 2,
      CLUTTER_MOD1_MASK     = 1 << 3,
      CLUTTER_MOD2_MASK     = 1 << 4,
      CLUTTER_MOD3_MASK     = 1 << 5,
      CLUTTER_MOD4_MASK     = 1 << 6,
      CLUTTER_MOD5_MASK     = 1 << 7,
      CLUTTER_BUTTON1_MASK  = 1 << 8,
      CLUTTER_BUTTON2_MASK  = 1 << 9,
      CLUTTER_BUTTON3_MASK  = 1 << 10,
      CLUTTER_BUTTON4_MASK  = 1 << 11,
      CLUTTER_BUTTON5_MASK  = 1 << 12,

      /* bits 15 to 25 are currently unused; bit 29 is used internally */

      CLUTTER_SUPER_MASK    = 1 << 26,
      CLUTTER_HYPER_MASK    = 1 << 27,
      CLUTTER_META_MASK     = 1 << 28,

      CLUTTER_RELEASE_MASK  = 1 << 30,

      CLUTTER_MODIFIER_MASK = 0x5c001fff
    } ClutterModifierType;

Masks applied to a ClutterEvent by modifiers.

`CLUTTER_SHIFT_MASK` | Mask applied by the Shift key
`CLUTTER_LOCK_MASK` | Mask applied by the Caps Lock key
`CLUTTER_CONTROL_MASK` | Mask applied by the Control key
`CLUTTER_MOD1_MASK` | Mask applied by the first Mod key
`CLUTTER_MOD2_MASK` | Mask applied by the second Mod key
`CLUTTER_MOD3_MASK` | Mask applied by the third Mod key
`CLUTTER_MOD4_MASK` | Mask applied by the fourth Mod key
`CLUTTER_MOD5_MASK` | Mask applied by the fifth Mod key
`CLUTTER_BUTTON1_MASK` | Mask applied by the first pointer button
`CLUTTER_BUTTON2_MASK` | Mask applied by the second pointer button
`CLUTTER_BUTTON3_MASK` | Mask applied by the third pointer button
`CLUTTER_BUTTON4_MASK` | Mask applied by the fourth pointer button
`CLUTTER_BUTTON5_MASK` | Mask applied by the fifth pointer button
`CLUTTER_SUPER_MASK` | Mask applied by the Super key
`CLUTTER_HYPER_MASK` | Mask applied by the Hyper key
`CLUTTER_META_MASK` | Mask applied by the Meta key
`CLUTTER_RELEASE_MASK` | Mask applied during release
`CLUTTER_MODIFIER_MASK` | A mask covering all modifier types

Since 0.4

### enum ClutterScrollDirection

    typedef enum
    {
      CLUTTER_SCROLL_UP,
      CLUTTER_SCROLL_DOWN,
      CLUTTER_SCROLL_LEFT,
      CLUTTER_SCROLL_RIGHT
    } ClutterScrollDirection;

Direction of a pointer scroll event.

`CLUTTER_SCROLL_UP` | Scroll up
`CLUTTER_SCROLL_DOWN` | Scroll down
`CLUTTER_SCROLL_LEFT` | Scroll left
`CLUTTER_SCROLL_RIGHT` | Scroll right

Since 0.4

### enum ClutterStageState

    typedef enum
    {
      CLUTTER_STAGE_STATE_FULLSCREEN       = (1<<1),
      CLUTTER_STAGE_STATE_OFFSCREEN        = (1<<2),
      CLUTTER_STAGE_STATE_ACTIVATED        = (1<<3)
    } ClutterStageState;

Stage state masks

`CLUTTER_STAGE_STATE_FULLSCREEN` | Fullscreen mask
`CLUTTER_STAGE_STATE_OFFSCREEN` | Offscreen mask
`CLUTTER_STAGE_STATE_ACTIVATED` | Activated mask

Since 0.4

### enum ClutterEventType

    typedef enum
    {
      CLUTTER_NOTHING = 0,
      CLUTTER_KEY_PRESS,
      CLUTTER_KEY_RELEASE,
      CLUTTER_MOTION,
      CLUTTER_ENTER,
      CLUTTER_LEAVE,
      CLUTTER_BUTTON_PRESS,
      CLUTTER_BUTTON_RELEASE,
      CLUTTER_SCROLL,
      CLUTTER_STAGE_STATE,
      CLUTTER_DESTROY_NOTIFY,
      CLUTTER_CLIENT_MESSAGE,
      CLUTTER_DELETE
    } ClutterEventType;

Types of events.

`CLUTTER_NOTHING` | Empty event
`CLUTTER_KEY_PRESS` | Key press event
`CLUTTER_KEY_RELEASE` | Key release event
`CLUTTER_MOTION` | Pointer motion event
`CLUTTER_ENTER` | Actor enter event
`CLUTTER_LEAVE` | Actor leave event
`CLUTTER_BUTTON_PRESS` | Pointer button press event
`CLUTTER_BUTTON_RELEASE` | Pointer button release event
`CLUTTER_SCROLL` | Pointer scroll event
`CLUTTER_STAGE_STATE` | Stage stage change event
`CLUTTER_DESTROY_NOTIFY` | Destroy notification event
`CLUTTER_CLIENT_MESSAGE` | Client message event
`CLUTTER_DELETE` | Stage delete event

Since 0.4

### union ClutterEvent

    union ClutterEvent
    {
      ClutterEventType type;

      ClutterAnyEvent any;
      ClutterButtonEvent button;
      ClutterKeyEvent key;
      ClutterMotionEvent motion;
      ClutterScrollEvent scroll;
      ClutterStageStateEvent stage_state;
      ClutterCrossingEvent crossing;
    };

Generic event wrapper.

Since 0.2

### enum ClutterEventFlags

    typedef enum {
      CLUTTER_EVENT_NONE           = 0,
      CLUTTER_EVENT_FLAG_SYNTHETIC = 1 << 0,
    } ClutterEventFlags;

Flags for the ClutterEvent

`CLUTTER_EVENT_NONE` | No flag set
`CLUTTER_EVENT_FLAG_SYNTHETIC` | Synthetic event

Since 0.6

### ClutterButtonEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;

      gfloat x;
      gfloat y;
      ClutterModifierType modifier_state;
      guint32 button;
      guint click_count;
      gdouble *axes; /* Future use */
      ClutterInputDevice *device;
    } ClutterButtonEvent;

Button event.

The event coordinates are relative to the stage that received the event, and can be transformed into actor-relative coordinates by using `clutter_actor_transform_stage_point()`.

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
gfloat `x`; | event X coordinate, relative to the stage
gfloat `y`; | event Y coordinate, relative to the stage
ClutterModifierType `modifier_state`; | button modifiers
guint32 `button`; | event button
guint `click_count`; | number of button presses within the default time and radius
gdouble *`axes`; | reserved for future use
ClutterInputDevice *`device`; | reserved for future use

Since 0.2

### ClutterKeyEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;

      ClutterModifierType modifier_state;
      guint keyval;
      guint16 hardware_keycode;
      gunichar unicode_value;
      ClutterInputDevice *device;
    } ClutterKeyEvent;

Key event

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
ClutterModifierType `modifier_state`; | key modifiers
guint `keyval`; | raw key value
guint16 `hardware_keycode`; | raw hardware key value
gunichar `unicode_value`; | Unicode representation
ClutterInputDevice *`device`; | reserved for future use

Since 0.2

### ClutterMotionEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;

      gfloat x;
      gfloat y;
      ClutterModifierType modifier_state;
      gdouble *axes; /* Future use */
      ClutterInputDevice *device;
    } ClutterMotionEvent;

Event for the pointer motion

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
gfloat `x`; | event X coordinate
gfloat `y`; | event Y coordinate
ClutterModifierType `modifier_state`; | button modifiers
gdouble *`axes`; | reserved for future use
ClutterInputDevice *`device`; | reserved for future use

Since 0.2

### ClutterScrollEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;

      gfloat x;
      gfloat y;
      ClutterScrollDirection direction;
      ClutterModifierType modifier_state;
      gdouble *axes; /* future use */
      ClutterInputDevice *device;
    } ClutterScrollEvent;

Scroll wheel (or similar device) event

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
gfloat `x`; | event X coordinate
gfloat `y`; | event Y coordinate
ClutterScrollDirection `direction`; | direction of the scrolling
ClutterModifierType `modifier_state`; | button modifiers
gdouble *`axes`; | reserved for future use
ClutterInputDevice *`device`; | reserved for future use

Since 0.2

### ClutterStageStateEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source; /* XXX: should probably be the stage itself */

      ClutterStageState changed_mask;
      ClutterStageState new_state;
    } ClutterStageStateEvent;

Event signalling a change in the ClutterStage state.

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor (unused)
ClutterStageState `changed_mask`; | bitwise OR of the changed flags
ClutterStageState `new_state`; | bitwise OR of the current state flags

Since 0.2

### ClutterCrossingEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;

      gfloat x;
      gfloat y;
      ClutterInputDevice *device;
      ClutterActor *related;
    } ClutterCrossingEvent;

Event for the movement of the pointer across different actors

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
gfloat `x`; | event X coordinate
gfloat `y`; | event Y coordinate
ClutterInputDevice *`device`; | reserved for future use
ClutterActor *`related`; | actor related to the crossing

Since 0.2

### ClutterInputDevice

    typedef struct _ClutterInputDevice ClutterInputDevice;

Generic representation of an input device. The actual contents of this structure depend on the backend used.

### clutter_event_new ()

    ClutterEvent *      clutter_event_new                   (ClutterEventType type);

Creates a new ClutterEvent of the specified type.

`type` : | The type of event.
Returns : | A newly allocated ClutterEvent.

### clutter_event_copy ()

    ClutterEvent *      clutter_event_copy                  (ClutterEvent *event);

Copies `event`.

`event` : | A ClutterEvent.
Returns : | A newly allocated ClutterEvent

### clutter_event_free ()

    void                clutter_event_free                  (ClutterEvent *event);

Frees all resources used by `event`.

`event` : | A ClutterEvent.

### clutter_event_type ()

    ClutterEventType    clutter_event_type                  (ClutterEvent *event);

Retrieves the type of the event.

`event` : | a ClutterEvent
Returns : | a ClutterEventType

### clutter_event_get_coords ()

    void                clutter_event_get_coords            (ClutterEvent *event,
                                                             gfloat *x,
                                                             gfloat *y);

Retrieves the coordinates of `event` and puts them into `x` and `y`.

`event` : | a ClutterEvent
`x` : | return location for the X coordinate
`y` : | return location for the Y coordinate

Since 0.4

### clutter_event_get_state ()

    ClutterModifierType  clutter_event_get_state            (ClutterEvent *event);

Retrieves the modifier state of the event.

`event` : | a ClutterEvent
Returns : | the modifier state parameter, or 0

Since 0.4

### clutter_event_get_time ()

    guint32             clutter_event_get_time              (ClutterEvent *event);

Retrieves the time of the event.

`event` : | a ClutterEvent
Returns : | the time of the event, or `CLUTTER_CURRENT_TIME`

Since 0.4

### clutter_event_get_source ()

    ClutterActor *      clutter_event_get_source            (ClutterEvent *event);

Retrieves the source ClutterActor the event originated from, or NULL if the event has no source.

`event` : | a ClutterEvent
Returns : | a ClutterActor. transfer none.

Since 0.6

### clutter_event_get_stage ()

    ClutterStage *      clutter_event_get_stage             (ClutterEvent *event);

Retrieves the source ClutterStage the event originated for, or `NULL` if the event has no stage.

`event` : | a ClutterEvent
Returns : | a ClutterStage. transfer none.

Since 0.8

### clutter_event_get_flags ()

    ClutterEventFlags   clutter_event_get_flags             (ClutterEvent *event);

Retrieves the ClutterEventFlags of `event`

`event` : | a ClutterEvent
Returns : | the event flags

Since 1.0

### clutter_event_get ()

    ClutterEvent *      clutter_event_get                   (void);

Pops an event off the event queue. Applications should not need to call this.

Returns : | A ClutterEvent or NULL if queue empty

Since 0.4

### clutter_event_peek ()

    ClutterEvent *      clutter_event_peek                  (void);

Returns a pointer to the first event from the event queue but does not remove it.

Returns : | A ClutterEvent or NULL if queue empty.. transfer none.

Since 0.4

### clutter_event_put ()

    void                clutter_event_put                   (ClutterEvent *event);

Puts a copy of the event on the back of the event queue. The event will have the `CLUTTER_EVENT_FLAG_SYNTHETIC` flag set. If the source is set event signals will be emitted for this source and capture/bubbling for its ancestors. If the source is not set it will be generated by picking or use the actor that currently has keyboard focus

`event` : | a ClutterEvent

Since 0.6

### clutter_events_pending ()

    gboolean            clutter_events_pending              (void);

Checks if events are pending in the event queue.

Returns : | TRUE if there are pending events, FALSE otherwise.

Since 0.4

### clutter_event_get_button ()

    guint32             clutter_event_get_button            (ClutterEvent *event);

Retrieves the button number of `event`

`event` : | a ClutterEvent of type `CLUTTER_BUTTON_PRESS` or of type `CLUTTER_BUTTON_RELEASE`
Returns : | the button number

Since 1.0

### clutter_event_get_click_count ()

    guint               clutter_event_get_click_count       (ClutterEvent *event);

Retrieves the number of clicks of `event`

`event` : | a ClutterEvent of type `CLUTTER_BUTTON_PRESS` or of type `CLUTTER_BUTTON_RELEASE`
Returns : | the click count

Since 1.0

### clutter_event_get_key_symbol ()

    guint               clutter_event_get_key_symbol        (ClutterEvent *event);

Retrieves the key symbol of `event`

`event` : | a ClutterEvent of type `CLUTTER_KEY_PRESS` or of type `CLUTTER_KEY_RELEASE`
Returns : | the key symbol representing the key

Since 1.0

### clutter_event_get_key_code ()

    guint16             clutter_event_get_key_code          (ClutterEvent *event);

Retrieves the keycode of the key that caused `event`

`event` : | a ClutterEvent of type `CLUTTER_KEY_PRESS` or of type `CLUTTER_KEY_RELEASE`
Returns : | The keycode representing the key

Since 1.0

### clutter_event_get_key_unicode ()

    guint32             clutter_event_get_key_unicode       (ClutterEvent *event);

Retrieves the unicode value for the key that caused `keyev`.

`event` : | A ClutterKeyEvent
Returns : | The unicode value representing the key

### clutter_keysym_to_unicode ()

    guint32             clutter_keysym_to_unicode           (guint keyval);

Convert from a Clutter key symbol to the corresponding ISO10646 (Unicode) character.

`keyval` : | a key symbol
Returns : | a Unicode character, or 0 if there is no corresponding character.

### clutter_event_get_related ()

    ClutterActor *      clutter_event_get_related           (ClutterEvent *event);

Retrieves the related actor of a crossing event.

`event` : | a ClutterEvent of type `CLUTTER_ENTER` or of type `CLUTTER_LEAVE`
Returns : | the related ClutterActor, or `NULL`. transfer none.

Since 1.0

### clutter_event_get_scroll_direction ()

    ClutterScrollDirection  clutter_event_get_scroll_direction
                                                            (ClutterEvent *event);

Retrieves the direction of the scrolling of `event`

`event` : | a ClutterEvent of type `CLUTTER_SCROLL`
Returns : | the scrolling direction

Since 1.0

### enum ClutterInputDeviceType

    typedef enum {
      CLUTTER_POINTER_DEVICE,
      CLUTTER_KEYBOARD_DEVICE,
      CLUTTER_EXTENSION_DEVICE,

      CLUTTER_N_DEVICE_TYPES
    } ClutterInputDeviceType;

The types of input devices available.

The ClutterInputDeviceType enumeration can be extended at later date; not every platform supports every input device type.

`CLUTTER_POINTER_DEVICE` | A pointer device
`CLUTTER_KEYBOARD_DEVICE` | A keyboard device
`CLUTTER_EXTENSION_DEVICE` | A generic extension device
`CLUTTER_N_DEVICE_TYPES` | The number of device types

Since 1.0

### clutter_event_get_device ()

    ClutterInputDevice * clutter_event_get_device           (ClutterEvent *event);

Retrieves the ClutterInputDevice for the event.

The ClutterInputDevice structure is completely opaque and should be cast to the platform-specific implementation.

`event` : | a ClutterEvent
Returns : | the ClutterInputDevice or `NULL`

Since 1.0

### clutter_event_get_device_id ()

    gint                clutter_event_get_device_id         (ClutterEvent *event);

Retrieves the events device id if set.

`event` : | a clutter event
Returns : | A unique identifier for the device or -1 if the event has no specific device set.

### clutter_event_get_device_type ()

    ClutterInputDeviceType  clutter_event_get_device_type   (ClutterEvent *event);

Retrieves the type of the device for `event`

`event` : | a ClutterEvent
Returns : | the ClutterInputDeviceType for the device, if any is set

Since 1.0

### clutter_get_input_device_for_id ()

    ClutterInputDevice * clutter_get_input_device_for_id    (gint id);

Retrieves the ClutterInputDevice from its id.

`id` : | a device id
Returns : | a ClutterInputDevice, or `NULL`. transfer none.

Since 0.8

### clutter_input_device_get_device_id ()

    gint                clutter_input_device_get_device_id  (ClutterInputDevice *device);

Retrieves the unique identifier of `device`

`device` : | a ClutterInputDevice
Returns : | the identifier of the device

Since 1.0

### clutter_input_device_get_device_type ()

    ClutterInputDeviceType  clutter_input_device_get_device_type
                                                            (ClutterInputDevice *device);

Retrieves the type of `device`

`device` : | a ClutterInputDevice
Returns : | the type of the device

Since 1.0

### clutter_get_current_event_time ()

    guint32             clutter_get_current_event_time      (void);

Retrieves the timestamp of the last event, if there is an event or if the event has a timestamp.

Returns : | the event timestamp, or `CLUTTER_CURRENT_TIME`

Since 1.0