Gdk.Device¶

Subclasses:	None

Methods¶

Inherited:	GObject.Object (37)
Structs:	GObject.ObjectClass (5)

class	`grab_info_libgtk_only` (display, device)
	`get_associated_device` ()
	`get_axes` ()
	`get_axis_use` (index_)
	`get_device_type` ()
	`get_display` ()
	`get_has_cursor` ()
	`get_key` (index_)
	`get_last_event_window` ()
	`get_mode` ()
	`get_n_axes` ()
	`get_n_keys` ()
	`get_name` ()
	`get_position` ()
	`get_position_double` ()
	`get_product_id` ()
	`get_seat` ()
	`get_source` ()
	`get_vendor_id` ()
	`get_window_at_position` ()
	`get_window_at_position_double` ()
	`grab` (window, grab_ownership, owner_events, event_mask, cursor, time_)
	`list_axes` ()
	`list_slave_devices` ()
	`set_axis_use` (index_, use)
	`set_key` (index_, keyval, modifiers)
	`set_mode` (mode)
	`ungrab` (time_)
	`warp` (screen, x, y)

Virtual Methods¶

Inherited:	GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`associated-device`	`Gdk.Device`	r	Associated pointer or keyboard with this device
`axes`	`Gdk.AxisFlags`	r	Axes
`device-manager`	`Gdk.DeviceManager`	r/w/co	Device manager which the device belongs to
`display`	`Gdk.Display`	r/w/co	Display which the device belongs to
`has-cursor`	`bool`	r/w/co	Whether there is a visible cursor following device motion
`input-mode`	`Gdk.InputMode`	r/w/en	Input mode for the device
`input-source`	`Gdk.InputSource`	r/w/co/en	Source type for the device
`n-axes`	`int`	r	Number of axes in the device
`name`	`str`	r/w/co	Device name
`num-touches`	`int`	r/w/co	Number of concurrent touches
`product-id`	`str`	r/w/co	Product ID
`seat`	`Gdk.Seat`	r/w	Seat
`tool`	`Gdk.DeviceTool`	r	The tool that is currently used with this device
`type`	`Gdk.DeviceType`	r/w/co	Device role in the device manager
`vendor-id`	`str`	r/w/co	Vendor ID

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`changed`	The `::changed` signal is emitted either when the `Gdk.Device` has changed the number of either axes or keys.
`tool-changed`	The `::tool-changed` signal is emitted on pen/eraser `Gdk.Devices` whenever tools enter or leave proximity.

Fields¶

Inherited:	GObject.Object (1)

Class Details¶

class Gdk.Device(**kwargs)¶

Bases:	`GObject.Object`
Abstract:	Yes

The Gdk.Device object represents a single input device, such as a keyboard, a mouse, a touchpad, etc.

See the Gdk.DeviceManager documentation for more information about the various kinds of master and slave devices, and their relationships.

classmethod grab_info_libgtk_only(display, device)[source]¶

Parameters:

display (Gdk.Display) – the display for which to get the grab information
device (Gdk.Device) – device to get the grab information from

Returns:

True if this application currently has the keyboard grabbed.

grab_window:	location to store current grab window
owner_events:	location to store boolean indicating whether the owner_events flag to `Gdk.keyboard_grab`() or `Gdk.pointer_grab`() was `True`.

Return type:

(bool, grab_window: Gdk.Window, owner_events: bool)

Determines information about the current keyboard grab. This is not public API and must not be used by applications.

Deprecated since version 3.16: The symbol was never meant to be used outside of GTK+

get_associated_device()[source]¶

Returns:	The associated device, or `None`
Return type:	`Gdk.Device` or `None`

Returns the associated device to self, if self is of type Gdk.DeviceType.MASTER, it will return the paired pointer or keyboard.

If self is of type Gdk.DeviceType.SLAVE, it will return the master device to which self is attached to.

If self is of type Gdk.DeviceType.FLOATING, None will be returned, as there is no associated device.

New in version 3.0.

get_axes()[source]¶

Return type:	`Gdk.AxisFlags`

Returns the axes currently available on the device.

New in version 3.22.

get_axis_use(index_)[source]¶

Parameters:	index (`int`) – the index of the axis.
Returns:	a `Gdk.AxisUse` specifying how the axis is used.
Return type:	`Gdk.AxisUse`

Returns the axis use for index_.

New in version 2.20.

get_device_type()[source]¶

Returns:	the `Gdk.DeviceType` for self.
Return type:	`Gdk.DeviceType`

Returns the device type for self.

