Clutter.InputDevice

g Clutter.InputDevice Clutter.InputDevice GObject.Object GObject.Object GObject.Object->Clutter.InputDevice

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
  get_associated_device ()
  get_axis (index_)
  get_axis_value (axes, axis)
  get_coords (sequence)
  get_device_coords ()
  get_device_id ()
  get_device_mode ()
  get_device_name ()
  get_device_type ()
  get_enabled ()
  get_grabbed_actor ()
  get_has_cursor ()
  get_key (index_)
  get_modifier_state ()
  get_n_axes ()
  get_n_keys ()
  get_pointer_actor ()
  get_pointer_stage ()
  get_product_id ()
  get_slave_devices ()
  get_vendor_id ()
  grab (actor)
  keycode_to_evdev (hardware_keycode, evdev_keycode)
  sequence_get_grabbed_actor (sequence)
  sequence_grab (sequence, actor)
  sequence_ungrab (sequence)
  set_enabled (enabled)
  set_key (index_, keyval, modifiers)
  ungrab ()
  update_from_event (event, update_stage)

Virtual Methods

Inherited:GObject.Object (7)

Properties

Name Type Flags Short Description
backend Clutter.Backend r/w/co The backend instance
device-manager Clutter.DeviceManager r/w/co The device manager instance
device-mode Clutter.InputMode r/w/co The mode of the device
device-type Clutter.InputDeviceType r/w/co The type of the device
enabled bool r/w Whether the device is enabled
has-cursor bool r/w/co Whether the device has a cursor
id int r/w/co Unique identifier of the device
n-axes int r The number of axes on the device
name str r/w/co The name of the device
product-id str r/w/co Product ID
vendor-id str r/w/co Vendor ID

Signals

Inherited:GObject.Object (1)

Fields

Inherited:GObject.Object (1)

Class Details

class Clutter.InputDevice(**kwargs)
Bases:GObject.Object
Abstract:No
Structure:Clutter.InputDeviceClass

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

get_associated_device()
Returns:a Clutter.InputDevice, or None
Return type:Clutter.InputDevice

Retrieves a pointer to the Clutter.InputDevice that has been associated to self.

If the Clutter.InputDevice :device-mode property of self is set to Clutter.InputMode.MASTER, this function will return None.

New in version 1.6.

get_axis(index_)
Parameters:index (int) – the index of the axis
Returns:the axis type
Return type:Clutter.InputAxis

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

New in version 1.6.

get_axis_value(axes, axis)
Parameters:
Returns:

True if the value was set, and False otherwise

value:return location for the axis value

Return type:

(bool, value: float)

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

An example of typical usage for this function is:

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

New in version 1.6.

get_coords(sequence)
Parameters:sequence (Clutter.EventSequence or None) – a Clutter.EventSequence, or None if the device is not touch-based
Returns:False if the device’s sequence hasn’t been found, and True otherwise.
point:return location for the pointer or touch point
Return type:(bool, point: Clutter.Point)

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

New in version 1.12.

get_device_coords()
Returns:
x:return location for the X coordinate
y:return location for the Y coordinate
Return type:(x: int, y: int)

Retrieves the latest coordinates of the pointer of self

New in version 1.2.

Deprecated since version 1.12: Use Clutter.InputDevice.get_coords() instead.

get_device_id()
Returns:the identifier of the device
Return type:int

Retrieves the unique identifier of self

New in version 1.0.

get_device_mode()
Returns:the device mode
Return type:Clutter.InputMode

Retrieves the Clutter.InputMode of self.

New in version 1.6.

get_device_name()
Returns:the name of the device, or None. The returned string is owned by the Clutter.InputDevice and should never be modified or freed
Return type:str

Retrieves the name of the self

New in version 1.2.

get_device_type()
Returns:the type of the device
Return type:Clutter.InputDeviceType

Retrieves the type of self

New in version 1.0.

get_enabled()
Returns:True if the device is enabled
Return type:bool

Retrieves whether self is enabled.

New in version 1.6.

get_grabbed_actor()
Returns:a Clutter.Actor, or None
Return type:Clutter.Actor

Retrieves a pointer to the Clutter.Actor currently grabbing all the events coming from self.

New in version 1.10.

get_has_cursor()
Returns:True if the device has a cursor
Return type:bool

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

New in version 1.6.

get_key(index_)
Parameters:index (int) – the index of the key
Returns:True if a key was set at the given index
keyval:return location for the keyval at index_
modifiers:return location for the modifiers at index_
Return type:(bool, keyval: int, modifiers: Clutter.ModifierType)

Retrieves the key set using Clutter.InputDevice.set_key()

New in version 1.6.

get_modifier_state()
Returns:the last known modifier state
Return type:Clutter.ModifierType

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

New in version 1.16.

get_n_axes()
Returns:the number of axes on the device
Return type:int

Retrieves the number of axes available on self.

New in version 1.6.

get_n_keys()
Returns:the number of registered keys
Return type:int

Retrieves the number of keys registered for self.

New in version 1.6.

get_pointer_actor()
Returns:a pointer to the Clutter.Actor or None
Return type:Clutter.Actor

