Struct input::Device

pub struct Device { /* fields omitted */ }

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.

Methods

impl Device

pub fn context(&self) -> Libinput

Get the libinput context from the device.

pub fn device_group(&self) -> DeviceGroup

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.

pub fn sysname(&self) -> &str

Get the system name of the device.

To get the descriptive device name, use name.

pub fn name(&self) -> &str

The descriptive device name as advertised by the kernel and/or the hardware itself.

To get the sysname for this device, use sysname.

pub fn output_name(&self) -> Option<&str>

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.

pub fn id_product(&self) -> u32

Get the product ID for this device.

pub fn id_vendor(&self) -> u32

Get the vendor ID for this device.

pub fn seat(&self) -> Seat

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.

pub fn set_seat_logical_name(&mut self, name: &str) -> Result<(), ()>

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.

pub unsafe fn udev_device(&self) -> Option<UdevDevice>

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.

Unsafety

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.

pub fn led_update(&mut self, leds: Led)

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.

pub fn has_capability(&self, cap: DeviceCapability) -> bool

Check if the given device has the specified capability.

pub fn size(&self) -> Option<(f64, f64)>

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.

pub fn pointer_has_button(&self, button: u32) -> Result<bool, ()>

Check if a DeviceCapability::Pointer device has a button with the given code (see linux/input.h).

pub fn keyboard_has_key(&self, key: u32) -> Result<bool, ()>

Check if a DeviceCapability::Keyboard device has a key with the given code (see linux/input.h).

pub fn switch_has_switch(&self, switch: Switch) -> Result<bool, ()>

Check if a DeviceCapability::Switch device has a switch of the given type.

pub fn tablet_pad_number_of_buttons(&self) -> i32

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.

pub fn tablet_pad_number_of_rings(&self) -> i32

Return the number of rings a device with the DeviceCapability::TabletPad capability provides.

pub fn tablet_pad_number_of_strips(&self) -> i32

Return the number of strips a device with the DeviceCapability::TabletPad capability provides.

pub fn tablet_pad_number_of_mode_groups(&self) -> i32

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.

pub fn tablet_pad_mode_group(&self, index: u32) -> Option<TabletPadModeGroup>

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.

pub fn tablet_pad_has_key(&self, code: u32) -> Option<bool>

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 key
• Some(false) if it has not
• None on error (no TabletPad device)

pub fn touch_count(&mut self) -> Option<u32>

Check how many touches a DeviceCapability::Touch-exposing Device supports simultaneously.

Returns

• Some(n) amount of touches
• Some(0) if unknown
• None on error (no touch device)

pub fn config_accel_default_profile(&self) -> Option<AccelProfile>

Return the default pointer acceleration profile for this pointer device.

pub fn config_accel_profile(&self) -> Option<AccelProfile>

Get the current pointer acceleration profile for this pointer device.

pub fn config_accel_profiles(&self) -> Vec<AccelProfile>

Returns a bitmask of the configurable acceleration modes available on this device.

pub fn config_accel_set_profile(
    &mut self,
    profile: AccelProfile
) -> DeviceConfigResult

Set the pointer acceleration profile of this pointer device to the given mode.

pub fn config_accel_default_speed(&self) -> f64

Return the default speed setting for this device, normalized to a range of [-1, 1].

pub fn config_accel_speed(&self) -> f64

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.

pub fn config_accel_set_speed(&mut self, speed: f64) -> DeviceConfigResult

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.

pub fn config_accel_is_available(&self) -> bool

Check if a device uses libinput-internal pointer-acceleration.

pub fn config_calibration_default_matrix(&self) -> Option<[f32; 6]>

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.

pub fn config_calibration_matrix(&self) -> Option<[f32; 6]>

Return the current calibration matrix for this device.

pub fn config_calibration_has_matrix(&self) -> bool

Check if the device can be calibrated via a calibration matrix.

pub fn config_calibration_set_matrix(
    &mut self,
    matrix: [f32; 6]
) -> DeviceConfigResult

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 ]

pub fn config_click_default_method(&self) -> Option<ClickMethod>

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.

pub fn config_click_method(&self) -> Option<ClickMethod>

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.

pub fn config_click_methods(&self) -> Vec<ClickMethod>

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.

pub fn config_click_set_method(
    &mut self,
    method: ClickMethod
) -> DeviceConfigResult

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.

pub fn config_dwt_default_enabled(&self) -> bool

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.

pub fn config_dwt_enabled(&self) -> bool

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.

pub fn config_dwt_is_available(&self) -> bool

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.

pub fn config_dwt_set_enabled(&self, enabled: bool) -> DeviceConfigResult

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.

pub fn config_left_handed(&self) -> bool

Get the current left-handed configuration of the device.

pub fn config_left_handed_default(&self) -> bool

Get the default left-handed configuration of the device.