New in version 3.0.

get_display()[source]¶

Returns:	a `Gdk.Display`. This memory is owned by GTK+, and must not be freed or unreffed.
Return type:	`Gdk.Display`

Returns the Gdk.Display to which self pertains.

New in version 3.0.

get_has_cursor()[source]¶

Returns:	`True` if the pointer follows device motion
Return type:	`bool`

Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don’t have a pointer.

New in version 2.20.

get_key(index_)[source]¶

Parameters: index (int) – the index of the macro button to get.

Returns:

True if keyval is set for index.

keyval:	return value for the keyval.
modifiers:	return value for modifiers.

Return type: (bool, keyval: int, modifiers: Gdk.ModifierType)

If index_ has a valid keyval, this function will return True and fill in keyval and modifiers with the keyval settings.

New in version 2.20.

get_last_event_window()[source]¶

Returns:	the last window the device
Return type:	`Gdk.Window` or `None`

Gets information about which window the given pointer device is in, based on events that have been received so far from the display server. If another application has a pointer grab, or this application has a grab with owner_events = False, None may be returned even if the pointer is physically over one of this application’s windows.

New in version 3.12.

get_mode()[source]¶

Returns:	a `Gdk.InputSource`
Return type:	`Gdk.InputMode`

Determines the mode of the device.

New in version 2.20.

get_n_axes()[source]¶

Returns:	the number of axes.
Return type:	`int`

Returns the number of axes the device currently has.

New in version 3.0.

get_n_keys()[source]¶

Returns:	the number of keys.
Return type:	`int`

Returns the number of keys the device currently has.

New in version 2.24.

get_name()[source]¶

Returns:	a name
Return type:	`str`

Determines the name of the device.

New in version 2.20.

get_position()[source]¶

Returns:

screen:	location to store the `Gdk.Screen` the self is on, or `None`.
x:	location to store root window X coordinate of self, or `None`.
y:	location to store root window Y coordinate of self, or `None`.

Return type: (screen: Gdk.Screen, x: int, y: int)

Gets the current location of self. As a slave device coordinates are those of its master pointer, This function may not be called on devices of type Gdk.DeviceType.SLAVE, unless there is an ongoing grab on them, see Gdk.Device.grab().

New in version 3.0.

get_position_double()[source]¶

Returns:

screen:	location to store the `Gdk.Screen` the self is on, or `None`.
x:	location to store root window X coordinate of self, or `None`.
y:	location to store root window Y coordinate of self, or `None`.

Return type: (screen: Gdk.Screen, x: float, y: float)

Gets the current location of self in double precision. As a slave device’s coordinates are those of its master pointer, this function may not be called on devices of type Gdk.DeviceType.SLAVE, unless there is an ongoing grab on them. See Gdk.Device.grab().

New in version 3.10.

get_product_id()[source]¶

Returns:	the product ID, or `None`
Return type:	`str` or `None`

Returns the product ID of this device, or None if this information couldn’t be obtained. This ID is retrieved from the device, and is thus constant for it. See Gdk.Device.get_vendor_id() for more information.

New in version 3.16.

get_seat()[source]¶

Returns:	A `Gdk.Seat`. This memory is owned by GTK+ and must not be freed.
Return type:	`Gdk.Seat`

Returns the Gdk.Seat the device belongs to.

New in version 3.20.

get_source()[source]¶

Returns:	a `Gdk.InputSource`
Return type:	`Gdk.InputSource`

Determines the type of the device.

New in version 2.20.

get_vendor_id()[source]¶

Returns:	the vendor ID, or `None`
Return type:	`str` or `None`

Returns the vendor ID of this device, or None if this information couldn’t be obtained. This ID is retrieved from the device, and is thus constant for it.

This function, together with Gdk.Device.get_product_id(), can be used to eg. compose Gio.Settings paths to store settings for this device.

static GSettings *
get_device_settings (GdkDevice *device)
{
  const gchar *vendor, *product;
  GSettings *settings;
  GdkDevice *device;
  gchar *path;

  vendor = gdk_device_get_vendor_id (device);
  product = gdk_device_get_product_id (device);

  path = g_strdup_printf ("/org/example/app/devices/%s:%s/", vendor, product);
  settings = g_settings_new_with_path (DEVICE_SCHEMA, path);
  g_free (path);

  return settings;
}

New in version 3.16.

get_window_at_position()[source]¶

Returns:

the Gdk.Window under the device position, or None.

win_x:	return location for the X coordinate of the device location, relative to the window origin, or `None`.
win_y:	return location for the Y coordinate of the device location, relative to the window origin, or `None`.

