libwacom
Wacom model identification library
libwacom devices

Functions to create and manage libwacom devices. More...

Typedefs

typedef struct _WacomDevice WacomDevice
 
typedef struct _WacomBuilder WacomBuilder
 
typedef struct _WacomMatch WacomMatch
 

Enumerations

enum  WacomBusType {
  WBUSTYPE_UNKNOWN , WBUSTYPE_USB , WBUSTYPE_SERIAL , WBUSTYPE_BLUETOOTH ,
  WBUSTYPE_I2C
}
 Bus types for tablets. More...
 
enum  WacomIntegrationFlags { WACOM_DEVICE_INTEGRATED_NONE = 0 , WACOM_DEVICE_INTEGRATED_DISPLAY = (1 << 0) , WACOM_DEVICE_INTEGRATED_SYSTEM = (1 << 1) }
 Tablet integration. More...
 
enum  WacomClass {
  WCLASS_UNKNOWN , WCLASS_INTUOS3 , WCLASS_INTUOS4 , WCLASS_INTUOS5 ,
  WCLASS_CINTIQ , WCLASS_BAMBOO , WCLASS_GRAPHIRE , WCLASS_ISDV4 ,
  WCLASS_INTUOS , WCLASS_INTUOS2 , WCLASS_PEN_DISPLAYS , WCLASS_REMOTE
}
 Classes of devices. More...
 
enum  WacomButtonFlags {
  WACOM_BUTTON_NONE = 0 , WACOM_BUTTON_POSITION_LEFT = (1 << 1) , WACOM_BUTTON_POSITION_RIGHT = (1 << 2) , WACOM_BUTTON_POSITION_TOP = (1 << 3) ,
  WACOM_BUTTON_POSITION_BOTTOM = (1 << 4) , WACOM_BUTTON_RING_MODESWITCH = (1 << 5) , WACOM_BUTTON_RING2_MODESWITCH = (1 << 6) , WACOM_BUTTON_TOUCHSTRIP_MODESWITCH = (1 << 7) ,
  WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH = (1 << 8) , WACOM_BUTTON_OLED = (1 << 9) , WACOM_BUTTON_DIAL_MODESWITCH = (1 << 10) , WACOM_BUTTON_DIAL2_MODESWITCH = (1 << 11) ,
  WACOM_BUTTON_MODESWITCH = (WACOM_BUTTON_RING_MODESWITCH | WACOM_BUTTON_RING2_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH | WACOM_BUTTON_DIAL_MODESWITCH | WACOM_BUTTON_DIAL2_MODESWITCH) , WACOM_BUTTON_DIRECTION = (WACOM_BUTTON_POSITION_LEFT | WACOM_BUTTON_POSITION_RIGHT | WACOM_BUTTON_POSITION_TOP | WACOM_BUTTON_POSITION_BOTTOM) , WACOM_BUTTON_RINGS_MODESWITCH = (WACOM_BUTTON_RING_MODESWITCH | WACOM_BUTTON_RING2_MODESWITCH) , WACOM_BUTTON_TOUCHSTRIPS_MODESWITCH = (WACOM_BUTTON_TOUCHSTRIP_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH) ,
  WACOM_BUTTON_DIALS_MODESWITCH = (WACOM_BUTTON_DIAL_MODESWITCH | WACOM_BUTTON_DIAL2_MODESWITCH)
}
 Capabilities of the various tablet buttons. More...
 
enum  WacomFallbackFlags { WFALLBACK_NONE = 0 , WFALLBACK_GENERIC = 1 }
 
enum  WacomCompareFlags { WCOMPARE_NORMAL = 0 , WCOMPARE_MATCHES = (1 << 1) }
 
enum  WacomStatusLEDs {
  WACOM_STATUS_LED_UNAVAILABLE = -1 , WACOM_STATUS_LED_RING = 0 , WACOM_STATUS_LED_RING2 = 1 , WACOM_STATUS_LED_TOUCHSTRIP = 2 ,
  WACOM_STATUS_LED_TOUCHSTRIP2 = 3
}
 

Functions

WacomDevicelibwacom_new_from_builder (const WacomDeviceDatabase *db, const WacomBuilder *builder, WacomFallbackFlags fallback, WacomError *error)
 Create a new device reference for the given builder. More...
 
WacomDevicelibwacom_new_from_path (const WacomDeviceDatabase *db, const char *path, WacomFallbackFlags fallback, WacomError *error)
 Create a new device reference from the given device path. More...
 
WacomDevicelibwacom_new_from_usbid (const WacomDeviceDatabase *db, int vendor_id, int product_id, WacomError *error)
 Create a new device reference from the given vendor/product IDs. More...
 
