ClutterInputDevice: Clutter Reference Manual

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

## Functions

gint | clutter_input_device_get_device_id ()
ClutterInputDeviceType | clutter_input_device_get_device_type ()
const gchar * | clutter_input_device_get_device_name ()
ClutterInputMode | clutter_input_device_get_device_mode ()
gboolean | clutter_input_device_get_has_cursor ()
void | clutter_input_device_set_enabled ()
gboolean | clutter_input_device_get_enabled ()
ClutterInputDevice * | clutter_input_device_get_associated_device ()
GList * | clutter_input_device_get_slave_devices ()
ClutterModifierType | clutter_input_device_get_modifier_state ()
gboolean | clutter_input_device_keycode_to_evdev ()
const gchar * | clutter_input_device_get_vendor_id ()
const gchar * | clutter_input_device_get_product_id ()
guint | clutter_input_device_get_n_keys ()
void | clutter_input_device_set_key ()
gboolean | clutter_input_device_get_key ()
guint | clutter_input_device_get_n_axes ()
ClutterInputAxis | clutter_input_device_get_axis ()
gboolean | clutter_input_device_get_axis_value ()
gboolean | clutter_input_device_get_coords ()
void | clutter_input_device_get_device_coords ()
ClutterActor * | clutter_input_device_get_pointer_actor ()
ClutterStage * | clutter_input_device_get_pointer_stage ()
void | clutter_input_device_grab ()
void | clutter_input_device_ungrab ()
ClutterActor * | clutter_input_device_get_grabbed_actor ()
void | clutter_input_device_sequence_grab ()
void | clutter_input_device_sequence_ungrab ()
ClutterActor * | clutter_input_device_sequence_get_grabbed_actor ()
void | clutter_input_device_update_from_event ()

## Properties

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

## Types and Values

enum | ClutterInputDeviceType
enum | ClutterInputAxis
enum | ClutterInputMode
| ClutterInputDevice

## Object Hierarchy

        GObject
        ╰── ClutterInputDevice

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

## Functions

### clutter_input_device_get_device_id ()

    gint
    clutter_input_device_get_device_id (ClutterInputDevice *device);

Retrieves the unique identifier of `device`

#### Parameters

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`

#### Parameters

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`

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

    const gchar *
    clutter_input_device_get_vendor_id (ClutterInputDevice *device);

Gets the vendor ID of this device.

#### Parameters

device | a slave ClutterInputDevice |

#### Returns

the vendor ID

Since: 1.22

### clutter_input_device_get_product_id ()

    const gchar *
    clutter_input_device_get_product_id (ClutterInputDevice *device);

Gets the product ID of this device.

#### Parameters

device | a slave ClutterInputDevice |

#### Returns

the product ID

Since: 1.22

### clutter_input_device_get_n_keys ()

    guint
    clutter_input_device_get_n_keys (ClutterInputDevice *device);

Retrieves the number of keys registered for `device` .

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

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

#### Parameters

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`

#### Parameters

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`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

## Types and Values

### enum ClutterInputDeviceType

The types of input devices available.

The ClutterInputDeviceType enumeration can be extended at later date; not every platform supports every input device type.

#### Members

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

The type of axes Clutter recognizes on a ClutterInputDevice

#### Members

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

The mode for input devices available.

#### Members

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.

## Property Details

### The `“backend”` property

      “backend”                  ClutterBackend *

The ClutterBackend that created the device.

Flags: Read / Write / Construct Only

Since: 1.6

### The `“device-manager”` property

      “device-manager”           ClutterDeviceManager *

The ClutterDeviceManager instance which owns the device

Flags: Read / Write / Construct Only

Since: 1.6

### The `“device-mode”` property

      “device-mode”              ClutterInputMode

The mode of the device.

Flags: Read / Write / Construct Only

Default value: CLUTTER_INPUT_MODE_FLOATING

### The `“device-type”` property

      “device-type”              ClutterInputDeviceType

The type of the device

Flags: Read / Write / Construct Only

Default value: CLUTTER_POINTER_DEVICE

Since: 1.2

### The `“enabled”` property

      “enabled”                  gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 1.6

### The `“has-cursor”` property

      “has-cursor”               gboolean

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

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 1.6

### The `“id”` property

      “id”                       gint

The unique identifier of the device

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: 0

Since: 1.2

### The `“n-axes”` property

      “n-axes”                   guint

The number of axes of the device.

Flags: Read

Default value: 0

Since: 1.6

### The `“name”` property

      “name”                     gchar *

The name of the device

Flags: Read / Write / Construct Only

Default value: NULL

Since: 1.2

### The `“product-id”` property

      “product-id”               gchar *

Product ID of this device.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 1.22

### The `“vendor-id”` property

      “vendor-id”                gchar *

Vendor ID of this device.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 1.22