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.