WacomDevicelibwacom_new_from_name (const WacomDeviceDatabase *db, const char *name, WacomError *error)
 Create a new device reference from the given name. More...
 
WacomDevice ** libwacom_list_devices_from_database (const WacomDeviceDatabase *db, WacomError *error)
 Returns the list of devices in the given database. More...
 
void libwacom_print_device_description (int fd, const WacomDevice *device)
 Print the description of this device to the given file. More...
 
void libwacom_destroy (WacomDevice *device)
 Remove the device and free all memory and references to it. More...
 
int libwacom_compare (const WacomDevice *a, const WacomDevice *b, WacomCompareFlags flags)
 Compare the two devices for equal-ness. More...
 
LIBWACOM_DEPRECATED WacomClass libwacom_get_class (const WacomDevice *device)
 
const char * libwacom_get_name (const WacomDevice *device)
 
const char * libwacom_get_model_name (const WacomDevice *device)
 
const char * libwacom_get_layout_filename (const WacomDevice *device)
 
int libwacom_get_vendor_id (const WacomDevice *device)
 
const char * libwacom_get_match (const WacomDevice *device)
 
const WacomMatch ** libwacom_get_matches (const WacomDevice *device)
 
const WacomMatchlibwacom_get_paired_device (const WacomDevice *device)
 Return the match string of the paired device for this device. More...
 
int libwacom_get_product_id (const WacomDevice *device)
 
int libwacom_get_width (const WacomDevice *device)
 Retrieve the width of the device. More...
 
int libwacom_get_height (const WacomDevice *device)
 Retrieve the height of the device. More...
 
int libwacom_has_stylus (const WacomDevice *device)
 
int libwacom_has_touch (const WacomDevice *device)
 
int libwacom_get_num_buttons (const WacomDevice *device)
 Tablet buttons are numbered 'A' through to 'A' + number of buttons. More...
 
int libwacom_get_num_keys (const WacomDevice *device)
 Tablet keys indices are numbered from zero. More...
 
int libwacom_has_ring (const WacomDevice *device) LIBWACOM_DEPRECATED
 
int libwacom_has_ring2 (const WacomDevice *device) LIBWACOM_DEPRECATED
 
int libwacom_get_num_rings (const WacomDevice *device)
 
int libwacom_has_touchswitch (const WacomDevice *device)
 
int libwacom_get_ring_num_modes (const WacomDevice *device)
 
int libwacom_get_ring2_num_modes (const WacomDevice *device)
 
int libwacom_get_num_strips (const WacomDevice *device)
 
int libwacom_get_strips_num_modes (const WacomDevice *device)
 
int libwacom_get_num_dials (const WacomDevice *device)
 
int libwacom_get_dial_num_modes (const WacomDevice *device)
 
int libwacom_get_dial2_num_modes (const WacomDevice *device)
 
const WacomStatusLEDslibwacom_get_status_leds (const WacomDevice *device, int *num_leds)
 
int libwacom_get_button_led_group (const WacomDevice *device, char button)
 
int libwacom_is_builtin (const WacomDevice *device) LIBWACOM_DEPRECATED
 
int libwacom_is_reversible (const WacomDevice *device)
 
WacomIntegrationFlags libwacom_get_integration_flags (const WacomDevice *device)
 
WacomBusType libwacom_get_bustype (const WacomDevice *device)
 
WacomButtonFlags libwacom_get_button_flag (const WacomDevice *device, char button)
 
int libwacom_get_button_evdev_code (const WacomDevice *device, char button)
 
const char * libwacom_match_get_name (const WacomMatch *match)
 
const char * libwacom_match_get_uniq (const WacomMatch *match)
 
WacomBusType libwacom_match_get_bustype (const WacomMatch *match)
 
uint32_t libwacom_match_get_product_id (const WacomMatch *match)
 
uint32_t libwacom_match_get_vendor_id (const WacomMatch *match)
 
const char * libwacom_match_get_match_string (const WacomMatch *match)
 

Detailed Description

Functions to create and manage libwacom devices.

Typedef Documentation

◆ WacomBuilder

typedef struct _WacomBuilder WacomBuilder

◆ WacomDevice

typedef struct _WacomDevice WacomDevice

◆ WacomMatch

typedef struct _WacomMatch WacomMatch

Enumeration Type Documentation

◆ WacomBusType

Bus types for tablets.

Enumerator
WBUSTYPE_UNKNOWN 

Unknown/unsupported bus type.

WBUSTYPE_USB 

USB tablet.

WBUSTYPE_SERIAL 

Serial tablet.

