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

Generated by GTK-Doc V1.11