Events: Clutter Reference Manual

## Events Events — User and window system events |

## Functions

#define | CLUTTER_CURRENT_TIME
#define | CLUTTER_PRIORITY_EVENTS
#define | CLUTTER_EVENT_PROPAGATE
#define | CLUTTER_EVENT_STOP
ClutterEvent * | clutter_event_new ()
ClutterEvent * | clutter_event_copy ()
void | clutter_event_free ()
ClutterEventType | clutter_event_type ()
void | clutter_event_set_coords ()
void | clutter_event_get_coords ()
void | clutter_event_set_state ()
ClutterModifierType | clutter_event_get_state ()
void | clutter_event_get_state_full ()
void | clutter_event_set_time ()
guint32 | clutter_event_get_time ()
void | clutter_event_set_source ()
ClutterActor * | clutter_event_get_source ()
void | clutter_event_set_stage ()
ClutterStage * | clutter_event_get_stage ()
void | clutter_event_set_flags ()
ClutterEventFlags | clutter_event_get_flags ()
gdouble * | clutter_event_get_axes ()
ClutterEventSequence * | clutter_event_get_event_sequence ()
double | clutter_event_get_angle ()
float | clutter_event_get_distance ()
void | clutter_event_get_position ()
gboolean | clutter_event_has_control_modifier ()
gboolean | clutter_event_has_shift_modifier ()
gboolean | clutter_event_is_pointer_emulated ()
guint | clutter_event_get_gesture_swipe_finger_count ()
gdouble | clutter_event_get_gesture_pinch_angle_delta ()
gdouble | clutter_event_get_gesture_pinch_scale ()
ClutterTouchpadGesturePhase | clutter_event_get_gesture_phase ()
void | clutter_event_get_gesture_motion_delta ()
ClutterEvent * | clutter_event_get ()
ClutterEvent * | clutter_event_peek ()
void | clutter_event_put ()
gboolean | clutter_events_pending ()
gboolean | (*ClutterEventFilterFunc) ()
guint | clutter_event_add_filter ()
void | clutter_event_remove_filter ()
#define | CLUTTER_BUTTON_PRIMARY
#define | CLUTTER_BUTTON_MIDDLE
#define | CLUTTER_BUTTON_SECONDARY
void | clutter_event_set_button ()
guint32 | clutter_event_get_button ()
guint | clutter_event_get_click_count ()
void | clutter_event_set_key_symbol ()
guint | clutter_event_get_key_symbol ()
void | clutter_event_set_key_code ()
guint16 | clutter_event_get_key_code ()
void | clutter_event_set_key_unicode ()
gunichar | clutter_event_get_key_unicode ()
guint32 | clutter_keysym_to_unicode ()
guint | clutter_unicode_to_keysym ()
void | clutter_event_set_related ()
ClutterActor * | clutter_event_get_related ()
void | clutter_event_set_scroll_direction ()
ClutterScrollDirection | clutter_event_get_scroll_direction ()
void | clutter_event_get_scroll_delta ()
void | clutter_event_set_scroll_delta ()
void | clutter_event_set_device ()
ClutterInputDevice * | clutter_event_get_device ()
void | clutter_event_set_source_device ()
ClutterInputDevice * | clutter_event_get_source_device ()
gint | clutter_event_get_device_id ()
ClutterInputDeviceType | clutter_event_get_device_type ()
guint32 | clutter_get_current_event_time ()
const ClutterEvent * | clutter_get_current_event ()

## Types and Values

enum | ClutterModifierType
enum | ClutterScrollDirection
enum | ClutterStageState
enum | ClutterEventType
| ClutterEvent
enum | ClutterEventFlags
struct | ClutterButtonEvent
struct | ClutterKeyEvent
struct | ClutterMotionEvent
struct | ClutterScrollEvent
struct | ClutterStageStateEvent
struct | ClutterCrossingEvent
struct | ClutterTouchEvent
| ClutterEventSequence
struct | ClutterTouchpadPinchEvent
struct | ClutterTouchpadSwipeEvent
enum | ClutterTouchpadGesturePhase

