Gnome::Gdk3::Device

Object representing an input device

Description

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

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

Synopsis

Declaration

unit class Gnome::Gdk3::Device;
also is Gnome::GObject::Object;

Types

enum GdkInputSource

An enumeration describing the type of an input device in general terms.

GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core pointer, even if it is something else, such as a trackball.)
GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end of a stylus on a graphics tablet.
GDK_SOURCE_CURSOR: the device is a graphics tablet “puck” or similar device.
GDK_SOURCE_KEYBOARD: the device is a keyboard.
GDK_SOURCE_TOUCHSCREEN: the device is a direct-input touch device, such as a touchscreen or tablet. This device type has been added in 3.4.
GDK_SOURCE_TOUCHPAD: the device is an indirect touch device, such as a touchpad. This device type has been added in 3.4.
GDK_SOURCE_TRACKPOINT: the device is a trackpoint. This device type has been added in 3.22
GDK_SOURCE_TABLET_PAD: the device is a “pad”, a collection of buttons, rings and strips found in drawing tablets. This device type has been added in 3.22.

enum GdkInputMode

An enumeration that describes the mode of an input device.

GDK_MODE_DISABLED: the device is disabled and will not report any events.
GDK_MODE_SCREEN: the device is enabled. The device’s coordinate space maps to the entire screen.
GDK_MODE_WINDOW: the device is enabled. The device’s coordinate space is mapped to a single window. The manner in which this window is chosen is undefined, but it will typically be the same way in which the focus window for key events is determined.

enum GdkDeviceType

Indicates the device type. See [above][Gnome::Gdk3::DeviceManager.description] for more information about the meaning of these device types.

GDK_DEVICE_TYPE_MASTER: Device is a master (or virtual) device. There will be an associated focus indicator on the screen.
GDK_DEVICE_TYPE_SLAVE: Device is a slave (or physical) device.
GDK_DEVICE_TYPE_FLOATING: Device is a physical device, currently not attached to any virtual device.

Methods

new

Create an object using a native object from elsewhere. See also Gnome::GObject::Object.

multi method new ( N-GObject :$native-object! )

[[gdk_] device_] get_name

Determines the name of the device.

Returns: a name

Since: 2.20

method gdk_device_get_name ( --> Str  )

[[gdk_] device_] get_has_cursor

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

Returns: 1 if the pointer follows device motion

Since: 2.20

method gdk_device_get_has_cursor ( --> Int  )

[[gdk_] device_] get_source

Determines the type of the device.

Returns: a Gnome::Gdk3::InputSource

Since: 2.20

method gdk_device_get_source ( --> GdkInputSource  )

[[gdk_] device_] get_mode

Determines the mode of the device.

Returns: a Gnome::Gdk3::InputSource

Since: 2.20

method gdk_device_get_mode ( --> GdkInputMode  )

[[gdk_] device_] set_mode

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.

Returns: 1 if the mode was successfully changed.

method gdk_device_set_mode ( GdkInputMode $mode --> Int  )

GdkInputMode $mode; the input mode.

[[gdk_] device_] get_n_keys

Returns the number of keys the device currently has.

Returns: the number of keys.

Since: 2.24

method gdk_device_get_n_keys ( --> Int  )

[[gdk_] device_] get_key

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

Returns: 1 if keyval is set for index.

Since: 2.20

method gdk_device_get_key ( UInt $index_, UInt $keyval, GdkModifierType $modifiers --> Int  )

UInt $index_; the index of the macro button to get.
UInt $keyval; (out): return value for the keyval.
GdkModifierType $modifiers; (out): return value for modifiers.

[[gdk_] device_] set_key

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

method gdk_device_set_key ( UInt $index_, UInt $keyval, GdkModifierType $modifiers )

UInt $index_; the index of the macro button to set
UInt $keyval; the keyval to generate
GdkModifierType $modifiers; the modifiers to set

[[gdk_] device_] get_state

Gets the current state of a pointer device relative to window. As a slave device’s coordinates are those of its master pointer, this function may not be called on devices of type GDK_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them. See gdk_device_grab().

method gdk_device_get_state ( N-GObject $window, Num $axes, GdkModifierType $mask )

N-GObject $window; a Gnome::Gdk3::Window.
Num $axes; (nullable) (array): an array of doubles to store the values of the axes of device in, or Any.
GdkModifierType $mask; (optional) (out): location to store the modifiers, or Any.

[[gdk_] device_] get_position

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

Since: 3.0

method gdk_device_get_position ( N-GObject $screen, Int $x, Int $y )

N-GObject $screen; (out) (transfer none) (allow-none): location to store the Gnome::Gdk3::Screen the device is on, or Any.
Int $x; (out) (allow-none): location to store root window X coordinate of device, or Any.
Int $y; (out) (allow-none): location to store root window Y coordinate of device, or Any.

[[gdk_] device_] get_window_at_position

Obtains the window underneath device, returning the location of the device in win_x and win_y. Returns Any if the window tree under device 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_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them, see gdk_device_grab().

Returns: (nullable) (transfer none): the Gnome::Gdk3::Window under the device position, or Any.

