Crate tabletdb 

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.

This crate currently uses the libwacom data files as data source. Note that these data files are not stable API and updating libwacom may cause this crate to stop working. We aim to remove this dependency in future versions.

Structs

Button

A button on a tablet.

ButtonIndex

A zero-based button index on a tablet

Cache

A cache of all tablets known to this crate at the time of building the cache.

CacheBuilder

Builder struct for a tablet Cache.

DeviceId

A USB device ID comprising a bus type, vendor id and product id

Dial

A relative dial

Eraser

An eraser is a tool intended for erasing.

EvdevCode

An evdev code of EV_KEY type (e.g. BTN_0, etc.)

Length

A physical length, e.g. the Tablet’s width or height.

Mouse

A mouse-like device

ProductId

A 16-bit Product ID

Ring

A ring providing absolute finger position, see e.g. the Wacom Intuos Pro series

Strip

A touch strip, see e.g. the Wacom Intuos 3

Stylus

A stylus describes one stylus-like tool available on a tablet.

StylusId

A stylus ID comprising a vendor and tool id

Tablet

Static information about a tablet.

TabletInfo

Info about a tablet.

ToolButton

A button on a tool

ToolId

A 32-bit Stylus ID.

VendorId

A 16-bit Vendor ID

Enums

Axis

A supported axis type

BusType

The bustype of this device

Error

Crate-specific errors

FeatureType

The type of an extra feature

FormFactor

Specifies how the tablet is integrated.

Location

The physical location of a button relative to the input area.

StylusType

An approximate description of the stylus type

Tool

A physical tool that may be used on a device.

Traits

Feature

ToolFeatures

Units

Helper trait to convert between crazy units and sensible ones.