## Object Hierarchy

        GBoxed
        ├── ClutterEvent
        ╰── ClutterEventSequence

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

## Functions

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

### CLUTTER_EVENT_PROPAGATE

    #define CLUTTER_EVENT_PROPAGATE         (FALSE)

Continues the propagation of an event; this macro should be used in event-related signals.

Since: 1.10

### CLUTTER_EVENT_STOP

    #define CLUTTER_EVENT_STOP              (TRUE)

Stops the propagation of an event; this macro should be used in event-related signals.

Since: 1.10

### clutter_event_new ()

    ClutterEvent *
    clutter_event_new (ClutterEventType type);

Creates a new ClutterEvent of the specified type.

#### Parameters

type | The type of event. |

#### Returns

A newly allocated ClutterEvent.

[transfer full]

### clutter_event_copy ()

    ClutterEvent *
    clutter_event_copy (const ClutterEvent *event);

Copies `event` .

#### Parameters

event | A ClutterEvent. |

#### Returns

A newly allocated ClutterEvent.

[transfer full]

### clutter_event_free ()

    void
    clutter_event_free (ClutterEvent *event);

Frees all resources used by `event` .

#### Parameters

event | A ClutterEvent. |

### clutter_event_type ()

    ClutterEventType
    clutter_event_type (const ClutterEvent *event);

Retrieves the type of the event.

#### Parameters

event | a ClutterEvent |

#### Returns

a ClutterEventType

### clutter_event_set_coords ()

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

Sets the coordinates of the `event` .

#### Parameters

event | a ClutterEvent |
x | the X coordinate of the event |
y | the Y coordinate of the event |

Since: 1.8

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

#### Parameters

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_set_state ()

    void
    clutter_event_set_state (ClutterEvent *event,
                             ClutterModifierType state);

Sets the modifier state of the event.

#### Parameters

event | a ClutterEvent |
state | the modifier state to set |

Since: 1.8

### clutter_event_get_state ()

    ClutterModifierType
    clutter_event_get_state (const ClutterEvent *event);

Retrieves the modifier state of the event. In case the window system supports reporting latched and locked modifiers, this function returns the effective state.

#### Parameters

event | a ClutterEvent |

#### Returns

the modifier state parameter, or 0

Since: 0.4

### clutter_event_get_state_full ()

    void
    clutter_event_get_state_full (const ClutterEvent *event,
                                  ClutterModifierType *button_state,
                                  ClutterModifierType *base_state,
                                  ClutterModifierType *latched_state,
                                  ClutterModifierType *locked_state,
                                  ClutterModifierType *effective_state);

Retrieves the decomposition of the keyboard state into button, base, latched, locked and effective. This can be used to transmit to other applications, for example when implementing a wayland compositor.

#### Parameters

event | a ClutterEvent |
button_state | the pressed buttons as a mask. | [out][allow-none]
base_state | the regular pressed modifier keys. | [out][allow-none]
latched_state | the latched modifier keys (currently released but still valid for one key press/release). | [out][allow-none]
locked_state | the locked modifier keys (valid until the lock key is pressed and released again). | [out][allow-none]
effective_state | the logical OR of all the state bits above. | [out][allow-none]

Since: 1.16

### clutter_event_set_time ()

    void
    clutter_event_set_time (ClutterEvent *event,
                            guint32 time_);

Sets the time of the event.

#### Parameters

event | a ClutterEvent |
time_ | the time of the event |

Since: 1.8

### clutter_event_get_time ()

    guint32
    clutter_event_get_time (const ClutterEvent *event);

Retrieves the time of the event.

#### Parameters

event | a ClutterEvent |

#### Returns

the time of the event, or `CLUTTER_CURRENT_TIME`

Since: 0.4