Since: 3.0

method gdk_device_get_window_at_position ( Int $win_x, Int $win_y --> N-GObject  )

Int $win_x; (out) (allow-none): return location for the X coordinate of the device location, relative to the window origin, or Any.
Int $win_y; (out) (allow-none): return location for the Y coordinate of the device location, relative to the window origin, or Any.

[[gdk_] device_] get_position_double

Gets the current location of device 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_DEVICE_TYPE_SLAVE, unless there is an ongoing grab on them. See gdk_device_grab().

Since: 3.10

method gdk_device_get_position_double ( N-GObject $screen, Num $x, Num $y )

N-GObject $screen; (out) (transfer none) (allow-none): location to store the Gnome::Gdk3::Screen the device is on, or Any.
Num $x; (out) (allow-none): location to store root window X coordinate of device, or Any.
Num $y; (out) (allow-none): location to store root window Y coordinate of device, or Any.

[[gdk_] device_] get_window_at_position_double

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

Returns: (nullable) (transfer none): the Gnome::Gdk3::Window under the device position, or Any.

Since: 3.0

method gdk_device_get_window_at_position_double ( Num $win_x, Num $win_y --> N-GObject  )

Num $win_x; (out) (allow-none): return location for the X coordinate of the device location, relative to the window origin, or Any.
Num $win_y; (out) (allow-none): return location for the Y coordinate of the device location, relative to the window origin, or Any.

[[gdk_] device_] get_n_axes

Returns the number of axes the device currently has.

Returns: the number of axes.

Since: 3.0

method gdk_device_get_n_axes ( --> Int  )

[[gdk_] device_] list_axes

Returns a GList of Gnome::Gdk3::Atoms, containing the labels for the axes that device currently has.

Returns: (transfer container) (element-type Gnome::Gdk3::Atom): A GList of Gnome::Gdk3::Atoms, free with g_list_free().

Since: 3.0

method gdk_device_list_axes ( --> N-GList  )

[[gdk_] device_] get_display

Returns the Gnome::Gdk3::Display to which device pertains.

Returns: (transfer none): a Gnome::Gdk3::Display. This memory is owned by GTK+, and must not be freed or unreffed.

Since: 3.0

method gdk_device_get_display ( --> N-GObject  )

[[gdk_] device_] get_associated_device

Returns the associated device to device, if device is of type GDK_DEVICE_TYPE_MASTER, it will return the paired pointer or keyboard.

If device is of type GDK_DEVICE_TYPE_SLAVE, it will return the master device to which device is attached to.

If device is of type GDK_DEVICE_TYPE_FLOATING, Any will be returned, as there is no associated device.

Returns: (nullable) (transfer none): The associated device, or Any

Since: 3.0

method gdk_device_get_associated_device ( --> N-GObject  )

[[gdk_] device_] list_slave_devices

If the device if of type GDK_DEVICE_TYPE_MASTER, it will return the list of slave devices attached to it, otherwise it will return Any

Returns: (nullable) (transfer container) (element-type Gnome::Gdk3::Device): the list of slave devices, or Any. The list must be freed with g_list_free(), the contents of the list are owned by GTK+ and should not be freed.

method gdk_device_list_slave_devices ( --> N-GList  )

[[gdk_] device_] get_device_type

Returns the device type for device.

Returns: the Gnome::Gdk3::DeviceType for device.

Since: 3.0

method gdk_device_get_device_type ( --> GdkDeviceType  )

gdk_device_warp

Warps device 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 Gnome::Gtk3::ColorSelectionDialog.

Since: 3.0

method gdk_device_warp ( N-GObject $screen, Int $x, Int $y )

N-GObject $screen; the screen to warp device to.
Int $x; the X coordinate of the destination.
Int $y; the Y coordinate of the destination.

[[gdk_] device_] get_last_event_window

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 = 0, Any may be returned even if the pointer is physically over one of this application’s windows.

Returns: (transfer none) (allow-none): the last window the device

Since: 3.12

method gdk_device_get_last_event_window ( --> N-GObject  )

[[gdk_] device_] get_vendor_id

Returns the vendor ID of this device, or Any 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 GSettings paths to store settings for this device.

[ static GSettings * get_device_settings (Gnome::Gdk3::Device *device) { const gchar *vendor, *product; GSettings *settings; Gnome::Gdk3::Device *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; } ]

Returns: (nullable): the vendor ID, or Any

Since: 3.16

method gdk_device_get_vendor_id ( --> Str  )

[[gdk_] device_] get_product_id

Returns the product ID of this device, or Any 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.

Returns: (nullable): the product ID, or Any

Since: 3.16

method gdk_device_get_product_id ( --> Str  )

[[gdk_] device_] get_seat

Returns the Gnome::Gdk3::Seat the device belongs to.

Returns: (transfer none): A Gnome::Gdk3::Seat. This memory is owned by GTK+ and must not be freed.

Since: 3.20

method gdk_device_get_seat ( --> N-GObject  )

Signals

