## ClutterInputDevice

ClutterInputDevice — An input device managed by Clutter

## Synopsis

    enum                ClutterInputDeviceType;
                        ClutterInputDevice;
    struct              ClutterInputDeviceClass;
    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);
    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

      "device-type"              ClutterInputDeviceType  : Read / Write / Construct Only
      "id"                       gint                  : Read / Write / Construct Only
      "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_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

### ClutterInputDevice

    typedef struct _ClutterInputDevice ClutterInputDevice;

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

### struct ClutterInputDeviceClass

    struct ClutterInputDeviceClass {
    };

The ClutterInputDeviceClass structure contains only private data and should not be accessed directly

Since 1.2

### 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_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 `"device-type"` property

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

The type of the device

Default value: CLUTTER_POINTER_DEVICE

Since 1.2

### 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 `"name"` property

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

The name of the device

Default value: NULL

Since 1.2