### clutter_event_set_source ()

    void
    clutter_event_set_source (ClutterEvent *event,
                              ClutterActor *actor);

Sets the source ClutterActor of `event` .

#### Parameters

event | a ClutterEvent |
actor | a ClutterActor, or `NULL`. | [allow-none]

Since: 1.8

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

#### Parameters

event | a ClutterEvent |

#### Returns

a ClutterActor.

[transfer none]

Since: 0.6

### clutter_event_set_stage ()

    void
    clutter_event_set_stage (ClutterEvent *event,
                             ClutterStage *stage);

Sets the source ClutterStage of the event.

#### Parameters

event | a ClutterEvent |
stage | a ClutterStage, or `NULL`. | [allow-none]

Since: 1.8

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

#### Parameters

event | a ClutterEvent |

#### Returns

a ClutterStage.

[transfer none]

Since: 0.8

### clutter_event_set_flags ()

    void
    clutter_event_set_flags (ClutterEvent *event,
                             ClutterEventFlags flags);

Sets the ClutterEventFlags of `event`

#### Parameters

event | a ClutterEvent |
flags | a binary OR of ClutterEventFlags values |

Since: 1.8

### clutter_event_get_flags ()

    ClutterEventFlags
    clutter_event_get_flags (const ClutterEvent *event);

Retrieves the ClutterEventFlags of `event`

#### Parameters

event | a ClutterEvent |

#### Returns

the event flags

Since: 1.0

### clutter_event_get_axes ()

    gdouble *
    clutter_event_get_axes (const ClutterEvent *event,
                            guint *n_axes);

Retrieves the array of axes values attached to the event.

#### Parameters

event | a ClutterEvent |
n_axes | return location for the number of axes returned. | [out]

#### Returns

an array of axis values.

[transfer none]

Since: 1.6

### clutter_event_get_event_sequence ()

    ClutterEventSequence *
    clutter_event_get_event_sequence (const ClutterEvent *event);

Retrieves the ClutterEventSequence of `event` .

#### Parameters

event | a ClutterEvent of type `CLUTTER_TOUCH_BEGIN`, `CLUTTER_TOUCH_UPDATE`, `CLUTTER_TOUCH_END`, or `CLUTTER_TOUCH_CANCEL` |

#### Returns

the event sequence, or `NULL`.

[transfer none]

Since: 1.10

### clutter_event_get_angle ()

    double
    clutter_event_get_angle (const ClutterEvent *source,
                             const ClutterEvent *target);

Retrieves the angle relative from `source` to `target` .

The direction of the angle is from the position X axis towards the positive Y axis.

#### Parameters

source | a ClutterEvent |
target | a ClutterEvent |

#### Returns

the angle between two ClutterEvent

Since: 1.12

### clutter_event_get_distance ()

    float
    clutter_event_get_distance (const ClutterEvent *source,
                                const ClutterEvent *target);

Retrieves the distance between two events, a `source` and a `target` .

#### Parameters

source | a ClutterEvent |
target | a ClutterEvent |

#### Returns

the distance between two ClutterEvent

Since: 1.12

### clutter_event_get_position ()

    void
    clutter_event_get_position (const ClutterEvent *event,
                                ClutterPoint *position);

Retrieves the event coordinates as a ClutterPoint.

#### Parameters

event | a ClutterEvent |
position | a ClutterPoint |

Since: 1.12

### clutter_event_has_control_modifier ()

    gboolean
    clutter_event_has_control_modifier (const ClutterEvent *event);

Checks whether `event` has the Control modifier mask set.

#### Parameters

event | a ClutterEvent |

#### Returns

`TRUE` if the event has the Control modifier mask set

Since: 1.12

### clutter_event_has_shift_modifier ()

    gboolean
    clutter_event_has_shift_modifier (const ClutterEvent *event);

Checks whether `event` has the Shift modifier mask set.

#### Parameters

event | a ClutterEvent |

#### Returns

