enum ClutterInputDeviceType

typedef enum {
  CLUTTER_POINTER_DEVICE,
  CLUTTER_KEYBOARD_DEVICE,
  CLUTTER_EXTENSION_DEVICE,
  CLUTTER_JOYSTICK_DEVICE,
  CLUTTER_TABLET_DEVICE,
  CLUTTER_TOUCHPAD_DEVICE,
  CLUTTER_TOUCHSCREEN_DEVICE,
  CLUTTER_PEN_DEVICE,
  CLUTTER_ERASER_DEVICE,
  CLUTTER_CURSOR_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.

Since 1.0

enum ClutterInputAxis

typedef enum {
  CLUTTER_INPUT_AXIS_IGNORE,

  CLUTTER_INPUT_AXIS_X,
  CLUTTER_INPUT_AXIS_Y,
  CLUTTER_INPUT_AXIS_PRESSURE,
  CLUTTER_INPUT_AXIS_XTILT,
  CLUTTER_INPUT_AXIS_YTILT,
  CLUTTER_INPUT_AXIS_WHEEL,
  CLUTTER_INPUT_AXIS_DISTANCE,

  CLUTTER_INPUT_AXIS_LAST
} ClutterInputAxis;

The type of axes Clutter recognizes on a ClutterInputDevice

Since 1.6

enum ClutterInputMode

typedef enum {
  CLUTTER_INPUT_MODE_MASTER,
  CLUTTER_INPUT_MODE_SLAVE,
  CLUTTER_INPUT_MODE_FLOATING
} ClutterInputMode;

The mode for input devices available.

Since 1.6

ClutterInputDevice

typedef struct _ClutterInputDevice ClutterInputDevice;

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

clutter_input_device_get_device_id ()

gint                clutter_input_device_get_device_id  (ClutterInputDevice *device);

Retrieves the unique identifier of device

Since 1.0

clutter_input_device_get_device_type ()

ClutterInputDeviceType clutter_input_device_get_device_type
                                                        (ClutterInputDevice *device);

Retrieves the type of device

Since 1.0

clutter_input_device_get_device_name ()

const gchar *       clutter_input_device_get_device_name
                                                        (ClutterInputDevice *device);

Retrieves the name of the device

Since 1.2

clutter_input_device_get_device_mode ()

ClutterInputMode    clutter_input_device_get_device_mode
                                                        (ClutterInputDevice *device);

Retrieves the ClutterInputMode of device.

Since 1.6

clutter_input_device_get_has_cursor ()

gboolean            clutter_input_device_get_has_cursor (ClutterInputDevice *device);

Retrieves whether device has a pointer that follows the device motion.

Since 1.6

clutter_input_device_set_enabled ()

void                clutter_input_device_set_enabled    (ClutterInputDevice *device,
                                                         gboolean enabled);

Enables or disables a ClutterInputDevice.

Only devices with a "device-mode" property set to CLUTTER_INPUT_MODE_SLAVE or CLUTTER_INPUT_MODE_FLOATING can be disabled.

Since 1.6

clutter_input_device_get_enabled ()

gboolean            clutter_input_device_get_enabled    (ClutterInputDevice *device);

Retrieves whether device is enabled.

Since 1.6

clutter_input_device_get_associated_device ()

ClutterInputDevice * clutter_input_device_get_associated_device
                                                        (ClutterInputDevice *device);

Retrieves a pointer to the ClutterInputDevice that has been associated to device.

If the "device-mode" property of device is set to CLUTTER_INPUT_MODE_MASTER, this function will return NULL.

Since 1.6

clutter_input_device_get_slave_devices ()

GList *             clutter_input_device_get_slave_devices
                                                        (ClutterInputDevice *device);

Retrieves the slave devices attached to device.

Since 1.6

clutter_input_device_keycode_to_evdev ()

gboolean            clutter_input_device_keycode_to_evdev
                                                        (ClutterInputDevice *device,
                                                         guint hardware_keycode,
                                                         guint *evdev_keycode);

Translates a hardware keycode from a ClutterKeyEvent to the equivalent evdev keycode. Note that depending on the input backend used by Clutter this function can fail if there is no obvious mapping between the key codes. The hardware keycode can be taken from the ClutterKeyEvent.hardware_keycode member of ClutterKeyEvent.

Since 1.10

clutter_input_device_get_n_keys ()

guint               clutter_input_device_get_n_keys     (ClutterInputDevice *device);

Retrieves the number of keys registered for device.

Since 1.6

clutter_input_device_set_key ()

void                clutter_input_device_set_key        (ClutterInputDevice *device,
                                                         guint index_,
                                                         guint keyval,
                                                         ClutterModifierType modifiers);

Sets the keyval and modifiers at the given index_ for device.

Clutter will use the keyval and modifiers set when filling out an event coming from the same input device.

Since 1.6

clutter_input_device_get_key ()

gboolean            clutter_input_device_get_key        (ClutterInputDevice *device,
                                                         guint index_,
                                                         guint *keyval,
                                                         ClutterModifierType *modifiers);

Retrieves the key set using clutter_input_device_set_key()

Since 1.6

clutter_input_device_get_n_axes ()

guint               clutter_input_device_get_n_axes     (ClutterInputDevice *device);

Retrieves the number of axes available on device.

Since 1.6

clutter_input_device_get_axis ()

ClutterInputAxis    clutter_input_device_get_axis       (ClutterInputDevice *device,
                                                         guint index_);

Retrieves the type of axis on device at the given index.

Since 1.6

clutter_input_device_get_axis_value ()

gboolean            clutter_input_device_get_axis_value (ClutterInputDevice *device,
                                                         gdouble *axes,
                                                         ClutterInputAxis axis,
                                                         gdouble *value);

Extracts the value of the given axis of a ClutterInputDevice from an array of axis values.

An example of typical usage for this function is:

1
2
3
4
5
6
7

ClutterInputDevice *device = clutter_event_get_device (event);
gdouble *axes = clutter_event_get_axes (event, NULL);
gdouble pressure_value = 0;

clutter_input_device_get_axis_value (device, axes,
                                     CLUTTER_INPUT_AXIS_PRESSURE,
                                     &pressure_value);

Since 1.6

clutter_input_device_get_coords ()

gboolean            clutter_input_device_get_coords     (ClutterInputDevice *device,
                                                         ClutterEventSequence *sequence,
                                                         ClutterPoint *point);

Retrieves the latest coordinates of a pointer or touch point of device.

Since 1.12

clutter_input_device_get_device_coords ()

void                clutter_input_device_get_device_coords
                                                        (ClutterInputDevice *device,
                                                         gint *x,
                                                         gint *y);

Retrieves the latest coordinates of the pointer of device

Since 1.2

clutter_input_device_get_pointer_actor ()

ClutterActor *      clutter_input_device_get_pointer_actor
                                                        (ClutterInputDevice *device);

Retrieves the ClutterActor underneath the pointer of device

Since 1.2

clutter_input_device_get_pointer_stage ()

ClutterStage *      clutter_input_device_get_pointer_stage
                                                        (ClutterInputDevice *device);

Retrieves the ClutterStage underneath the pointer of device

Since 1.2

clutter_input_device_grab ()

void                clutter_input_device_grab           (ClutterInputDevice *device,
                                                         ClutterActor *actor);

Acquires a grab on actor for the given device.

Any event coming from device will be delivered to actor, bypassing the usual event delivery mechanism, until the grab is released by calling clutter_input_device_ungrab().

The grab is client-side: even if the windowing system used by the Clutter backend has the concept of "device grabs", Clutter will not use them.

Only ClutterInputDevice of types CLUTTER_POINTER_DEVICE and CLUTTER_KEYBOARD_DEVICE can hold a grab.

Since 1.10

clutter_input_device_ungrab ()

void                clutter_input_device_ungrab         (ClutterInputDevice *device);

Releases the grab on the device, if one is in place.

Since 1.10

clutter_input_device_get_grabbed_actor ()

ClutterActor *      clutter_input_device_get_grabbed_actor
                                                        (ClutterInputDevice *device);

Retrieves a pointer to the ClutterActor currently grabbing all the events coming from device.

Since 1.10

clutter_input_device_sequence_grab ()

void                clutter_input_device_sequence_grab  (ClutterInputDevice *device,
                                                         ClutterEventSequence *sequence,
                                                         ClutterActor *actor);

Acquires a grab on actor for the given device and the given touch sequence.

Any touch event coming from device and from sequence will be delivered to actor, bypassing the usual event delivery mechanism, until the grab is released by calling clutter_input_device_sequence_ungrab().

The grab is client-side: even if the windowing system used by the Clutter backend has the concept of "device grabs", Clutter will not use them.

Since 1.12

clutter_input_device_sequence_ungrab ()

void                clutter_input_device_sequence_ungrab
                                                        (ClutterInputDevice *device,
                                                         ClutterEventSequence *sequence);

Releases the grab on the device for the given sequence, if one is in place.

Since 1.12

clutter_input_device_sequence_get_grabbed_actor ()

ClutterActor *      clutter_input_device_sequence_get_grabbed_actor
                                                        (ClutterInputDevice *device,
                                                         ClutterEventSequence *sequence);

Retrieves a pointer to the ClutterActor currently grabbing the touch events coming from device given the sequence.

Since 1.12

clutter_input_device_update_from_event ()

void                clutter_input_device_update_from_event
                                                        (ClutterInputDevice *device,
                                                         ClutterEvent *event,
                                                         gboolean update_stage);

Forcibly updates the state of the device using a ClutterEvent

This function should never be used by applications: it is meant for integration with embedding toolkits, like clutter-gtk

Embedding toolkits that disable the event collection inside Clutter need to use this function to update the state of input devices depending on a ClutterEvent that they are going to submit to the event handling code in Clutter though clutter_do_event(). Since the input devices hold the state that is going to be used to fill in fields like the ClutterButtonEvent click count, or to emit synthesized events like CLUTTER_ENTER and CLUTTER_LEAVE, it is necessary for embedding toolkits to also be responsible of updating the input device state.

For instance, this might be the code to translate an embedding toolkit native motion notification into a Clutter ClutterMotionEvent and ask Clutter to process it:

1
2
3
4
5

ClutterEvent c_event;

translate_native_event_to_clutter (native_event, &c_event);

clutter_do_event (&c_event);

Before letting clutter_do_event() process the event, it is necessary to call clutter_input_device_update_from_event():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

ClutterEvent c_event;
ClutterDeviceManager *manager;
ClutterInputDevice *device;

translate_native_event_to_clutter (native_event, &c_event);

/* get the device manager */
manager = clutter_device_manager_get_default ();

/* use the default Core Pointer that Clutter
 * backends register by default
 */
device = clutter_device_manager_get_core_device (manager, %CLUTTER_POINTER_DEVICE);

/* update the state of the input device */
clutter_input_device_update_from_event (device, &c_event, FALSE);

clutter_do_event (&c_event);

The update_stage boolean argument should be used when the input device enters and leaves a ClutterStage; it will use the ClutterStage field of the passed event to update the stage associated to the input device.

Since 1.2

The "backend" property

  "backend"                  ClutterBackend*       : Read / Write / Construct Only

The ClutterBackend that created the device.

Since 1.6

The "device-manager" property

  "device-manager"           ClutterDeviceManager*  : Read / Write / Construct Only

The ClutterDeviceManager instance which owns the device

Since 1.6

The "device-mode" property

  "device-mode"              ClutterInputMode      : Read / Write / Construct Only

The mode of the device.

Default value: CLUTTER_INPUT_MODE_FLOATING

The "device-type" property

  "device-type"              ClutterInputDeviceType  : Read / Write / Construct Only

The type of the device

Default value: CLUTTER_POINTER_DEVICE

Since 1.2

The "enabled" property

  "enabled"                  gboolean              : Read / Write

Whether the device is enabled.

A device with the "device-mode" property set to CLUTTER_INPUT_MODE_MASTER cannot be disabled.

A device must be enabled in order to receive events from it.

Default value: FALSE

Since 1.6

The "has-cursor" property

  "has-cursor"               gboolean              : Read / Write / Construct Only

Whether the device has an on screen cursor following its movement.

Default value: FALSE

Since 1.6

The "id" property

  "id"                       gint                  : Read / Write / Construct Only

The unique identifier of the device

Allowed values: >= G_MAXULONG

Default value: 0

Since 1.2

The "n-axes" property

  "n-axes"                   guint                 : Read

The number of axes of the device.

Default value: 0

Since 1.6

The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

The name of the device

Default value: NULL

Since 1.2