Clutter Reference Manual: ClutterInputDevice

## ClutterInputDevice ClutterInputDevice — An input device managed by Clutter |

## Synopsis

    enum                ClutterInputDeviceType;
    enum                ClutterInputAxis;
    enum                ClutterInputMode;
                        ClutterInputDevice;
    gint                clutter_input_device_get_device_id  (ClutterInputDevice *device);
    ClutterInputDeviceType clutter_input_device_get_device_type
                                                            (ClutterInputDevice *device);
    const gchar *       clutter_input_device_get_device_name
                                                            (ClutterInputDevice *device);
    ClutterInputMode    clutter_input_device_get_device_mode
                                                            (ClutterInputDevice *device);
    gboolean            clutter_input_device_get_has_cursor (ClutterInputDevice *device);
    void                clutter_input_device_set_enabled    (ClutterInputDevice *device,
                                                             gboolean enabled);
    gboolean            clutter_input_device_get_enabled    (ClutterInputDevice *device);
    ClutterInputDevice * clutter_input_device_get_associated_device
                                                            (ClutterInputDevice *device);
    GList *             clutter_input_device_get_slave_devices
                                                            (ClutterInputDevice *device);
    ClutterModifierType clutter_input_device_get_modifier_state
                                                            (ClutterInputDevice *device);
    gboolean            clutter_input_device_keycode_to_evdev
                                                            (ClutterInputDevice *device,
                                                             guint hardware_keycode,
                                                             guint *evdev_keycode);

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

    guint               clutter_input_device_get_n_axes     (ClutterInputDevice *device);
    ClutterInputAxis    clutter_input_device_get_axis       (ClutterInputDevice *device,
                                                             guint index_);
    gboolean            clutter_input_device_get_axis_value (ClutterInputDevice *device,
                                                             gdouble *axes,
                                                             ClutterInputAxis axis,
                                                             gdouble *value);

    gboolean            clutter_input_device_get_coords     (ClutterInputDevice *device,
                                                             ClutterEventSequence *sequence,
                                                             ClutterPoint *point);
    void                clutter_input_device_get_device_coords
                                                            (ClutterInputDevice *device,
                                                             gint *x,
                                                             gint *y);
    ClutterActor *      clutter_input_device_get_pointer_actor
                                                            (ClutterInputDevice *device);
    ClutterStage *      clutter_input_device_get_pointer_stage
                                                            (ClutterInputDevice *device);

    void                clutter_input_device_grab           (ClutterInputDevice *device,
                                                             ClutterActor *actor);
    void                clutter_input_device_ungrab         (ClutterInputDevice *device);
    ClutterActor *      clutter_input_device_get_grabbed_actor
                                                            (ClutterInputDevice *device);
    void                clutter_input_device_sequence_grab  (ClutterInputDevice *device,
                                                             ClutterEventSequence *sequence,
                                                             ClutterActor *actor);
    void                clutter_input_device_sequence_ungrab
                                                            (ClutterInputDevice *device,
                                                             ClutterEventSequence *sequence);
    ClutterActor *      clutter_input_device_sequence_get_grabbed_actor
                                                            (ClutterInputDevice *device,
                                                             ClutterEventSequence *sequence);

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

## Object Hierarchy

      GObject
       +----ClutterInputDevice

## Properties

      "backend"                  ClutterBackend*       : Read / Write / Construct Only
      "device-manager"           ClutterDeviceManager*  : Read / Write / Construct Only
      "device-mode"              ClutterInputMode      : Read / Write / Construct Only
      "device-type"              ClutterInputDeviceType  : Read / Write / Construct Only
      "enabled"                  gboolean              : Read / Write
      "has-cursor"               gboolean              : Read / Write / Construct Only
      "id"                       gint                  : Read / Write / Construct Only
      "n-axes"                   guint                 : Read
      "name"                     gchar*                : Read / Write / Construct Only

## Description

ClutterInputDevice represents an input device known to Clutter.

The ClutterInputDevice class holds the state of the device, but its contents are usually defined by the Clutter backend in use.

## Details

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

`CLUTTER_POINTER_DEVICE` | A pointer device
`CLUTTER_KEYBOARD_DEVICE` | A keyboard device
`CLUTTER_EXTENSION_DEVICE` | A generic extension device
`CLUTTER_JOYSTICK_DEVICE` | A joystick device
`CLUTTER_TABLET_DEVICE` | A tablet device
`CLUTTER_TOUCHPAD_DEVICE` | A touchpad device
`CLUTTER_TOUCHSCREEN_DEVICE` | A touch screen device
`CLUTTER_PEN_DEVICE` | A pen device
`CLUTTER_ERASER_DEVICE` | An eraser device
`CLUTTER_CURSOR_DEVICE` | A cursor device
`CLUTTER_N_DEVICE_TYPES` | The number of device types

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

`CLUTTER_INPUT_AXIS_IGNORE` | Unused axis
`CLUTTER_INPUT_AXIS_X` | The position on the X axis
`CLUTTER_INPUT_AXIS_Y` | The position of the Y axis
`CLUTTER_INPUT_AXIS_PRESSURE` | The pressure information
`CLUTTER_INPUT_AXIS_XTILT` | The tilt on the X axis
`CLUTTER_INPUT_AXIS_YTILT` | The tile on the Y axis
`CLUTTER_INPUT_AXIS_WHEEL` | A wheel
`CLUTTER_INPUT_AXIS_DISTANCE` | Distance (Since 1.12)
`CLUTTER_INPUT_AXIS_LAST` | Last value of the enumeration; this value is useful when iterating over the enumeration values (Since 1.12)

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.