`TRUE` if the event has the Shift modifier mask set

Since: 1.12

### clutter_event_is_pointer_emulated ()

    gboolean
    clutter_event_is_pointer_emulated (const ClutterEvent *event);

Checks whether a pointer `event` has been generated by the windowing system. The returned value can be used to distinguish between events synthesized by the windowing system itself (as opposed by Clutter).

#### Parameters

event | a ClutterEvent |

#### Returns

`TRUE` if the event is pointer emulated

Since: 1.12

### clutter_event_get_gesture_swipe_finger_count ()

    guint
    clutter_event_get_gesture_swipe_finger_count
                                   (const ClutterEvent *event);

Returns the number of fingers that is triggering the touchpad gesture.

#### Parameters

event | a touchpad swipe event |

#### Returns

the number of fingers swiping.

Since: 1.24

### clutter_event_get_gesture_pinch_angle_delta ()

    gdouble
    clutter_event_get_gesture_pinch_angle_delta
                                   (const ClutterEvent *event);

Returns the angle delta reported by this specific event.

#### Parameters

event | a touchpad pinch event |

#### Returns

The angle delta relative to the previous event.

Since: 1.24

### clutter_event_get_gesture_pinch_scale ()

    gdouble
    clutter_event_get_gesture_pinch_scale (const ClutterEvent *event);

Returns the current scale as reported by `event` , 1.0 being the original distance at the time the corresponding event with phase `CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN` is received. is received.

#### Parameters

event | a touchpad pinch event |

#### Returns

the current pinch gesture scale

Since: 1.24

### clutter_event_get_gesture_phase ()

    ClutterTouchpadGesturePhase
    clutter_event_get_gesture_phase (const ClutterEvent *event);

Returns the phase of the event, See ClutterTouchpadGesturePhase.

#### Parameters

event | a touchpad gesture event |

#### Returns

the phase of the gesture event.

### clutter_event_get_gesture_motion_delta ()

    void
    clutter_event_get_gesture_motion_delta
                                   (const ClutterEvent *event,
                                    gdouble *dx,
                                    gdouble *dy);

Returns the gesture motion deltas relative to the current pointer position.

#### Parameters

event | A clutter touchpad gesture event |
dx | the displacement relative to the pointer position in the X axis, or `NULL`. | [out][allow-none]
dy | the displacement relative to the pointer position in the Y axis, or `NULL`. | [out][allow-none]

Since: 1.24

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

#### Parameters

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

### ClutterEventFilterFunc ()

    gboolean
    (*ClutterEventFilterFunc) (const ClutterEvent *event,
                               gpointer user_data);

A function pointer type used by event filters that are added with `clutter_event_add_filter()`.

#### Parameters

event | the event that is going to be emitted |
user_data | the data pointer passed to `clutter_event_add_filter()` |

#### Returns

`CLUTTER_EVENT_STOP` to indicate that the event has been handled or `CLUTTER_EVENT_PROPAGATE` otherwise. Returning `CLUTTER_EVENT_STOP` skips any further filter functions and prevents the signal emission for the event.

Since: 1.18

### clutter_event_add_filter ()

    guint
    clutter_event_add_filter (ClutterStage *stage,
                              ClutterEventFilterFunc func,
                              GDestroyNotify notify,
                              gpointer user_data);

Adds a function which will be called for all events that Clutter processes. The function will be called before any signals are emitted for the event and it will take precedence over any grabs.

#### Parameters

stage | The ClutterStage to capture events for. | [allow-none]
func | The callback function which will be passed all events. |
notify | A GDestroyNotify |
user_data | A data pointer to pass to the function. |

#### Returns

an identifier for the event filter, to be used with `clutter_event_remove_filter()`.

Since: 1.18

### clutter_event_remove_filter ()

    void
    clutter_event_remove_filter (guint id);

Removes an event filter that was previously added with `clutter_event_add_filter()`.

#### Parameters