WBUSTYPE_BLUETOOTH 

Bluetooth tablet.

WBUSTYPE_I2C 

I2C tablet.

◆ WacomButtonFlags

Capabilities of the various tablet buttons.

Enumerator
WACOM_BUTTON_NONE 
WACOM_BUTTON_POSITION_LEFT 
WACOM_BUTTON_POSITION_RIGHT 
WACOM_BUTTON_POSITION_TOP 
WACOM_BUTTON_POSITION_BOTTOM 
WACOM_BUTTON_RING_MODESWITCH 
WACOM_BUTTON_RING2_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIP_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH 
WACOM_BUTTON_OLED 
WACOM_BUTTON_DIAL_MODESWITCH 
WACOM_BUTTON_DIAL2_MODESWITCH 
WACOM_BUTTON_MODESWITCH 
WACOM_BUTTON_DIRECTION 
WACOM_BUTTON_RINGS_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIPS_MODESWITCH 
WACOM_BUTTON_DIALS_MODESWITCH 

◆ WacomClass

enum WacomClass

Classes of devices.

Deprecated:
This enum should no longer be used. The classes are not fine-grained or reliable enough to be useful.
Enumerator
WCLASS_UNKNOWN 

Unknown/unsupported device class.

WCLASS_INTUOS3 

Any Intuos3 series.

WCLASS_INTUOS4 

Any Intuos4 series.

WCLASS_INTUOS5 

Any Intuos5 series.

WCLASS_CINTIQ 

Any Cintiq device.

WCLASS_BAMBOO 

Any Bamboo device.

WCLASS_GRAPHIRE 

Any Graphire device.

WCLASS_ISDV4 

Any serial ISDV4 device.

WCLASS_INTUOS 

Any Intuos series.

WCLASS_INTUOS2 

Any Intuos2 series.

WCLASS_PEN_DISPLAYS 

Any "interactive pen display".

WCLASS_REMOTE 

Any Wacom Remote.

◆ WacomCompareFlags

Enumerator
WCOMPARE_NORMAL 

compare the device only

WCOMPARE_MATCHES 

compare all possible matches too

◆ WacomFallbackFlags

Enumerator
WFALLBACK_NONE 
WFALLBACK_GENERIC 

◆ WacomIntegrationFlags

Tablet integration.

Enumerator
WACOM_DEVICE_INTEGRATED_NONE 
WACOM_DEVICE_INTEGRATED_DISPLAY 
WACOM_DEVICE_INTEGRATED_SYSTEM 

◆ WacomStatusLEDs

Enumerator
WACOM_STATUS_LED_UNAVAILABLE 
WACOM_STATUS_LED_RING 
WACOM_STATUS_LED_RING2 
WACOM_STATUS_LED_TOUCHSTRIP 
WACOM_STATUS_LED_TOUCHSTRIP2 

Function Documentation

◆ libwacom_compare()

int libwacom_compare ( const WacomDevice a,
const WacomDevice b,
WacomCompareFlags  flags 
)

Compare the two devices for equal-ness.

Parameters
aThe first device
bThe second device
flagsFlags to dictate what constitutes a match
Returns
0 if the devices are identical, nonzero otherwise

◆ libwacom_destroy()

void libwacom_destroy ( WacomDevice device)

Remove the device and free all memory and references to it.

Parameters
deviceThe device to delete

◆ libwacom_get_bustype()

WacomBusType libwacom_get_bustype ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The bustype of this device.

◆ libwacom_get_button_evdev_code()

int libwacom_get_button_evdev_code ( const WacomDevice device,
char  button 
)
Parameters
deviceThe tablet to query
buttonThe ID of the button to check for, between 'A' and 'Z'
Returns
The evdev event code sent when the button is pressed or 0 if unknown.

◆ libwacom_get_button_flag()

WacomButtonFlags libwacom_get_button_flag ( const WacomDevice device,
char  button 
)
Parameters
deviceThe tablet to query
buttonThe ID of the button to check for, between 'A' and 'Z'
Returns
a WacomButtonFlags with information about the button

◆ libwacom_get_button_led_group()

int libwacom_get_button_led_group ( const WacomDevice device,
char  button 
)
Parameters
deviceThe tablet to query
buttonThe ID of the button to check for, between 'A' and 'Z'
Returns
the status LED group id to use or -1 if no LED is available for the given tablet / button

◆ libwacom_get_class()

LIBWACOM_DEPRECATED WacomClass libwacom_get_class ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The class of the device
Deprecated:
This function should no longer be used. The classes are not fine-grained or reliable enough to be useful.

◆ libwacom_get_dial2_num_modes()

