Skip to content

Device Properties

Jump to bottom Edit New page
Jason Gerecke edited this page Jan 21, 2020 · 22 revisions

The xf86-input-wacom driver exposes a number of properties that may be used to monitor or modify its operation. These properties are used by tools like xsetwacom and the GNOME Control Center, and may be used by other applications as well. It is even possible to interact with these properties through shell scripts with the help of the xinput utility.

You will typically never need to directly interact with the driver properties unless you are writing your own control panel software. If you are looking to make adjustments to the driver's operation, we recommend you stick to using available control panels instead.

Note that not all of these properties may be available on a given system. Tools which interact with these properties should check to see which exist prior to trying to read or write to them.

Table of Contents

Reading, Writing, and Watching Properties

By Script

The xinput command (installed as part of the xorg-xinput package or similar) can be used to read, write, and watch properties through the command-line. Please read man xinput for specific information on how to use the command. Combined with some shell magic, this can be used to quickly hack together useful scripts.

Programmatically

The source code to the xinput command provides a good starting point for reading, writing, and watching properties programmatically. Its src/properties.c file will be of particular interest. Also worth reading are the following pages:

Properties by Function

Tablet Identification

Property Name Type R/W Description
Device Node Atom Read-only

Path to the event device node which this X device reads from.

This may be used, for example, to link individual X devices back into a single logical device that the user interacts with. It can also be used as a starting point to query other tools and libraries for additional device information.
Device Product ID Int32[2] Read-only

Vendor and Product ID for device.

Returns a pair of integers which contain VID:PID information. E.g. [0x056A, 0x00F8] for a Cintiq 24HD touch.

Tool Identification

Property Name Type R/W Description
Wacom Serial IDs Int32[5] Read-only

Serial number and tool type for pen currently and previously in prox.

Format of the values is [$TABLET_PID, $PREV_SERIAL, $PREV_TYPE, $CUR_SERIAL, $CUR_TYPE]. Comparing the previous and current IDs can be used to determine if the user has switched between pens. Not all tablet models are capable of retrieving tool serial and type information, and in such case generic values will be used instead.
Wacom Tool Type Atom Read-only

General class of tool represented by this device.

Possible values: STYLUS, ERASER, PAD, CURSOR, TOUCH

Tool Mapping

Property Name Type R/W Description
Coordinate Transformation Matrix Float[9] Read-Write

Restrict the pointer to a single monitor, window, or arbitrary region of the desktop.

This is a 9-element affine transformation matrix in row-major order which operates in normalized desktop space. The default value [1, 0, 0, 0, 1, 0, 0, 0, 1] is the identity transform and leaves the tablet mapped to the entire desktop. Detailed information on how to adjust this property can be found in the Dual and Multi-Monitor Set Up article.
Wacom Tablet Area Int32[4] Read-Write

Restrict the tablet's active area to a portion of the surface.

This property defines the active area of the tablet in tablet space with [$LEFT, $TOP, $RIGHT, $BOTTOM] coordinates. Setting the value to [-1, -1, -1, -1] will trigger the driver to reset the area if it had been changed (after which, the property can be read to discover the full area). The area may be adjusted for several reasons: to facilitate a "match-aspect-ratio" function, to use a limited portion of the tablet for ergonomic reasons, or for calibration of a display tablet.

It is important to note that the default $LEFT and $TOP coordinate may not be zero! Many display tablets are physically larger than the LCD assembly and have their active area reduced slightly by default to provide optimal tracking near the display edges.
Wacom Rotation Int8 Read-Write

Logically rotate the tablet coordinates.

Valid values are 0 (no rotation), 1 (rotate counter-clockwise), 2 (rotate clockwise), and 3 (rotate 180-degrees). If the user rotates a tablet e.g. clockwise, this value should be set to 2 to match. Note that some programs may leave this property unchanged and modify the Coordinate Transformation Matrix to achieve a similar result.

Tool Feel

Property Name Type R/W Description
Wacom Pressurecurve Int32[4] Read-Write

Defines how hard or soft the pen feels

This property defines a pair of control points that adjust the shape of a Bezier curve from (0,0) to (100,100). The default value [0, 0, 100, 100] results in a linear ramp from zero to full pressure. The pen can be made to have a softer feel by moving the control points toward (0, 100), firmer by moving them toward (100,0), or have an S-shaped response by moving the points in opposite directions.
Wacom Proximity Threshold Int32 Read-Write

Defines the distance at which a tool in relative mode can move the cursor.

Adjusting this distance allows you to change how far the pen or puck must be picked up from the tablet surface before it is treated as being out of prox. The pointer will only move in response to motion when the pen or puck is closer than this distance. A user may wish to change this value for ergonomic reasons. Values are in arbitrary tablet-distance units.
Wacom Pressure Threshold Int32 Read-Write

Defines the minimum pressure needed to trigger a click

Pressure is still reported below this threshold in case an application needs access to the data, but an actual left-click event (which is normally necessary to draw or interact with GUI elements) is not emitted until the pressure level is reached. Values are contained in a normalized 0-2048 pressure range.
Wacom Sample and Suppress Int32[2] Read-Write

Define data noise reduction parameters

The driver's two noise-reduction parameters can be controlled through this property. The first adjusts the minimum change that must occur in any value for it to not be ignored as noise. The second adjusts the number of previous samples that get averaged together prior to reporting.

Button Actions

Property Name Type R/W Description
Wacom Button Actions Atom[] Read-Only Look-up table mapping button number to action property
Wacom button action Int32[] Read-Write List of encoded actions to perform on button press

Pointer Acceleration

Property Name Type R/W Description
Device Accel Profile Int8 Read-Write
Device Accel Constant Deceleration Float Read-Write
Device Accel Adaptive Deceleration Float Read-Write
Device Accel Velocity Scaling Float Read-Write

Gestures

Property Name Type R/W Description
Wacom Hover Click Int8 Read-Write Set whether side-switch clicks require an accompanying tap
Wacom Enable Touch Gesture Int8 Read-Write Swap between driver-provided and desktop-provided gestures
Wacom Touch Gesture Parameters Int8[3] Read-Write Driver-provided gesture settings
Wacom Panscroll Threshold Int32 Read-Write Adjust distance pen must move for panscroll gesture to trigger

Misc.

Property Name Type R/W Description
Device Enabled Int8 Read-Write Completely enable or disable a device
Wacom Enable Touch Int8 Read-Write Disable touch input, or see if it is disabled by hardware
Wacom Pressure Recalibration Int8 Read-Write Adjust how worn-out pens are treated
Wacom Debug Levels Int8[2] Read-Write Adjust the amount and type of logging produced by the driver
Wacom Serial ID binding Int32 Read-Write

Bind the use of this device to a single pen.

Writing a serial number to this property will cause the driver to ignore events from pens that have a different serial number. The default value of 0 allows all pens to work with the device.

xf86-input-wacom wiki

Intro and the Future of xf86-input-wacom

Guides

Advanced

Historical Information

Clone this wiki locally