`CLUTTER_INPUT_MODE_MASTER` | A master, virtual device
`CLUTTER_INPUT_MODE_SLAVE` | A slave, physical device, attached to a master device
`CLUTTER_INPUT_MODE_FLOATING` | A slave, physical device, not attached to a master device

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`

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

    const gchar *       clutter_input_device_get_device_name
                                                            (ClutterInputDevice *device);

Retrieves the name of the `device`

`device` : | a ClutterInputDevice
Returns : | the name of the device, or `NULL`. The returned string is owned by the ClutterInputDevice and should never be modified or freed

Since 1.2

### clutter_input_device_get_device_mode ()

    ClutterInputMode    clutter_input_device_get_device_mode
                                                            (ClutterInputDevice *device);

Retrieves the ClutterInputMode of `device`.

`device` : | a ClutterInputDevice
Returns : | the device mode

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.

`device` : | a ClutterInputDevice
Returns : | `TRUE` if the device has a cursor

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.

`device` : | a ClutterInputDevice
`enabled` : | `TRUE` to enable the `device`

Since 1.6

### clutter_input_device_get_enabled ()

    gboolean            clutter_input_device_get_enabled    (ClutterInputDevice *device);

Retrieves whether `device` is enabled.

`device` : | a ClutterInputDevice
Returns : | `TRUE` if the 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`.

`device` : | a ClutterInputDevice
Returns : | a ClutterInputDevice, or `NULL`. [transfer none]

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

`device` : | a ClutterInputDevice
Returns : | a list of ClutterInputDevice, or `NULL`. The contents of the list are owned by the device. Use `g_list_free()` when done. [transfer container][element-type Clutter.InputDevice]

Since 1.6

### clutter_input_device_get_modifier_state ()

    ClutterModifierType clutter_input_device_get_modifier_state
                                                            (ClutterInputDevice *device);

Retrieves the current modifiers state of the device, as seen by the last event Clutter processed.

`device` : | a ClutterInputDevice
Returns : | the last known modifier state

Since 1.16

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

`device` : | A ClutterInputDevice
`hardware_keycode` : | The hardware keycode from a ClutterKeyEvent
`evdev_keycode` : | The return location for the evdev keycode
Returns : | `TRUE` if the conversion succeeded, `FALSE` otherwise.

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

`device` : | a ClutterInputDevice
Returns : | the number of registered keys

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.

`device` : | a ClutterInputDevice
`index_` : | the index of the key
`keyval` : | the keyval
`modifiers` : | a bitmask of modifiers

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

`device` : | a ClutterInputDevice
`index_` : | the index of the key
`keyval` : | return location for the keyval at `index_`. [out]
`modifiers` : | return location for the modifiers at `index_`. [out]
Returns : | `TRUE` if a key was set at the given index

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

`device` : | a ClutterInputDevice
Returns : | the number of axes on the 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.

`device` : | a ClutterInputDevice
`index_` : | the index of the axis
Returns : | the axis type

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);

`device` : | a ClutterInputDevice
`axes` : | an array of axes values, typically coming from `clutter_event_get_axes()`. [array]
`axis` : | the axis to extract
`value` : | return location for the axis value. [out]
Returns : | `TRUE` if the value was set, and `FALSE` otherwise

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

`device` : | a ClutterInputDevice
`sequence` : | a ClutterEventSequence, or `NULL` if the device is not touch-based. [allow-none]
`point` : | return location for the pointer or touch point. [out caller-allocates]
Returns : | `FALSE` if the device's sequence hasn't been found, and `TRUE` otherwise.

Since 1.12

### clutter_input_device_get_device_coords ()

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

### Warning

`clutter_input_device_get_device_coords` has been deprecated since version 1.12 and should not be used in newly-written code. Use `clutter_input_device_get_coords()` instead.

Retrieves the latest coordinates of the pointer of `device`

`device` : | a ClutterInputDevice of type `CLUTTER_POINTER_DEVICE`
`x` : | return location for the X coordinate. [out]
`y` : | return location for the Y coordinate. [out]

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`

`device` : | a ClutterInputDevice of type `CLUTTER_POINTER_DEVICE`
Returns : | a pointer to the ClutterActor or `NULL`. [transfer none]

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`

`device` : | a ClutterInputDevice of type `CLUTTER_POINTER_DEVICE`
Returns : | a pointer to the ClutterStage or `NULL`. [transfer none]

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.

`device` : | a ClutterInputDevice
`actor` : | a ClutterActor

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.

`device` : | a ClutterInputDevice

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

`device` : | a ClutterInputDevice
Returns : | a ClutterActor, or `NULL`. [transfer none]

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.

`device` : | a ClutterInputDevice
`sequence` : | a ClutterEventSequence
`actor` : | a ClutterActor

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.

`device` : | a ClutterInputDevice
`sequence` : | a ClutterEventSequence

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

`device` : | a ClutterInputDevice
`sequence` : | a ClutterEventSequence
Returns : | a ClutterActor, or `NULL`. [transfer none]

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.

`device` : | a ClutterInputDevice
`event` : | a ClutterEvent
`update_stage` : | whether to update the ClutterStage of the `device` using the stage of the event

Since 1.2

## Property Details

### 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: >= -1

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