int libwacom_get_dial2_num_modes ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of modes for the second dial, if any

◆ libwacom_get_dial_num_modes()

int libwacom_get_dial_num_modes ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of modes for the dial, if any

◆ libwacom_get_height()

int libwacom_get_height ( const WacomDevice device)

Retrieve the height of the device.

This is the height of the usable area as advertised, not the total size of the physical tablet. For e.g. an Intuos4 6x9 this will return 6.

Parameters
deviceThe tablet to query
Returns
The width of this device in inches

◆ libwacom_get_integration_flags()

WacomIntegrationFlags libwacom_get_integration_flags ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the integration flags for the device

◆ libwacom_get_layout_filename()

const char* libwacom_get_layout_filename ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The full filename including path to the SVG layout of the device if available, or NULL otherwise

◆ libwacom_get_match()

const char* libwacom_get_match ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The current match string used for this device (if set) or the first match string in the tablet definition.

◆ libwacom_get_matches()

const WacomMatch** libwacom_get_matches ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
A pointer to the null-terminated list of possible matches for this device. Do not modify this pointer or any content!

◆ libwacom_get_model_name()

const char* libwacom_get_model_name ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The vendor-specific model name (e.g. CTE-650 for a Bamboo Fun), or NULL if none is set

◆ libwacom_get_name()

const char* libwacom_get_name ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The human-readable name for this device

◆ libwacom_get_num_buttons()

int libwacom_get_num_buttons ( const WacomDevice device)

Tablet buttons are numbered 'A' through to 'A' + number of buttons.

Parameters
deviceThe tablet to query
Returns
The number of buttons on the tablet

◆ libwacom_get_num_dials()

int libwacom_get_num_dials ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of rotary dials on the tablet otherwise

◆ libwacom_get_num_keys()

int libwacom_get_num_keys ( const WacomDevice device)

Tablet keys indices are numbered from zero.

Parameters
deviceThe tablet to query
Returns
The number of keys on the tablet

◆ libwacom_get_num_rings()

int libwacom_get_num_rings ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of touch rings on the tablet otherwise
Since
2.12

◆ libwacom_get_num_strips()

int libwacom_get_num_strips ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of touch strips on the tablet otherwise

◆ libwacom_get_paired_device()

const WacomMatch* libwacom_get_paired_device ( const WacomDevice device)

Return the match string of the paired device for this device.

A paired device is a device with a different match string but that shares the physical device with this device.

If the return value is NULL, no device is paired with this device or all paired devices have the same WacomMatch as this device.

The returned device may not be a libwacom device itself.

Parameters
deviceThe tablet to query
Returns
A pointer to paired device for this device. Do not modify this pointer or any content!

◆ libwacom_get_product_id()

int libwacom_get_product_id ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The numeric product ID for this device
Bug:
The return value is a signed int but libwacom_match_get_product_id() returns an unsigned int. This may cause compiler warning, but the effective range for product IDs is 16-bit only anyway.

◆ libwacom_get_ring2_num_modes()

int libwacom_get_ring2_num_modes ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of modes for the second touchring if it has a mode switch

◆ libwacom_get_ring_num_modes()

int libwacom_get_ring_num_modes ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of modes for the touchring if it has a mode switch

◆ libwacom_get_status_leds()

const WacomStatusLEDs* libwacom_get_status_leds ( const WacomDevice device,
int *  num_leds 
)
Parameters
deviceThe tablet to query
num_ledsReturn location for the number of supported status LEDs
Returns
an array of status LEDs supported by the device

◆ libwacom_get_strips_num_modes()

int libwacom_get_strips_num_modes ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of modes for each of the touchstrips if any

◆ libwacom_get_vendor_id()

int libwacom_get_vendor_id ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The numeric vendor ID for this device
Bug:
The return value is a signed int but libwacom_match_get_vendor_id() returns an unsigned int. This may cause compiler warnings, but the effective range for vendor IDs is 16-bit only anyway.

◆ libwacom_get_width()

int libwacom_get_width ( const WacomDevice device)

Retrieve the width of the device.

This is the width of the usable area as advertised, not the total size of the physical tablet. For e.g. an Intuos4 6x9 this will return 9.

Parameters
deviceThe tablet to query
Returns
The width of this device in inches

◆ libwacom_has_ring()

int libwacom_has_ring ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device has a touch ring or zero otherwise
Deprecated:
2.12 Use libwacom_get_num_rings() instead.

◆ libwacom_has_ring2()

int libwacom_has_ring2 ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device has a second touch ring or zero otherwise
Deprecated:
2.12 Use libwacom_get_num_rings() instead.

◆ libwacom_has_stylus()

