Device Properties

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
  • Programmatically
• Properties by Function
  • Tablet Identification
  • Tool Identification
  • Tool Mapping
  • Tool Feel
  • Button Actions
  • Pointer Acceleration
  • Gestures
  • Misc.

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.

# List devices
$ xinput list

# List and read device properties
$ xinput list-props <id>

# Set an integer property
$ xinput set-int-prop <id> "<Property Name>" [8|16|32] <value> [<value> ...]

# Set a float property
$ xinput set-float-prop <id> "<Property Name>" <value> [<value> ...]

# Watch device properties
$ xinput watch-props <id>

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:

• man xlistdeviceproperties
• man xgetdeviceproperty
• man xchangedeviceproperty
• man xgetatomname
• http://who-t.blogspot.com/2008/10/device-properties-have-landed.html

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 coordinates 90° clockwise), 2 (rotate coordinates 90° counter-clockwise), and 3 (rotate coordinates 180°). Note that the value set here should mirror the physical rotation of the tablet to cancel it out. That is, if a tablet has been e.g. rotated counter-clockwise 90 degrees, this property should be set to 1. Some programs (notably the GNOME Control Center) may leave this property unchanged and instead modify the Coordinate Transformation Matrix property 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. This variable-length array contains the names of Atoms that themselves store the actions to perform when a button is pressed. The array index corresponds to the button number: the first value is the Atom describing the first button, the second value the second button, etc. Logical button numbers 4-7 are skipped for historical reasons and filled with the None Atom if present.
Wacom button action	Int32[]	Read-Write	List of encoded actions to perform on button press. This variable-length array contains an integer for each action that is to be performed when the button is pressed. Basic documentation of the encoding format can be found in the include/Xwacom.h header file.

Gestures

Property Name	Type	R/W	Description
Wacom Hover Click	Int8	Read-Write	Set whether side-switch clicks require an accompanying tap. Some users prefer that clicks of a pen side-switch only be registered when accompanied with a tap of the pen tip. This can be for accuracy reasons (pressing the switch without the tip in contact may cause the pen to move slightly in response to the force) or for ergonomic reasons (requiring a tap can reduce the chances of an accidental side-switch activation). Accompanying taps are required when this property is zero.
Wacom Enable Touch Gesture	Int8	Read-Write	Swap between driver-provided and desktop-provided gestures. The xf86-input-wacom driver includes a basic touch gesture recognition engine that is capable of performing right-click, scroll, and zoom gestures. These gestures may be useful on systems which do not have a desktop-provided gesture-recognition engine. Enabling the gestures with a non-zero value prevents the desktop from receiving multi-touch events, while disabling gestures with a zero value prevents the driver from using multi-touch events.
Wacom Touch Gesture Parameters	Int32[3]	Read-Write	Values adjusting the driver-provided gesture recognizer. This array of 3 integers controlls the following gesture properties: [$ZOOM_DISTANCE, $SCROLL_DISTANCE, $TAP_TIME]. Adjusting the zoom distance controls how far a pair of fingers must move apart to trigger the zoom gesture. Adjusting the scroll distance controls how far a pair of fingers must hove vertically or horizontally to trigger the scroll gesture. Adjusting the tap time controls how long the driver will wait for a second contact in double-click and right-click gestures.
Wacom Panscroll Threshold	Int32	Read-Write	Adjust distance pen must move for panscroll gesture to trigger.

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

Misc.

Property Name	Type	R/W	Description
Device Enabled	Int8	Read-Write	Completely enable or disable a device. The Xorg server uses this property to determine if a device should be used at all.
Wacom Enable Touch	Int8	Read-Write	Disable touch input through software. Touch can be disabled by toggling this property on a touch device. This may be preferable to toggling the Device Enabled property which is not used by any of our software and likely indicates the (semi-)permanent preference of the user or system.
Wacom Hardware Touch Switch	Int8	Read-Only	See if touch has been disabled in hardware. Several Wacom devices include switches or buttons that allow the user to disable touch input. The state of this switch can be read through this property.
Wacom Pressure Recalibration	Int8	Read-Write	Attempt to remove "pre-loaded" initial pressure from worn-out pens. Worn out pens may report a non-zero amount of pressure as soon as they come into proximity. The driver can attempt to account for this and re-scale the usable pressure range when it occurs. This automatic re-scaling can, however, cause problems in environments where users rapidly "stab" the display since the driver may not see a zero-pressure event prior to contact.
Wacom Debug Levels	Int8[2]	Read-Write	Adjust the amount and type of logging produced by the driver. Defines the log level for the two different logging domains in the driver [$TOOL_DBG_LEVEL, $TABLET_DBG_LEVEL]. The former controls debug logs for tool-specific information and the latter for device information. The default of [0, 0] disables debug logging. Debug logs are written to the standard Xorg log file.
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.