Retrieves the Clutter.Actor underneath the pointer of self

New in version 1.2.

get_pointer_stage()
Returns:a pointer to the Clutter.Stage or None
Return type:Clutter.Stage

Retrieves the Clutter.Stage underneath the pointer of self

New in version 1.2.

get_product_id()
Returns:the product ID
Return type:str

Gets the product ID of this device.

New in version 1.22.

get_slave_devices()
Returns:a list of Clutter.InputDevice, or None. The contents of the list are owned by the device. Use g_list_free() when done
Return type:[Clutter.InputDevice]

Retrieves the slave devices attached to self.

New in version 1.6.

get_vendor_id()
Returns:the vendor ID
Return type:str

Gets the vendor ID of this device.

New in version 1.22.

grab(actor)
Parameters:actor (Clutter.Actor) – a Clutter.Actor

Acquires a grab on actor for the given self.

Any event coming from self will be delivered to actor, bypassing the usual event delivery mechanism, until the grab is released by calling Clutter.InputDevice.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 Clutter.InputDevice of types Clutter.InputDeviceType.POINTER_DEVICE and Clutter.InputDeviceType.KEYBOARD_DEVICE can hold a grab.

New in version 1.10.

keycode_to_evdev(hardware_keycode, evdev_keycode)
Parameters:
  • hardware_keycode (int) – The hardware keycode from a Clutter.KeyEvent
  • evdev_keycode (int) – The return location for the evdev keycode
Returns:

True if the conversion succeeded, False otherwise.

Return type:

bool

Translates a hardware keycode from a Clutter.KeyEvent 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 Clutter.KeyEvent.hardware_keycode member of Clutter.KeyEvent.

New in version 1.10.

sequence_get_grabbed_actor(sequence)
Parameters:sequence (Clutter.EventSequence) – a Clutter.EventSequence
Returns:a Clutter.Actor, or None
Return type:Clutter.Actor

Retrieves a pointer to the Clutter.Actor currently grabbing the touch events coming from self given the sequence.

New in version 1.12.

sequence_grab(sequence, actor)
Parameters:

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

Any touch event coming from self and from sequence will be delivered to actor, bypassing the usual event delivery mechanism, until the grab is released by calling Clutter.InputDevice.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.

New in version 1.12.

sequence_ungrab(sequence)
Parameters:sequence (Clutter.EventSequence) – a Clutter.EventSequence

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

New in version 1.12.

set_enabled(enabled)
Parameters:enabled (bool) – True to enable the self

Enables or disables a Clutter.InputDevice.

Only devices with a Clutter.InputDevice :device-mode property set to Clutter.InputMode.SLAVE or Clutter.InputMode.FLOATING can be disabled.

New in version 1.6.

set_key(index_, keyval, modifiers)
Parameters:

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

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

New in version 1.6.

ungrab()

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

New in version 1.10.

update_from_event(event, update_stage)
Parameters:

Forcibly updates the state of the self using a Clutter.Event

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 Clutter.Event 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 Clutter.ButtonEvent click count, or to emit synthesized events like Clutter.EventType.ENTER and Clutter.EventType.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 Clutter.MotionEvent and ask Clutter to process it:

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.InputDevice.update_from_event():

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 Clutter.Stage; it will use the Clutter.Stage field of the passed event to update the stage associated to the input device.

New in version 1.2.

Property Details

Clutter.InputDevice.props.backend
Name:backend
Type:Clutter.Backend
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The Clutter.Backend that created the device.

New in version 1.6.

Clutter.InputDevice.props.device_manager
Name:device-manager
Type:Clutter.DeviceManager
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The Clutter.DeviceManager instance which owns the device

New in version 1.6.

Clutter.InputDevice.props.device_mode
Name:device-mode
Type:Clutter.InputMode
Default Value:Clutter.InputMode.FLOATING
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The mode of the device

Clutter.InputDevice.props.device_type
Name:device-type
Type:Clutter.InputDeviceType
Default Value:Clutter.InputDeviceType.POINTER_DEVICE
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The type of the device

New in version 1.2.

Clutter.InputDevice.props.enabled
Name:enabled
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

Whether the device is enabled.

A device with the Clutter.InputDevice :device-mode property set to Clutter.InputMode.MASTER cannot be disabled.

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

New in version 1.6.

Clutter.InputDevice.props.has_cursor
Name:has-cursor
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

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

New in version 1.6.

Clutter.InputDevice.props.id
Name:id
Type:int
Default Value:0
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The unique identifier of the device

New in version 1.2.

Clutter.InputDevice.props.n_axes
Name:n-axes
Type:int
Default Value:0
Flags:READABLE

The number of axes of the device.

New in version 1.6.

Clutter.InputDevice.props.name
Name:name
Type:str
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The name of the device

New in version 1.2.

Clutter.InputDevice.props.product_id
Name:product-id
Type:str
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

Product ID of this device.

New in version 1.22.

Clutter.InputDevice.props.vendor_id
Name:vendor-id
Type:str
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

Vendor ID of this device.

New in version 1.22.