## 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,
                                                             gint *x,
                                                             gint *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);

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

    guint32             clutter_button_event_button         (ClutterButtonEvent *buttev);

    guint               clutter_key_event_symbol            (ClutterKeyEvent *keyev);
    guint16             clutter_key_event_code              (ClutterKeyEvent *keyev);
    guint32             clutter_key_event_unicode           (ClutterKeyEvent *keyev);
    guint32             clutter_keysym_to_unicode           (guint keyval);

    gint                clutter_event_get_device_id         (ClutterEvent *event);
    ClutterInputDevice* clutter_get_input_device_for_id     (gint id);

## Description

Windowing events handled by Clutter.

## 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
    } 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

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_FLAG_SYNTHETIC = 1 << 0,
    } ClutterEventFlags;

Flags for the ClutterEvent

`CLUTTER_EVENT_FLAG_SYNTHETIC` | Synthetic event

Since 0.6

### ClutterButtonEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;
      gint x;
      gint y;
      ClutterModifierType modifier_state;
      guint32 button;
      guint click_count;
      gdouble *axes; /* Future use */
      ClutterInputDevice *device; /* Future use */
    } ClutterButtonEvent;

Button event

ClutterEventType `type`; | event type
guint32 `time`; | event time
ClutterEventFlags `flags`; | event flags
ClutterStage *`stage`; | event source stage
ClutterActor *`source`; | event source actor
gint `x`; | event X coordinate
gint `y`; | event Y coordinate
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;
    } 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

Since 0.2

### ClutterMotionEvent

    typedef struct {
      ClutterEventType type;
      guint32 time;
      ClutterEventFlags flags;
      ClutterStage *stage;
      ClutterActor *source;
      gint x;
      gint y;
      ClutterModifierType modifier_state;
      gdouble *axes; /* Future use */
      ClutterInputDevice *device; /* Future use */
    } 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
gint `x`; | event X coordinate
gint `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;
      gint x;
      gint y;
      ClutterScrollDirection direction;
      ClutterModifierType modifier_state;
      gdouble *axes; /* future use */
      ClutterInputDevice *device; /* future use */
    } 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
gint `x`; | event X coordinate
gint `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; /* unused 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;
      gint x;
      gint y;
      ClutterInputDevice *device; /* future use */
      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
gint `x`; | event X coordinate
gint `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,
                                                             gint *x,
                                                             gint *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

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

Since 0.8

### 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.

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 it's 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_button_event_button ()

    guint32             clutter_button_event_button         (ClutterButtonEvent *buttev);

Retrieve the button number of the event.

`buttev` : | a ClutterButtonEvent
Returns : | the button number.

Since 0.4

### clutter_key_event_symbol ()

    guint               clutter_key_event_symbol            (ClutterKeyEvent *keyev);

Retrieves the value of the key that caused `keyev`.

`keyev` : | A ClutterKeyEvent
Returns : | The keysym representing the key

### clutter_key_event_code ()

    guint16             clutter_key_event_code              (ClutterKeyEvent *keyev);

Retrieves the keycode of the key that caused `keyev`.

`keyev` : | A ClutterKeyEvent
Returns : | The keycode representing the key

### clutter_key_event_unicode ()

    guint32             clutter_key_event_unicode           (ClutterKeyEvent *keyev);

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

`keyev` : | 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 clutter key symbol
Returns : | the corresponding unicode character, or 0 if there is no corresponding character.

### 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_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`

Since 0.8