id | The ID of the event filter, as returned from `clutter_event_add_filter()` |

Since: 1.18

### CLUTTER_BUTTON_PRIMARY

    #define CLUTTER_BUTTON_PRIMARY          (1)

The primary button of a pointer device.

This is typically the left mouse button in a right-handed mouse configuration.

Since: 1.10

### CLUTTER_BUTTON_MIDDLE

    #define CLUTTER_BUTTON_MIDDLE           (2)

The middle button of a pointer device.

Since: 1.10

### CLUTTER_BUTTON_SECONDARY

    #define CLUTTER_BUTTON_SECONDARY        (3)

The secondary button of a pointer device.

This is typically the right mouse button in a right-handed mouse configuration.

Since: 1.10

### clutter_event_set_button ()

    void
    clutter_event_set_button (ClutterEvent *event,
                              guint32 button);

Sets the button number of `event`

#### Parameters

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

Since: 1.8

### clutter_event_get_button ()

    guint32
    clutter_event_get_button (const ClutterEvent *event);

Retrieves the button number of `event`

#### Parameters

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`

#### Parameters

event | a ClutterEvent of type `CLUTTER_BUTTON_PRESS` or of type `CLUTTER_BUTTON_RELEASE` |

#### Returns

the click count

Since: 1.0

### clutter_event_set_key_symbol ()

    void
    clutter_event_set_key_symbol (ClutterEvent *event,
                                  guint key_sym);

Sets the key symbol of `event` .

#### Parameters

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

Since: 1.8

### clutter_event_get_key_symbol ()

    guint
    clutter_event_get_key_symbol (const ClutterEvent *event);

Retrieves the key symbol of `event`

#### Parameters

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_set_key_code ()

    void
    clutter_event_set_key_code (ClutterEvent *event,
                                guint16 key_code);

Sets the keycode of the `event` .

#### Parameters

event | a ClutterEvent of type `CLUTTER_KEY_PRESS` or `CLUTTER_KEY_RELEASE` |
key_code | the keycode representing the key |

Since: 1.8

### clutter_event_get_key_code ()

    guint16
    clutter_event_get_key_code (const ClutterEvent *event);

Retrieves the keycode of the key that caused `event`

#### Parameters

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_set_key_unicode ()

    void
    clutter_event_set_key_unicode (ClutterEvent *event,
                                   gunichar key_unicode);

Sets the Unicode value of `event` .

#### Parameters

event | a ClutterEvent of type `CLUTTER_KEY_PRESS` or `CLUTTER_KEY_RELEASE` |
key_unicode | the Unicode value representing the key |

Since: 1.8

### clutter_event_get_key_unicode ()

    gunichar
    clutter_event_get_key_unicode (const ClutterEvent *event);

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

#### Parameters

event | a ClutterEvent of type `CLUTTER_KEY_PRESS` or `CLUTTER_KEY_RELEASE` |

#### Returns

The unicode value representing the key

### clutter_keysym_to_unicode ()

    guint32
    clutter_keysym_to_unicode (guint keyval);

Converts `keyval` from a Clutter key symbol to the corresponding ISO10646 (Unicode) character.

#### Parameters

keyval | a key symbol |

#### Returns

a Unicode character, or 0 if there is no corresponding character.

### clutter_unicode_to_keysym ()

    guint
    clutter_unicode_to_keysym (guint32 wc);

Convert from a ISO10646 character to a key symbol.

#### Parameters

wc | a ISO10646 encoded character |

#### Returns

the corresponding Clutter key symbol, if one exists. or, if there is no corresponding symbol, wc | 0x01000000

Since: 1.10

### clutter_event_set_related ()

    void
    clutter_event_set_related (ClutterEvent *event,
                               ClutterActor *actor);

Sets the related actor of a crossing event

#### Parameters

event | a ClutterEvent of type `CLUTTER_ENTER` or `CLUTTER_LEAVE` |
actor | a ClutterActor or `NULL`. | [allow-none]

Since: 1.8

### clutter_event_get_related ()

    ClutterActor *
    clutter_event_get_related (const ClutterEvent *event);

Retrieves the related actor of a crossing event.

#### Parameters

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_set_scroll_direction ()

    void
    clutter_event_set_scroll_direction (ClutterEvent *event,
                                        ClutterScrollDirection direction);

Sets the direction of the scrolling of `event`

#### Parameters

event | a ClutterEvent |
direction | the scrolling direction |

Since: 1.8

### clutter_event_get_scroll_direction ()

    ClutterScrollDirection
    clutter_event_get_scroll_direction (const ClutterEvent *event);

Retrieves the direction of the scrolling of `event`

#### Parameters

event | a ClutterEvent of type `CLUTTER_SCROLL` |

#### Returns

the scrolling direction

Since: 1.0

### clutter_event_get_scroll_delta ()

    void
    clutter_event_get_scroll_delta (const ClutterEvent *event,
                                    gdouble *dx,
                                    gdouble *dy);

Retrieves the precise scrolling information of `event` .

The `event` has to have a ClutterScrollEvent.direction value of `CLUTTER_SCROLL_SMOOTH`.

#### Parameters

event | a ClutterEvent of type `CLUTTER_SCROLL` |
dx | return location for the delta on the horizontal axis. | [out]
dy | return location for the delta on the vertical axis. | [out]

Since: 1.10

### clutter_event_set_scroll_delta ()

    void
    clutter_event_set_scroll_delta (ClutterEvent *event,
                                    gdouble dx,
                                    gdouble dy);

Sets the precise scrolling information of `event` .

#### Parameters

event | a ClutterEvent of type `CLUTTER_SCROLL` |
dx | delta on the horizontal axis |
dy | delta on the vertical axis |

Since: 1.10

### clutter_event_set_device ()

    void
    clutter_event_set_device (ClutterEvent *event,
                              ClutterInputDevice *device);

Sets the device for `event` .

#### Parameters

event | a ClutterEvent |
device | a ClutterInputDevice, or `NULL`. | [allow-none]

Since: 1.6

### clutter_event_get_device ()

    ClutterInputDevice *
    clutter_event_get_device (const ClutterEvent *event);

Retrieves the ClutterInputDevice for the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()`.

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