Return type: (Gdk.Window or None, win_x: int, win_y: int)

Obtains the window underneath self, returning the location of the device in win_x and win_y. Returns None if the window tree under self is not known to GDK (for example, belongs to another application).

As a slave device coordinates are those of its master pointer, This function may not be called on devices of type Gdk.DeviceType.SLAVE, unless there is an ongoing grab on them, see Gdk.Device.grab().

New in version 3.0.

get_window_at_position_double()[source]¶

Returns:

the Gdk.Window under the device position, or None.

win_x:	return location for the X coordinate of the device location, relative to the window origin, or `None`.
win_y:	return location for the Y coordinate of the device location, relative to the window origin, or `None`.

Return type: (Gdk.Window or None, win_x: float, win_y: float)

Obtains the window underneath self, returning the location of the device in win_x and win_y in double precision. Returns None if the window tree under self is not known to GDK (for example, belongs to another application).

As a slave device coordinates are those of its master pointer, This function may not be called on devices of type Gdk.DeviceType.SLAVE, unless there is an ongoing grab on them, see Gdk.Device.grab().

New in version 3.0.

grab(window, grab_ownership, owner_events, event_mask, cursor, time_)[source]¶

Parameters:	window (`Gdk.Window`) – the `Gdk.Window` which will own the grab (the grab window) grab_ownership (`Gdk.GrabOwnership`) – specifies the grab ownership. owner_events (`bool`) – if `False` then all device events are reported with respect to window and are only reported if selected by event_mask. If `True` then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to window and only if selected by event_mask. In either mode, unreported events are discarded. event_mask (`Gdk.EventMask`) – specifies the event mask, which is used in accordance with owner_events. cursor (`Gdk.Cursor` or `None`) – the cursor to display while the grab is active if the device is a pointer. If this is `None` then the normal cursors are used for window and its descendants, and the cursor for window is used elsewhere. time (`int`) – the timestamp of the event which led to this pointer grab. This usually comes from the `Gdk.Event` struct, though `Gdk.CURRENT_TIME` can be used if the time isn’t known.
Returns:	`Gdk.GrabStatus.SUCCESS` if the grab was successful.
Return type:	`Gdk.GrabStatus`

Grabs the device so that all events coming from this device are passed to this application until the device is ungrabbed with Gdk.Device.ungrab(), or the window becomes unviewable. This overrides any previous grab on the device by this client.

Note that self and window need to be on the same display.

Device grabs are used for operations which need complete control over the given device events (either pointer or keyboard). For example in GTK+ this is used for Drag and Drop operations, popup menus and such.

Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with owner_events set to True.

If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the Gdk.EventGrabBroken events that are emitted when the grab ends unvoluntarily.

New in version 3.0.

Deprecated since version 3.20.: Use Gdk.Seat.grab() instead.

list_axes()[source]¶

Returns:	A `GLib.List` of `Gdk.Atoms`, free with g_list_free().
Return type:	[`Gdk.Atom`]

Returns a GLib.List of Gdk.Atoms, containing the labels for the axes that self currently has.

New in version 3.0.

list_slave_devices()[source]¶

Returns:	the list of slave devices, or `None`. The list must be freed with g_list_free(), the contents of the list are owned by GTK+ and should not be freed.
Return type:	[`Gdk.Device`] or `None`

If the device if of type Gdk.DeviceType.MASTER, it will return the list of slave devices attached to it, otherwise it will return None

set_axis_use(index_, use)[source]¶

Parameters:	index (`int`) – the index of the axis use (`Gdk.AxisUse`) – specifies how the axis is used

Specifies how an axis of a device is used.

set_key(index_, keyval, modifiers)[source]¶

Parameters:	index (`int`) – the index of the macro button to set keyval (`int`) – the keyval to generate modifiers (`Gdk.ModifierType`) – the modifiers to set

Specifies the X key event to generate when a macro button of a device is pressed.

set_mode(mode)[source]¶

Parameters:	mode (`Gdk.InputMode`) – the input mode.
Returns:	`True` if the mode was successfully changed.
Return type:	`bool`

Sets a the mode of an input device. The mode controls if the device is active and whether the device’s range is mapped to the entire screen or to a single window.

Note: This is only meaningful for floating devices, master devices (and slaves connected to these) drive the pointer cursor, which is not limited by the input mode.

ungrab(time_)[source]¶

Parameters:	time (`int`) – a timestap (e.g. `Gdk.CURRENT_TIME`).

