Struct input::Device [−][src]
pub struct Device { /* fields omitted */ }Expand description
Representation of a single input device as seen by the kernel.
A single physical device might consist out of multiple input
devices like a keyboard-touchpad combination. See DeviceGroup
if you want to track such combined physical devices.
Implementations
Get the libinput context from the device.
Get the device group this device is assigned to.
Some physical devices like graphics tablets are represented by
multiple kernel devices and thus by multiple Devices.
libinput assigns these devices to the same DeviceGroup
allowing the caller to identify such devices and adjust
configuration settings accordingly. For example, setting a
tablet to left-handed often means turning it upside down. A
touch device on the same tablet would need to be turned upside
down too to work correctly.
All devices are part of a device group though for most devices
the group will be a singleton. A device is assigned to a
device group on DeviceAddedEvent and removed from that group
on DeviceRemovedEvent. It is up to the caller to track how
many devices are in each device group.
Device groups do not get re-used once the last device in the group was removed, i.e. unplugging and re-plugging a physical device with grouped devices will return a different device group after every unplug.
Device groups are assigned based on the LIBINPUT_DEVICE_GROUP
udev property, see Static device configuration via udev.
Get the system name of the device.
To get the descriptive device name, use name.
The descriptive device name as advertised by the kernel and/or the hardware itself.
To get the sysname for this device, use sysname.
A device may be mapped to a single output, or all available outputs.
If a device is mapped to a single output only, a relative device may not move beyond the boundaries of this output. An absolute device has its input coordinates mapped to the extents of this output.
Get the product ID for this device.
Get the seat associated with this input device, see Seats for details.
A seat can be uniquely identified by the physical and logical seat name. There will ever be only one seat instance with a given physical and logical seat name pair at any given time, but if no external reference is kept, it may be destroyed if no device belonging to it is left.
Change the logical seat associated with this device by removing the device and adding it to the new seat.
This command is identical to physically unplugging the device,
then re-plugging it as a member of the new seat. libinput will
generate a DeviceRemovedEvent event and this Device is
considered removed from the context; it will not generate
further events and will be freed when it goes out of scope.
A DeviceAddedEvent event is generated with a new Device
handle. It is the caller’s responsibility to update references
to the new device accordingly.
If the logical seat name already exists in the device’s physical seat, the device is added to this seat. Otherwise, a new seat is created.
Note
This change applies to this device until removal or suspend,
whichever happens earlier.
Return a udev handle to the device that is this libinput device, if any.
Some devices may not have a udev device, or the udev device
may be unobtainable. This function returns None if no udev
device was available.
Calling this function multiple times for the same device may not return the same udev handle each time.
Safety
The result of this function is not definied if the passed udev Context
is not the same as the one the libinput Context was created from.
Update the LEDs on the device, if any.
If the device does not have LEDs, or does not have one or more of the LEDs given in the mask, this function does nothing.
Arguments
leds: Leds to turn on
Missing Leds will be turned off.
The slice is interpreted as a bitmap.
Check if the given device has the specified capability.
Get the physical size of a device in mm, where meaningful.
This function only succeeds on devices with the required data, i.e. tablets, touchpads and touchscreens.
Check if a DeviceCapability::Pointer device has a button
with the given code (see linux/input.h).
Check if a DeviceCapability::Keyboard device has a key with
the given code (see linux/input.h).
Check if a DeviceCapability::Switch device has a switch of the
given type.
Return the number of buttons on a device with the
DeviceCapability::TabletPad capability.
Buttons on a pad device are numbered sequentially, see Tablet pad button numbers for details.
Return the number of rings a device with the
DeviceCapability::TabletPad capability provides.
Return the number of strips a device with the
DeviceCapability::TabletPad capability provides.
Most devices only provide a single mode group, however devices such as the Wacom Cintiq 22HD provide two mode groups.
If multiple mode groups are available, a caller should use
TabletPadModeGroup::has_button,
TabletPadModeGroup::has_ring and
TabletPadModeGroup::has_strip() to associate each button,
ring and strip with the correct mode group.
Return the current mode this mode group is in.
Note that the returned mode is the mode valid as of completing
the last dispatch. The returned mode may thus be
different than the mode returned by
TabletPadEventTrait::mode.
For example, if the mode was toggled three times between the
call to dispatch, this function returns the third mode but
the events in the event queue will return the modes 1, 2 and
3, respectively.
Check if a DeviceCapability::TabletPad-device has a key with the given code (see linux/input-event-codes.h).
Returns
Some(true)if it has the requested keySome(false)if it has notNoneon error (no TabletPad device)
Check how many touches a DeviceCapability::Touch-exposing Device supports simultaneously.
Returns
Some(n)amount of touchesSome(0)if unknownNoneon error (no touch device)
Return the default pointer acceleration profile for this pointer device.
Get the current pointer acceleration profile for this pointer device.
Returns a bitmask of the configurable acceleration modes available on this device.
Set the pointer acceleration profile of this pointer device to the given mode.
Return the default speed setting for this device, normalized to a range of [-1, 1].
Get the current pointer acceleration setting for this pointer device.
The returned value is normalized to a range of [-1, 1]. See
config_accel_set_speed for details.
Set the pointer acceleration speed of this pointer device within a range of [-1, 1], where 0 is the default acceleration for this device, -1 is the slowest acceleration and 1 is the maximum acceleration available on this device.
The actual pointer acceleration mechanism is implementation-dependent, as is the number of steps available within the range. libinput picks the semantically closest acceleration step if the requested value does not match a discrete setting.
Check if a device uses libinput-internal pointer-acceleration.
Return the default calibration matrix for this device.
On most devices, this is the identity matrix. If the udev
property LIBINPUT_CALIBRATION_MATRIX is set on the respective u
dev device, that property’s value becomes the default matrix,
see Static device configuration via udev.
Return the current calibration matrix for this device.
Check if the device can be calibrated via a calibration matrix.
Apply the 3x3 transformation matrix to absolute device coordinates.
This matrix has no effect on relative events.
Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
[ a b c ] [ x ]
[ d e f ] * [ y ]
[ 0 0 1 ] [ 1 ]The translation component (c, f) is expected to be normalized to the device coordinate range. For example, the matrix
[ 1 0 1 ]
[ 0 1 -1 ]
[ 0 0 1 ]moves all coordinates by 1 device-width to the right and 1 device-height up.
The rotation matrix for rotation around the origin is defined as
[ cos(a) -sin(a) 0 ]
[ sin(a) cos(a) 0 ]
[ 0 0 1 ]Note that any rotation requires an additional translation component to translate the rotated coordinates back into the original device space. The rotation matrixes for 90, 180 and 270 degrees clockwise are:
90 deg cw: 180 deg cw: 270 deg cw:
[ 0 -1 1] [ -1 0 1] [ 0 1 0 ]
[ 1 0 0] [ 0 -1 1] [ -1 0 1 ]
[ 0 0 1] [ 0 0 1] [ 0 0 1 ]Get the default button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
Get the button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
Check which button click methods a device supports.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
Set the button click method for this device.
The button click method defines when to generate software-emulated buttons, usually on a device that does not have a specific physical button available.
Note
The selected click method may not take effect immediately. The device may require changing to a neutral state first before activating the new method.
Check if the disable-while typing feature is enabled on this device by default.
If the device does not support disable-while-typing, this
function returns false.
Check if the disable-while typing feature is currently enabled on this device.
If the device does not support disable-while-typing, this
function returns false.
Check if this device supports configurable disable-while-typing feature.
This feature is usually available on built-in touchpads and disables the touchpad while typing. See Disable-while-typing for details.
Enable or disable the disable-while-typing feature.
When enabled, the device will be disabled while typing and for a short period after. See Disable-while-typing for details.
Note
Enabling or disabling disable-while-typing may not take effect immediately.
Get the current left-handed configuration of the device.
Get the default left-handed configuration of the device.
Check if a device has a configuration that supports left-handed usage.
Set the left-handed configuration of the device.
The exact behavior is device-dependent. On a mouse and most pointing devices, left and right buttons are swapped but the middle button is unmodified. On a touchpad, physical buttons (if present) are swapped. On a clickpad, the top and bottom software-emulated buttons are swapped where present, the main area of the touchpad remains a left button. Tapping and clickfinger behavior is not affected by this setting.
Changing the left-handed configuration of a device may not take effect until all buttons have been logically released.
Check if configurable middle button emulation is enabled by default on this device.
See Middle button emulation for details.
If the device does not have configurable middle button
emulation, this function returns false.
Note
Some devices provide middle mouse button emulation but do not
allow enabling/disabling that emulation. These devices always
return false.
Check if configurable middle button emulation is enabled on this device.
See Middle button emulation for details.
If the device does not have configurable middle button
emulation, this function returns false.
Note
Some devices provide middle mouse button emulation but do not
allow enabling/disabling that emulation. These devices always
return false.
Check if middle mouse button emulation configuration is available on this device.
See Middle button emulation for details.
Note
Some devices provide middle mouse button emulation but do not
allow enabling/disabling that emulation. These devices return
false in config_middle_emulation_is_available.
Enable or disable middle button emulation on this device.
When enabled, a simultaneous press of the left and right button generates a middle mouse button event. Releasing the buttons generates a middle mouse button release, the left and right button events are discarded otherwise.
See Middle button emulation for details.
Get the current rotation of a device in degrees clockwise off the logical neutral position.
If this device does not support rotation, the return value is always 0.
Get the default rotation of a device in degrees clockwise off the logical neutral position.
If this device does not support rotation, the return value is always 0.
Check whether a device can have a custom rotation applied.
Set the rotation of a device in degrees clockwise off the logical neutral position.
Any subsequent motion events are adjusted according to the given angle.
The angle has to be in the range of [0, 360] degrees,
otherwise this function returns DeviceConfigError::Invalid.
If the angle is a multiple of 360 or negative, the caller
must ensure the correct ranging before calling this function.
libinput guarantees that this function accepts multiples of
90 degrees. If a value is within the [0, 360] range but not a
multiple of 90 degrees, this function may return
DeviceConfigError::Invalid if the underlying device or
implementation does not support finer-grained rotation angles.
The rotation angle is applied to all motion events emitted by the device. Thus, rotating the device also changes the angle required or presented by scrolling, gestures, etc.
Setting a rotation of 0 degrees on a device that does not support rotation always succeeds.
Get the button for the ScrollMethod::OnButtonDown method
for this device.
If ScrollMethod::OnButtonDown scroll method is not
supported, or no button is set, this function returns 0.
Note
The return value is independent of the currently selected
scroll-method. For button scrolling to activate, a device
must have the ScrollMethod::OnButtonDown method enabled,
and a non-zero button set as scroll button.
Get the default button for the ScrollMethod::OnButtonDown
method for this device.
If ScrollMethod::OnButtonDown scroll method is not
supported, or no default button is set,
this function returns 0.
Get the default scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
A return value of None means the scroll method is not known
Get the scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
A return value of None means the scroll method is not known
Check which scroll methods a device supports.
The method defines when to generate scroll axis events instead of pointer motion events.
Set the scroll method for this device.
The method defines when to generate scroll axis events instead of pointer motion events.
Note
Setting ScrollMethod::OnButtonDown enables the scroll
method, but scrolling is only activated when the configured
button is held down. If no button is set, i.e.
config_scroll_button returns 0, scrolling cannot activate.
Get the default mode for scrolling on this device.
Get the current mode for scrolling on this device.
Return non-zero if the device supports “natural scrolling”.
In traditional scroll mode, the movement of fingers on a touchpad when scrolling matches the movement of the scroll bars. When the fingers move down, the scroll bar moves down, a line of text on the screen moves towards the upper end of the screen. This also matches scroll wheels on mice (wheel down, content moves up).
Natural scrolling is the term coined by Apple for inverted scrolling. In this mode, the effect of scrolling movement of fingers on a touchpad resemble physical manipulation of paper. When the fingers move down, a line of text on the screen moves down (scrollbars move up). This is the opposite of scroll wheels on mice.
A device supporting natural scrolling can be switched between traditional scroll mode and natural scroll mode.
pub fn config_scroll_set_natural_scroll_enabled(
&mut self,
enabled: bool
) -> DeviceConfigResult
pub fn config_scroll_set_natural_scroll_enabled(
&mut self,
enabled: bool
) -> DeviceConfigResult
Enable or disable natural scrolling on the device.
Set the button for the ScrollMethod::OnButtonDown method
for this device.
When the current scroll method is set to
ScrollMethod::OnButtonDown, no button press/release events
will be send for the configured button.
When the configured button is pressed, any motion events along a scroll-capable axis are turned into scroll axis events.
Note
Setting the button does not change the scroll method. To
change the scroll method call config_scroll_set_method.
If the button is 0, button scrolling is effectively disabled.
Get the current scroll button lock state
If ScrollMethod::OnButtonDown is not supported, or no button is set,
this functions returns Disabled.
Note
The return value is independent of the currently selected scroll-method.
For the scroll button lock to activate, a device must have the
ScrollMethod::OnButtonDown enabled, and a non-zero button set as scroll button.
Get the default scroll button lock state
If ScrollMethod::OnButtonDown is not supported, or no button is set,
this functions returns Disabled.
Set the scroll button lock.
If the state is Disabled the button must physically be held down for
button scrolling to work. If the state is Enabled, the button is considered
logically down after the first press and release sequence, and logically
up after the second press and release sequence.
Get the send-event mode for this device.
The mode defines when the device processes and sends events to the caller.
If a caller enables the bits for multiple modes, some of
which are subsets of another mode libinput may drop the bits
that are subsets. In other words, don’t expect
config_send_events_mode to always return exactly the same
as passed into config_send_events_set_mode.
Return the possible send-event modes for this device.
These modes define when a device may process and send events.
Set the send-event mode for this device.
The mode defines when the device processes and sends events to the caller.
The selected mode may not take effect immediately. Events
already received and processed from this device are
unaffected and will be passed to the caller on the next call
to <Libinput as Iterator>::next().
If the mode is a mixture of SendEventsModes, the device may
wait for or generate events until it is in a neutral state.
For example, this may include waiting for or generating
button release events.
If the device is already suspended, this function does nothing and returns success. Changing the send-event mode on a device that has been removed is permitted.
Get the finger number to button number mapping for tap-to-click.
The return value for a device that does not support tapping
is always TapButtonMap::LeftRightMiddle.
This will return None for devices
where config_tap_finger_count returns 0.
Get the default finger number to button number mapping for tap-to-click.
The return value for a device that does not support tapping
is always TapButtonMap::LeftRightMiddle.
This will return None for devices
where config_tap_finger_count returns 0.
Return whether tap-and-drag is enabled or disabled by default on this device.
Check if drag-lock during tapping is enabled by default on this device.
If the device does not support tapping, this function always
returns false.
Drag lock may be enabled by default even when tapping is disabled by default.
Return the default setting for whether tap-to-click is enabled on this device.
Return whether tap-and-drag is enabled or disabled on this device.
Check if drag-lock during tapping is enabled on this device.
If the device does not support tapping, this function always
returns false.
Drag lock may be enabled even when tapping is disabled.
Check if tap-to-click is enabled on this device.
If the device does not support tapping, this function always
returns false.
Check if the device supports tap-to-click and how many fingers can be used for tapping.
See config_tap_set_enabled for more information.
Set the finger number to button number mapping for tap-to-click.
The default mapping on most devices is to have a 1, 2 and 3
finger tap to map to the left, right and middle button,
respectively. A device may permit changing the button mapping
but disallow specific maps. In this case
DeviceConfigError::Disabled is returned, the caller is
expected to handle this case correctly.
Changing the button mapping may not take effect immediately, the device may wait until it is in a neutral state before applying any changes.
The mapping may be changed when tap-to-click is disabled. The new mapping takes effect when tap-to-click is enabled in the future.
Note
This will return None for devices where
config_tap_finger_count returns 0.
Enable or disable tap-and-drag on this device.
When enabled, a single-finger tap immediately followed by a finger down results in a button down event, subsequent finger motion thus triggers a drag. The button is released on finger up. See Tap-and-drag for more details.
Enable or disable drag-lock during tapping on this device.
When enabled, a finger may be lifted and put back on the touchpad within a timeout and the drag process continues. When disabled, lifting the finger during a tap-and-drag will immediately stop the drag. See Tap-and-drag for details.
Enabling drag lock on a device that has tapping disabled is permitted, but has no effect until tapping is enabled.
Enable or disable tap-to-click on this device, with a default mapping of 1, 2, 3 finger tap mapping to left, right, middle click, respectively.
Tapping is limited by the number of simultaneous touches
supported by the device, see config_tap_finger_count.
Trait Implementations
Receive a raw pointer representing this type.
Auto Trait Implementations
impl !RefUnwindSafe for Device
impl !UnwindSafe for Device
Blanket Implementations
Mutably borrows from an owned value. Read more