#### Parameters

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_set_source_device ()

    void
    clutter_event_set_source_device (ClutterEvent *event,
                                     ClutterInputDevice *device);

Sets the source ClutterInputDevice for `event` .

The ClutterEvent must have been created using `clutter_event_new()`.

#### Parameters

event | a ClutterEvent |
device | a ClutterInputDevice. | [allow-none]

Since: 1.8

### clutter_event_get_source_device ()

    ClutterInputDevice *
    clutter_event_get_source_device (const ClutterEvent *event);

Retrieves the hardware device that originated the event.

If you need the virtual device, use `clutter_event_get_device()`.

If no hardware device originated this event, this function will return the same device as `clutter_event_get_device()`.

#### Parameters

event | a ClutterEvent |

#### Returns

a pointer to a ClutterInputDevice or `NULL`.

[transfer none]

Since: 1.6

### clutter_event_get_device_id ()

    gint
    clutter_event_get_device_id (const ClutterEvent *event);

Retrieves the events device id if set.

#### Parameters

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`

#### Parameters

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

## Types and Values

### enum ClutterModifierType

Masks applied to a ClutterEvent by modifiers.

Note that Clutter may add internal values to events which include reserved values such as `CLUTTER_MODIFIER_RESERVED_13_MASK`. Your code should preserve and ignore them. You can use `CLUTTER_MODIFIER_MASK` to remove all reserved values.

#### Members

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

Direction of a pointer scroll event.

The `CLUTTER_SCROLL_SMOOTH` value implies that the ClutterScrollEvent has precise scrolling delta information.

#### Members

CLUTTER_SCROLL_UP | Scroll up |
CLUTTER_SCROLL_DOWN | Scroll down |
CLUTTER_SCROLL_LEFT | Scroll left |
CLUTTER_SCROLL_RIGHT | Scroll right |
CLUTTER_SCROLL_SMOOTH | Precise scrolling delta (available in 1.10) |

Since: 0.4

### enum ClutterStageState

Stage state masks, used by the ClutterEvent of type `CLUTTER_STAGE_STATE`.

#### Members

CLUTTER_STAGE_STATE_FULLSCREEN | Fullscreen mask |
CLUTTER_STAGE_STATE_OFFSCREEN | Offscreen mask (deprecated) |
CLUTTER_STAGE_STATE_ACTIVATED | Activated mask |

Since: 0.4

### enum ClutterEventType

Types of events.

#### Members

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 state change event |
CLUTTER_DESTROY_NOTIFY | Destroy notification event |
CLUTTER_CLIENT_MESSAGE | Client message event |
CLUTTER_DELETE | Stage delete event |
CLUTTER_TOUCH_BEGIN | A new touch event sequence has started; event added in 1.10 |
CLUTTER_TOUCH_UPDATE | A touch event sequence has been updated; event added in 1.10 |
CLUTTER_TOUCH_END | A touch event sequence has finished; event added in 1.10 |
CLUTTER_TOUCH_CANCEL | A touch event sequence has been canceled; event added in 1.10 |
CLUTTER_TOUCHPAD_PINCH | A pinch gesture event, the current state is determined by its phase field; event added in 1.24 |
CLUTTER_TOUCHPAD_SWIPE | A swipe gesture event, the current state is determined by its phase field; event added in 1.24 |
CLUTTER_EVENT_LAST | Marks the end of the ClutterEventType enumeration; added in 1.10 |

Since: 0.4

### ClutterEvent

Generic event wrapper.

Since: 0.2

### enum ClutterEventFlags

Flags for the ClutterEvent

#### Members

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()`.