pub fn config_left_handed_is_available(&self) -> bool

Check if a device has a configuration that supports left-handed usage.

pub fn config_left_handed_set(&self, enabled: bool) -> DeviceConfigResult

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.

pub fn config_middle_emulation_default_enabled(&self) -> bool

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.

pub fn config_middle_emulation_enabled(&self) -> bool

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.

pub fn config_middle_emulation_is_available(&self) -> bool

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.

pub fn config_middle_emulation_set_enabled(
    &self,
    enabled: bool
) -> DeviceConfigResult

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.

pub fn config_rotation_angle(&self) -> u32

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.

pub fn config_rotation_default_angle(&self) -> u32

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.

pub fn config_rotation_is_available(&self) -> bool

Check whether a device can have a custom rotation applied.

pub fn config_rotation_set_angle(&self, angle: u32) -> DeviceConfigResult

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.

pub fn config_scroll_button(&self) -> u32

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.

pub fn config_scroll_default_button(&self) -> u32

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.

pub fn config_scroll_default_method(&self) -> ScrollMethod

Get the default scroll method for this device.

The method defines when to generate scroll axis events instead of pointer motion events.

pub fn config_scroll_method(&self) -> ScrollMethod

Get the scroll method for this device.

The method defines when to generate scroll axis events instead of pointer motion events.

pub fn config_scroll_methods(&self) -> Vec<ScrollMethod>

Check which scroll methods a device supports.

The method defines when to generate scroll axis events instead of pointer motion events.

pub fn config_scroll_set_method(
    &mut self,
    method: ScrollMethod
) -> DeviceConfigResult

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.

pub fn config_scroll_default_natural_scroll_enabled(&self) -> bool

Get the default mode for scrolling on this device.

pub fn config_scroll_natural_scroll_enabled(&self) -> bool

Get the current mode for scrolling on this device.

pub fn config_scroll_has_natural_scroll(&self) -> bool

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

Enable or disable natural scrolling on the device.

pub fn config_scroll_set_button(&mut self, button: u32) -> DeviceConfigResult

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.

pub fn config_scroll_button_lock(&self) -> ScrollButtonLockState

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.

pub fn config_scroll_default_button_lock(&self) -> ScrollButtonLockState

Get the default scroll button lock state

If ScrollMethod::OnButtonDown is not supported, or no button is set, this functions returns Disabled.

pub fn config_scroll_set_button_lock(
    &mut self,
    state: ScrollButtonLockState
) -> DeviceConfigResult

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.

pub fn config_send_events_mode(&self) -> SendEventsMode

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.

pub fn config_send_events_modes(&self) -> SendEventsMode

Return the possible send-event modes for this device.

These modes define when a device may process and send events.

pub fn config_send_events_set_mode(
    &self,
    mode: SendEventsMode
) -> DeviceConfigResult

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.

pub fn config_tap_button_map(&self) -> Option<TapButtonMap>

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.

pub fn config_tap_default_button_map(&self) -> Option<TapButtonMap>

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.

pub fn config_tap_default_drag_enabled(&self) -> bool

Return whether tap-and-drag is enabled or disabled by default on this device.

pub fn config_tap_default_drag_lock_enabled(&self) -> bool

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.

pub fn config_tap_default_enabled(&self) -> bool

Return the default setting for whether tap-to-click is enabled on this device.

pub fn config_tap_drag_enabled(&self) -> bool

Return whether tap-and-drag is enabled or disabled on this device.

pub fn config_tap_drag_lock_enabled(&self) -> bool

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.

pub fn config_tap_enabled(&self) -> bool

Check if tap-to-click is enabled on this device.

If the device does not support tapping, this function always returns false.

pub fn config_tap_finger_count(&self) -> u32

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.

pub fn config_tap_set_button_map(
    &mut self,
    map: TapButtonMap
) -> DeviceConfigResult

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.

pub fn config_tap_set_drag_enabled(
    &mut self,
    enabled: bool
) -> DeviceConfigResult

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.

pub fn config_tap_set_drag_lock_enabled(
    &mut self,
    enabled: bool
) -> DeviceConfigResult

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.

pub fn config_tap_set_enabled(&mut self, enabled: bool) -> DeviceConfigResult

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

impl AsRaw<libinput_device> for Device

fn as_raw(&self) -> *const libinput_device

Receive a raw pointer representing this type.

impl Clone for Device

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Context for Device

fn context(&self) -> &Libinput

Returns the underlying libinput context

impl Debug for Device

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Drop for Device

fn drop(&mut self)

Executes the destructor for this type.

impl Eq for Device

impl FromRaw<libinput_device> for Device

unsafe fn from_raw(ffi: *mut libinput_device, context: &Libinput) -> Self

Create a new instance of this type from a raw pointer and it's context.

impl Hash for Device

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl PartialEq<Device> for Device

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl StructuralEq for Device