Lib.rs

A database of information about graphics tablets.

This crate provides static information about graphics tablets (Wacom, Huion, XP-Pen, Ugee, etc.) that cannot be obtained from the kernel device itself such as:

• is the given tablet integrated into a display or a system (i.e. a laptop display)
• which axes and buttons are available on a given tool. The kernel exports all possible axes across all possible tools on a tablet.
• which tools are available on a given tablet
• obtaining a detailed (SVG) and rough (top/bottom/left/right) layout of the button positions

A physical tablet is not required for querying information about tablet. This crate does not affect the functionality of a tablet. It's a wrapper around a set of text files that describe a tablet and never actually looks at the device itself beyond (maybe) extracting the device's name and ids from /sys.

This crate is tablet-vendor-agnostic and (in theory) platform-agnostic. Support for platforms other than Linux is untested.

Tablets, Styli, Buttons, Rings, Dials, Strips

A tablet as seen by this crate refers to the physical tablet that is connected to the host via one of the supported BusTypes.

Many tablets have Buttons and almost all tablets support Styli, the notable exception being those resembling a Remote, e.g. the Wacom ExpressKey Remote.

A tablet may also have additional Features:

• a [Ring] is a ring-shaped feature providing absolute finger position, see e.g. the Wacom Intuos Pro series
• a [Dial] is a dial or wheel-shaped feature providing relative input data, see e.g. the Huion Inspiroy 2S or the Huion Inspiroy Dial 2
• a touch [Strip] strip providing absolute finger position, see e.g. the Wacom Intuos 3.

A tablet may have more than one feature (e.g. two rings) and more than one feature type (e.g. a ring and two strips).

Modes and Mode Toggles

Features may be logically associated with a [Button]. For example the Wacom Intuos Pro series has one button inside the [Ring]. This button is physically independent of the ring but often associated with the "modes" of the ring (and other buttons). This button is referred to as "mode toggle button".

Such a mode may allow assigning different actions to the feature depending on the current mode. This crate only provides information about which button is logically associated with the feature (see [Feature::buttons()]) and the number of modes expected on this tablet ([Feature::num_modes()]).

On Linux, the modes are typically tied to the LEDs on the device and pressing the button associated with the feature will iterate and/or toggle the respective LED.

Some tablets have more than one mode toggle button - on those tablets each button is expected to switch to one specific mode. On tablets with one mode switch button the button is typically expected to cycle modes.

Examples

The most common use is to query information about a tablet that exists locally:

// A cache with default include paths
let cache = Cache::new()?;
for entry in std::fs::read_dir("/dev/input").unwrap().flatten() {
    // Extract the information from a local tablet
    let info = TabletInfo::new_from_path(&entry.path())?;
    // Find that tablet in the cache
    for tablet in cache.iter().filter(|t| *t == &info) {
        println!("{:?}: {}", entry.path(), tablet.name());
    }
}

But it's also possible to simply filter on other information if no device is present:

// A cache with default include paths
let cache = Cache::new()?;
for tablet in cache.iter().filter(|t| t.bustype() == BusType::Bluetooth) {
        println!("{} is a supported Bluetooth tablet", tablet.name());
}

See the [CacheBuilder] for cases where non-default include paths are needed.

Relationship to libwacom

This crate aims to be equivalent to libwacom. Some of libwacom's deprecated APIs are not present here, others provide a different structure but the set of information is the same.