int libwacom_has_stylus ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device supports styli or zero otherwise

◆ libwacom_has_touch()

int libwacom_has_touch ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device supports touch or zero otherwise

◆ libwacom_has_touchswitch()

int libwacom_has_touchswitch ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device has a touch switch or zero otherwise

◆ libwacom_is_builtin()

int libwacom_is_builtin ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device is built into the screen (ie a screen tablet) or zero if the device is an external tablet
Deprecated:
0.7 Use libwacom_get_integration_flags() instead.

◆ libwacom_is_reversible()

int libwacom_is_reversible ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device can be used left-handed (rotated 180 degrees)

◆ libwacom_list_devices_from_database()

WacomDevice** libwacom_list_devices_from_database ( const WacomDeviceDatabase db,
WacomError error 
)

Returns the list of devices in the given database.

Parameters
dbA device database
errorIf not NULL, set to the error if any occurs
Returns
A NULL terminated list of pointers to all the devices inside the database. The content of the list is owned by the database and should not be modified or freed. Use free() to free the list.

◆ libwacom_match_get_bustype()

WacomBusType libwacom_match_get_bustype ( const WacomMatch match)

◆ libwacom_match_get_match_string()

const char* libwacom_match_get_match_string ( const WacomMatch match)

◆ libwacom_match_get_name()

const char* libwacom_match_get_name ( const WacomMatch match)

◆ libwacom_match_get_product_id()

uint32_t libwacom_match_get_product_id ( const WacomMatch match)

◆ libwacom_match_get_uniq()

const char* libwacom_match_get_uniq ( const WacomMatch match)

◆ libwacom_match_get_vendor_id()

uint32_t libwacom_match_get_vendor_id ( const WacomMatch match)

◆ libwacom_new_from_builder()

WacomDevice* libwacom_new_from_builder ( const WacomDeviceDatabase db,
const WacomBuilder builder,
WacomFallbackFlags  fallback,
WacomError error 
)

Create a new device reference for the given builder.

In case of error, NULL is returned and the error is set to the appropriate value.

The behavior for unset values in the builder is as follows:

  • if the bus is WBUSTYPE_UNKNOWN but product and vendor ID are set (and optionally device name, match name, and/or uniq), all known bus types are tested until a match is found (if any)
  • if the device name is set but all other values are empty the behavior matches libwacom_new_from_name(), i.e. the name alone will be used as lookup
  • if the uniq is set but all other values are empty the only the uniq string will be used for lookup device is the first with a corresponding uniq match.
  • if one of vendor or product id is zero and the other one is nonzero, no match will be found and the fallback device (if requested) is returned
Parameters
dbA device database
builderA builder specifying the known fields for this device.
fallbackWhether we should create a generic if model is unknown
errorIf not NULL, set to the error if any occurs
Returns
A new reference to this device or NULL on error.

◆ libwacom_new_from_name()

WacomDevice* libwacom_new_from_name ( const WacomDeviceDatabase db,
const char *  name,
WacomError error 
)

Create a new device reference from the given name.

In case of error, NULL is returned and the error is set to the appropriate value.

Parameters
dbA device database
nameThe name identifying the device
errorIf not NULL, set to the error if any occurs
Returns
A new reference to this device or NULL on error.

◆ libwacom_new_from_path()

WacomDevice* libwacom_new_from_path ( const WacomDeviceDatabase db,
const char *  path,
WacomFallbackFlags  fallback,
WacomError error 
)

Create a new device reference from the given device path.

In case of error, NULL is returned and the error is set to the appropriate value.

Parameters
dbA device database
pathA device path in the form of e.g. /dev/input/event0
fallbackWhether we should create a generic if model is unknown
errorIf not NULL, set to the error if any occurs
Returns
A new reference to this device or NULL on errror.

◆ libwacom_new_from_usbid()

WacomDevice* libwacom_new_from_usbid ( const WacomDeviceDatabase db,
int  vendor_id,
int  product_id,
WacomError error 
)

Create a new device reference from the given vendor/product IDs.

In case of error, NULL is returned and the error is set to the appropriate value.

Note
The term "usbid" is misleading, this function will return devices with matching ids on the USB, Bluetooth or i2c bus.
Parameters
dbA device database
vendor_idThe vendor ID of the device
product_idThe product ID of the device
errorIf not NULL, set to the error if any occurs
Returns
A new reference to this device or NULL on errror.

◆ libwacom_print_device_description()

void libwacom_print_device_description ( int  fd,
const WacomDevice device 
)

Print the description of this device to the given file.

Parameters
fdThe file descriptor to print to
deviceThe device to print the description for.