input/event/tablet_tool/
tool.rs

Help
1use crate::{ffi, AsRaw, FromRaw};
2
3/// Available tool types for a device with the `DeviceCapability::TabletTool` capability.
4///
5/// The tool type defines the default usage of the tool as advertised by the
6/// manufacturer. Multiple different physical tools may share the same tool type, e.g. a
7/// Wacom Classic Pen, Wacom Pro Pen and a Wacom Grip Pen are all of type
8/// `TabletToolType::Pen`. Use `TabletTool::tool_id` to get a specific model where
9/// applicable.
10///
11/// Note that on some device, the eraser tool is on the tail end of a pen device. On
12/// other devices, e.g. MS Surface 3, the eraser is the pen tip while a button is held
13/// down.
14///
15/// ## Note
16///
17/// The `TabletToolType` can only describe the default physical type of the device. For
18/// devices with adjustable physical properties the tool type remains the same, i.e.
19/// putting a Wacom stroke nib into a classic pen leaves the tool type as
20/// `TabletToolType::Pen`.
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
22#[non_exhaustive]
23pub enum TabletToolType {
24    /// A generic pen.
25    Pen,
26    /// Eraser.
27    Eraser,
28    /// A paintbrush-like tool.
29    Brush,
30    /// Physical drawing tool, e.g. Wacom Inking Pen
31    Pencil,
32    /// An airbrush-like tool.
33    Airbrush,
34    /// A mouse bound to the tablet.
35    Mouse,
36    /// A mouse tool with a lens.
37    Lens,
38    /// A rotary device with positional and rotation data
39    #[cfg(feature = "libinput_1_14")]
40    Totem,
41}
42
43ffi_ref_struct! {
44    /// An object representing a tool being used by a device with the
45    /// `DeviceCapability::TabletTool` capability.
46    ///
47    /// Tablet events generated by such a device are bound to a specific tool rather than
48    /// coming from the device directly. Depending on the hardware it is possible to track
49    /// the same physical tool across multiple `Device`s, see
50    /// [Tracking unique tools](https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html#tablet-serial-numbers).
51    struct TabletTool, ffi::libinput_tablet_tool, ffi::libinput_tablet_tool_ref, ffi::libinput_tablet_tool_unref
52}
53
54impl TabletTool {
55    ffi_func!(
56    /// Return the serial number of a tool.
57    ///
58    /// If the tool does not report a serial number, this function returns zero.
59    /// See [Tracking unique tools](https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html#tablet-serial-numbers) for details.
60    pub fn serial, ffi::libinput_tablet_tool_get_serial, u64);
61    ffi_func!(
62    /// Return the tool ID for a tool object.
63    ///
64    /// If nonzero, this number identifies the specific type of the tool with more
65    /// precision than the type returned in `tool_type`,
66    /// see [Vendor-specific tablet tool types](https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html#tablet-tool-types).
67    /// Not all tablets support a tool ID.
68    ///
69    /// Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom Cintiq
70    /// and Wacom Intuos Pro series.
71    pub fn tool_id, ffi::libinput_tablet_tool_get_tool_id, u64);
72
73    /// Return the tool type for a tool object,
74    /// see [Vendor-specific tablet tool types](https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html#tablet-tool-types)
75    /// for details.
76    ///
77    /// A return value of `None` means the tool type is not known.
78    pub fn tool_type(&self) -> Option<TabletToolType> {
79        match unsafe { ffi::libinput_tablet_tool_get_type(self.as_raw_mut()) } {
80            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_PEN => {
81                Some(TabletToolType::Pen)
82            }
83            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_ERASER => {
84                Some(TabletToolType::Eraser)
85            }
86            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_BRUSH => {
87                Some(TabletToolType::Brush)
88            }
89            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_PENCIL => {
90                Some(TabletToolType::Pencil)
91            }
92            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_AIRBRUSH => {
93                Some(TabletToolType::Airbrush)
94            }
95            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_MOUSE => {
96                Some(TabletToolType::Mouse)
97            }
98            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_LENS => {
99                Some(TabletToolType::Lens)
100            }
101            #[cfg(feature = "libinput_1_14")]
102            ffi::libinput_tablet_tool_type_LIBINPUT_TABLET_TOOL_TYPE_TOTEM => {
103                Some(TabletToolType::Totem)
104            }
105            _x => {
106                #[cfg(feature = "log")]
107                log::warn!("Unknown `TabletToolType` returned by libinput: {}", _x);
108                None
109            }
110        }
111    }
112
113    /// Check if a tablet tool has a button with the passed-in code (see linux/input.h).
114    pub fn has_button(&self, button: u32) -> bool {
115        unsafe { ffi::libinput_tablet_tool_has_button(self.as_raw_mut(), button) != 0 }
116    }
117
118    ffi_func!(
119    /// Return whether the tablet tool supports distance.
120    pub fn has_distance, ffi::libinput_tablet_tool_has_distance, bool);
121    ffi_func!(
122    /// Return whether the tablet tool supports pressure.
123    pub fn has_pressure, ffi::libinput_tablet_tool_has_pressure, bool);
124    ffi_func!(
125    /// Return whether the tablet tool supports z-rotation.v
126    pub fn has_rotation, ffi::libinput_tablet_tool_has_rotation, bool);
127    ffi_func!(
128    /// Return whether the tablet tool has a slider axis.
129    pub fn has_slider, ffi::libinput_tablet_tool_has_slider, bool);
130    ffi_func!(
131    /// Return whether the tablet tool supports tilt.
132    pub fn has_tilt, ffi::libinput_tablet_tool_has_tilt, bool);
133    ffi_func!(
134    /// Return whether the tablet tool has a relative wheel.
135    pub fn has_wheel, ffi::libinput_tablet_tool_has_wheel, bool);
136    ffi_func!(
137    /// Returns `true` if the physical tool can be uniquely identified by libinput, or
138    /// `false` otherwise.
139    ///
140    /// If a tool can be uniquely identified, keeping a reference to the tool allows
141    /// tracking the tool across proximity out sequences and across compatible tablets.
142    /// See [Tracking unique tools](https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html#tablet-serial-numbers)
143    /// for more details.
144    pub fn is_unique, ffi::libinput_tablet_tool_is_unique, bool);
145    #[cfg(feature = "libinput_1_14")]
146    ffi_func!(
147    /// Returns whether the tablet tool has a ellipsis major and minor.
148    ///
149    /// Where the underlying hardware only supports one of either major or minor,
150    /// libinput emulated the other axis as a cicular contact, i.e. major == minor
151    /// for all values of major.
152    pub fn tablet_tool_has_size, ffi::libinput_tablet_tool_has_size, bool);
153}
input/event/tablet_tool/tool.rs

input/event/tablet_tool/
tool.rs