There are two ways to connect to a signal. The first option you have is to use register-signal() from Gnome::GObject::Object. The second option is to use g_signal_connect_object() directly from Gnome::GObject::Signal.

First method

The positional arguments of the signal handler are all obligatory as well as their types. The named attributes :$widget and user data are optional.

# handler method
method mouse-event ( N-GdkEvent $event, :$widget ) { ... }

# connect a signal on window object
my Gnome::Gtk3::Window $w .= new( ... );
$w.register-signal( self, 'mouse-event', 'button-press-event');

Second method

my Gnome::Gtk3::Window $w .= new( ... );
my Callable $handler = sub (
  N-GObject $native, N-GdkEvent $event, OpaquePointer $data
) {
  ...
}

$w.connect-object( 'button-press-event', $handler);

Also here, the types of positional arguments in the signal handler are important. This is because both methods register-signal() and g_signal_connect_object() are using the signatures of the handler routines to setup the native call interface.

Supported signals

changed

The changed signal is emitted either when the Gnome::Gdk3::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.

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($device),
  *%user-options
);

$device; the Gnome::Gdk3::Device that changed.

tool-changed

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

Since: 3.22

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($device),
  *%user-options
);

$device; the native object for Gnome::Gdk3::Device that changed.
$tool; The new current tool

Properties

An example of using a string type property of a Gnome::Gtk3::Label object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use new(:label(‘my text label’)) or gtk_label_set_text(‘my text label’).

my Gnome::Gtk3::Label $label .= new;
my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
$label.g-object-get-property( 'label', $gv);
$gv.g-value-set-string('my text label');

Supported properties

Device manager

The Gnome::Gdk3::DeviceManager the Gnome::Gdk3::Device pertains to. Since: 3.0 Widget type: GDK_TYPE_DEVICE_MANAGER

The Gnome::GObject::Value type of property device-manager is G_TYPE_OBJECT.

Device name

The device name. Since: 3.0

The Gnome::GObject::Value type of property name is G_TYPE_STRING.

Device type

Device role in the device manager. Since: 3.0 Widget type: GDK_TYPE_DEVICE_TYPE

The Gnome::GObject::Value type of property type is G_TYPE_ENUM.

Input source

Source type for the device. Since: 3.0 Widget type: GDK_TYPE_INPUT_SOURCE

The Gnome::GObject::Value type of property input-source is G_TYPE_ENUM.

Input mode for the device

Input mode for the device Default value: False

The Gnome::GObject::Value type of property input-mode is G_TYPE_ENUM.

Whether the device has a cursor

Whether the device is represented by a cursor on the screen. Devices of type GDK_DEVICE_TYPE_MASTER will have 1 here. Since: 3.0

The Gnome::GObject::Value type of property has-cursor is G_TYPE_BOOLEAN.

Number of axes in the device

Number of axes in the device. Since: 3.0

The Gnome::GObject::Value type of property n-axes is G_TYPE_UINT.

Vendor ID

Vendor ID of this device, see gdk_device_get_vendor_id(). Since: 3.16

The Gnome::GObject::Value type of property vendor-id is G_TYPE_STRING.

Product ID

Product ID of this device, see gdk_device_get_product_id(). Since: 3.16

The Gnome::GObject::Value type of property product-id is G_TYPE_STRING.

Number of concurrent touches

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. Since: 3.20

The Gnome::GObject::Value type of property num-touches is G_TYPE_UINT.

Axes

The axes currently available for this device. Since: 3.22

The Gnome::GObject::Value type of property axes is G_TYPE_FLAGS.

Tool

The tool that is currently used with this device Widget type: GDK_TYPE_DEVICE_TOOL

The Gnome::GObject::Value type of property tool is G_TYPE_OBJECT.

Gnome::Gdk3::Device

Description

See Also

Synopsis

Declaration

Types

enum GdkInputSource

enum GdkInputMode

enum GdkDeviceType

Methods

new

[[gdk_] device_] get_name

[[gdk_] device_] get_has_cursor

[[gdk_] device_] get_source

[[gdk_] device_] get_mode

[[gdk_] device_] set_mode

[[gdk_] device_] get_n_keys

[[gdk_] device_] get_key

[[gdk_] device_] set_key

[[gdk_] device_] get_state

[[gdk_] device_] get_position

[[gdk_] device_] get_window_at_position

[[gdk_] device_] get_position_double

[[gdk_] device_] get_window_at_position_double

[[gdk_] device_] get_n_axes

[[gdk_] device_] list_axes

[[gdk_] device_] get_display

[[gdk_] device_] get_associated_device

[[gdk_] device_] list_slave_devices

[[gdk_] device_] get_device_type

gdk_device_warp

[[gdk_] device_] get_last_event_window

[[gdk_] device_] get_vendor_id

[[gdk_] device_] get_product_id

[[gdk_] device_] get_seat

Signals

First method

Second method

Supported signals

changed

tool-changed

Properties

Supported properties

Device manager

Device name

Device type

Input source

Input mode for the device

Whether the device has a cursor

Number of axes in the device

Vendor ID

Product ID

Number of concurrent touches

Axes

Tool