#### Members

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`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |

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

#### Members

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`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |

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

#### Members

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`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |

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

#### Members

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`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |

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.

#### Members

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

#### Members

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`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |
ClutterActor *`related`; | actor related to the crossing |

Since: 0.2

### struct ClutterTouchEvent

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

      gfloat x;
      gfloat y;
      ClutterEventSequence *sequence;
      ClutterModifierType modifier_state;
      gdouble *axes; /* reserved */
      ClutterInputDevice *device;
    };

Used for touch events.

The `type` field will be one of `CLUTTER_TOUCH_BEGIN`, `CLUTTER_TOUCH_END`, `CLUTTER_TOUCH_UPDATE`, or `CLUTTER_TOUCH_CANCEL`.

Touch events are grouped into sequences; each touch sequence will begin with a `CLUTTER_TOUCH_BEGIN` event, progress with `CLUTTER_TOUCH_UPDATE` events, and end either with a `CLUTTER_TOUCH_END` event or with a `CLUTTER_TOUCH_CANCEL` event.

With multi-touch capable devices there can be multiple event sequence running at the same time.

#### Members

ClutterEventType `type`; | event type |
guint32 `time`; | event time |
ClutterEventFlags `flags`; | event flags |
ClutterStage *`stage`; | event source stage |
ClutterActor *`source`; | event source actor (unused) |
gfloat `x`; | the X coordinate of the pointer, relative to the stage |
gfloat `y`; | the Y coordinate of the pointer, relative to the stage |
ClutterEventSequence *`sequence`; | the event sequence that this event belongs to |
ClutterModifierType `modifier_state`; | a bit-mask representing the state of modifier keys (e.g. Control, Shift, and Alt) and the pointer buttons. See ClutterModifierType. | [type ClutterModifierType]
gdouble *`axes`; | reserved |
ClutterInputDevice *`device`; | the device that originated the event. If you want the physical device the event originated from, use `clutter_event_get_source_device()` |

Since: 1.10

### ClutterEventSequence

    typedef struct _ClutterEventSequence ClutterEventSequence;

The ClutterEventSequence structure is an opaque type used to denote the event sequence of a touch event.

Since: 1.12

### struct ClutterTouchpadPinchEvent

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

      ClutterTouchpadGesturePhase phase;
      gfloat x;
      gfloat y;
      gfloat dx;
      gfloat dy;
      gfloat angle_delta;
      gfloat scale;
    };

Used for touchpad pinch gesture events. The current state of the gesture will be determined by the `phase` field.

Each event with phase `CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN` will report a `scale` of 1.0, all later phases in the gesture report the current scale relative to the initial 1.0 value (eg. 0.5 being half the size, 2.0 twice as big).

#### Members

ClutterEventType `type`; | event type |
guint32 `time`; | event time |
ClutterEventFlags `flags`; | event flags |
ClutterStage *`stage`; | event source stage |
ClutterActor *`source`; | event source actor (unused) |
ClutterTouchpadGesturePhase `phase`; | the current phase of the gesture |
gfloat `x`; | the X coordinate of the pointer, relative to the stage |
gfloat `y`; | the Y coordinate of the pointer, relative to the stage |
gfloat `dx`; | movement delta of the pinch focal point in the X axis |
gfloat `dy`; | movement delta of the pinch focal point in the Y axis |
gfloat `angle_delta`; | angle delta in degrees, clockwise rotations are represented by positive deltas |
gfloat `scale`; | the current scale |

Since: 1.24

### struct ClutterTouchpadSwipeEvent

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

      ClutterTouchpadGesturePhase phase;
      guint n_fingers;
      gfloat x;
      gfloat y;
      gfloat dx;
      gfloat dy;
    };

Used for touchpad swipe gesture events. The current state of the gesture will be determined by the `phase` field.

#### Members

ClutterEventType `type`; | event type |
guint32 `time`; | event time |
ClutterEventFlags `flags`; | event flags |
ClutterStage *`stage`; | event source stage |
ClutterActor *`source`; | event source actor (unused) |
ClutterTouchpadGesturePhase `phase`; | the current phase of the gesture |
guint `n_fingers`; | the number of fingers triggering the swipe |
gfloat `x`; | the X coordinate of the pointer, relative to the stage |
gfloat `y`; | the Y coordinate of the pointer, relative to the stage |
gfloat `dx`; | movement delta of the pinch focal point in the X axis |
gfloat `dy`; | movement delta of the pinch focal point in the Y axis |

Since: 1.24

### enum ClutterTouchpadGesturePhase

The phase of a touchpad gesture event. All gestures are guaranteed to begin with an event of type `CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN`, followed by a number of `CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE` (possibly 0).

A finished gesture may have 2 possible outcomes, an event with phase `CLUTTER_TOUCHPAD_GESTURE_PHASE_END` will be emitted when the gesture is considered successful, this should be used as the hint to perform any permanent changes.

Cancelled gestures may be so for a variety of reasons, due to hardware, or due to the gesture recognition layers hinting the gesture did not finish resolutely (eg. a 3rd finger being added during a pinch gesture). In these cases, the last event with report the phase `CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL`, this should be used as a hint to undo any visible/permanent changes that were done throughout the progress of the gesture.

See also ClutterTouchpadPinchEvent and ClutterTouchpadPinchEvent.

#### Members

CLUTTER_TOUCHPAD_GESTURE_PHASE_BEGIN | The gesture has begun. |
CLUTTER_TOUCHPAD_GESTURE_PHASE_UPDATE | The gesture has been updated. |
CLUTTER_TOUCHPAD_GESTURE_PHASE_END | The gesture was finished, changes should be permanently applied. |
CLUTTER_TOUCHPAD_GESTURE_PHASE_CANCEL | The gesture was cancelled, all changes should be undone. |

Since: 1.24