Release any grab on self.

New in version 3.0.

Deprecated since version 3.20.: Use Gdk.Seat.ungrab() instead.

warp(screen, x, y)[source]¶

Parameters:	screen (`Gdk.Screen`) – the screen to warp self to. x (`int`) – the X coordinate of the destination. y (`int`) – the Y coordinate of the destination.

Warps self in display to the point x,`y` on the screen screen, unless the device is confined to a window by a grab, in which case it will be moved as far as allowed by the grab. Warping the pointer creates events as if the user had moved the mouse instantaneously to the destination.

Note that the pointer should normally be under the control of the user. This function was added to cover some rare use cases like keyboard navigation support for the color picker in the #GtkColorSelectionDialog.

New in version 3.0.

Signal Details¶

Gdk.Device.signals.changed(device)¶

Signal Name:	`changed`
Flags:	`RUN_LAST`
Parameters:	device (`Gdk.Device`) – The object which received the signal

The ::changed signal is emitted either when the Gdk.Device has changed the number of either axes or keys. For example In X this will normally happen when the slave device routing events through the master device changes (for example, user switches from the USB mouse to a tablet), in that case the master device will change to reflect the new slave device axes and keys.

Gdk.Device.signals.tool_changed(device, tool)¶

Signal Name:	`tool-changed`
Flags:	`RUN_LAST`
Parameters:	device (`Gdk.Device`) – The object which received the signal tool (`Gdk.DeviceTool`) – The new current tool

The ::tool-changed signal is emitted on pen/eraser Gdk.Devices whenever tools enter or leave proximity.

New in version 3.22.

Property Details¶

Gdk.Device.props.associated_device¶

Name:	`associated-device`
Type:	`Gdk.Device`
Default Value:	`None`
Flags:	`READABLE`

Associated pointer or keyboard with this device, if any. Devices of type Gdk.DeviceType.MASTER always come in keyboard/pointer pairs. Other device types will have a None associated device.

New in version 3.0.

Gdk.Device.props.axes¶

Name:	`axes`
Type:	`Gdk.AxisFlags`
Default Value:	`0`
Flags:	`READABLE`

The axes currently available for this device.

New in version 3.22.

Gdk.Device.props.device_manager¶

Name:	`device-manager`
Type:	`Gdk.DeviceManager`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The Gdk.DeviceManager the Gdk.Device pertains to.

New in version 3.0.

Gdk.Device.props.display¶

Name:	`display`
Type:	`Gdk.Display`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The Gdk.Display the Gdk.Device pertains to.

New in version 3.0.

Gdk.Device.props.has_cursor¶

Name:	`has-cursor`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Whether the device is represented by a cursor on the screen. Devices of type Gdk.DeviceType.MASTER will have True here.

New in version 3.0.

Gdk.Device.props.input_mode¶

Name:	`input-mode`
Type:	`Gdk.InputMode`
Default Value:	`Gdk.InputMode.DISABLED`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

Input mode for the device

Gdk.Device.props.input_source¶

Name:	`input-source`
Type:	`Gdk.InputSource`
Default Value:	`Gdk.InputSource.MOUSE`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`, `EXPLICIT_NOTIFY`

Source type for the device.

New in version 3.0.

Gdk.Device.props.n_axes¶

Name:	`n-axes`
Type:	`int`
Default Value:	`0`
Flags:	`READABLE`

Number of axes in the device.

New in version 3.0.

Gdk.Device.props.name¶

Name:	`name`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The device name.

New in version 3.0.

Gdk.Device.props.num_touches¶

Name:	`num-touches`
Type:	`int`
Default Value:	`0`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown.

New in version 3.20.

Gdk.Device.props.product_id¶

Name:	`product-id`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Product ID of this device, see Gdk.Device.get_product_id().

New in version 3.16.

Gdk.Device.props.seat¶

Name:	`seat`
Type:	`Gdk.Seat`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

Gdk.Seat of this device.

New in version 3.20.

Gdk.Device.props.tool¶

Name:	`tool`
Type:	`Gdk.DeviceTool`
Default Value:	`None`
Flags:	`READABLE`

The tool that is currently used with this device

Gdk.Device.props.type¶

Name:	`type`
Type:	`Gdk.DeviceType`
Default Value:	`Gdk.DeviceType.MASTER`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Device role in the device manager.

New in version 3.0.

Gdk.Device.props.vendor_id¶

Name:	`vendor-id`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Vendor ID of this device, see Gdk.Device.get_vendor_id().

New in version 3.16.