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

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

    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_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
    } 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

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_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_device_coords ()

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

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