## 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;
    struct              ClutterButtonEvent;
    struct              ClutterKeyEvent;
    struct              ClutterMotionEvent;
    struct              ClutterScrollEvent;
    struct              ClutterStageStateEvent;
    struct              ClutterCrossingEvent;
    ClutterEvent *          clutter_event_new               (ClutterEventType type);
    ClutterEvent *          clutter_event_copy              (const ClutterEvent *event);
    void                clutter_event_free                  (ClutterEvent *event);
    ClutterEventType    clutter_event_type                  (const ClutterEvent *event);

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

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

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

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

    ClutterActor *          clutter_event_get_related       (const ClutterEvent *event);

    ClutterScrollDirection  clutter_event_get_scroll_direction
                                                            (const ClutterEvent *event);

    ClutterInputDevice *    clutter_event_get_device        (const ClutterEvent *event);
    gint                clutter_event_get_device_id         (const ClutterEvent *event);
    ClutterInputDeviceType  clutter_event_get_device_type   (const ClutterEvent *event);

    guint32             clutter_get_current_event_time      (void);
    const ClutterEvent * clutter_get_current_event          (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

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

### struct ClutterButtonEvent

    struct ClutterButtonEvent {
      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;
    };

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

### struct ClutterKeyEvent

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

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

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

### struct ClutterMotionEvent

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

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

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

### struct ClutterScrollEvent

    struct ClutterScrollEvent {
      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;
    };

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

### struct ClutterStageStateEvent

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

      ClutterStageState changed_mask;
      ClutterStageState new_state;
    };

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

### struct ClutterCrossingEvent

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

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

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

### 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              (const 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                  (const ClutterEvent *event);

Retrieves the type of the event.

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

### clutter_event_get_coords ()

    void                clutter_event_get_coords            (const 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, or `NULL`. [out]
`y` : | return location for the Y coordinate, or `NULL`. [out]

Since 0.4

### clutter_event_get_state ()

    ClutterModifierType  clutter_event_get_state            (const 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              (const 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        (const 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         (const 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             (const 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                   (const 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            (const 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       (const 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        (const 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          (const 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       (const 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       (const 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
                                                            (const ClutterEvent *event);

Retrieves the direction of the scrolling of `event`

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

Since 1.0

### clutter_event_get_device ()

    ClutterInputDevice *    clutter_event_get_device        (const 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`. The returned device is owned by the ClutterEvent and it should not be unreferenced. [transfer none]

Since 1.0

### clutter_event_get_device_id ()

    gint                clutter_event_get_device_id         (const 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   (const 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_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

### clutter_get_current_event ()

    const ClutterEvent * clutter_get_current_event          (void);

If an event is currently being processed, return that event. This function is intended to be used to access event state that might not be exposed by higher-level widgets. For example, to get the key modifier state from a Button 'clicked' event.

Returns : | The current ClutterEvent, or `NULL` if none. [transfer none]

Since 1.2