libwacom Wacom model identification library

Typedefs | Enumerations | Functions
libwacom devices

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

## Typedefs
typedef struct _WacomDevice | WacomDevice
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_MODESWITCH = (WACOM_BUTTON_RING_MODESWITCH | WACOM_BUTTON_RING2_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP2_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) }
| 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
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. More...
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. More...
WacomDevice * | libwacom_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 WacomMatch * | libwacom_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_has_ring (const WacomDevice *device)
int | libwacom_has_ring2 (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)
const WacomStatusLEDs * | libwacom_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)
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

## ◆ WacomDevice

typedef struct _WacomDevice WacomDevice

## ◆ WacomMatch

typedef struct _WacomMatch WacomMatch

## Enumeration Type Documentation

## ◆ WacomBusType

enum 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

enum 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_MODESWITCH |
WACOM_BUTTON_DIRECTION |
WACOM_BUTTON_RINGS_MODESWITCH |
WACOM_BUTTON_TOUCHSTRIPS_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

enum WacomCompareFlags

Enumerator
WCOMPARE_NORMAL | compare the device only
WCOMPARE_MATCHES | compare all possible matches too

## ◆ WacomFallbackFlags

enum WacomFallbackFlags

Enumerator
WFALLBACK_NONE |
WFALLBACK_GENERIC |

## ◆ WacomIntegrationFlags

enum WacomIntegrationFlags

Tablet integration.

Enumerator
WACOM_DEVICE_INTEGRATED_NONE |
WACOM_DEVICE_INTEGRATED_DISPLAY |
WACOM_DEVICE_INTEGRATED_SYSTEM |

## ◆ WacomStatusLEDs

enum 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

  a | The first device
  b | The second device
  flags | Flags 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

  device | The device to delete

## ◆ libwacom_get_bustype()

WacomBusType libwacom_get_bustype | ( | const WacomDevice * | device | ) |

Parameters

  device | The 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

  device | The tablet to query
  button | The 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

  device | The tablet to query
  button | The 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

  device | The tablet to query
  button | The 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

  device | The 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_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

  device | The tablet to query

Returns
  The width of this device in inches

## ◆ libwacom_get_integration_flags()

WacomIntegrationFlags libwacom_get_integration_flags | ( | const WacomDevice * | device | ) |

Parameters

  device | The tablet to query

Returns
  the integration flags for the device

## ◆ libwacom_get_layout_filename()

const char * libwacom_get_layout_filename | ( | const WacomDevice * | device | ) |

Parameters

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  device | The tablet to query

Returns
  The number of buttons on the tablet

## ◆ libwacom_get_num_strips()

int libwacom_get_num_strips | ( | const WacomDevice * | device | ) |

Parameters

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  device | The tablet to query
  num_leds | Return 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

  device | The 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

  device | The 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

  device | The tablet to query

Returns
  The width of this device in inches

## ◆ libwacom_has_ring()

int libwacom_has_ring | ( | const WacomDevice * | device | ) |

Parameters

  device | The tablet to query

Returns
  non-zero if the device has a touch ring or zero otherwise

## ◆ libwacom_has_ring2()

int libwacom_has_ring2 | ( | const WacomDevice * | device | ) |

Parameters

  device | The tablet to query

Returns
  non-zero if the device has a second touch ring or zero otherwise

## ◆ libwacom_has_stylus()

int libwacom_has_stylus | ( | const WacomDevice * | device | ) |

Parameters

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  device | The 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

  db | A device database
  error | If 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_vendor_id()

uint32_t libwacom_match_get_vendor_id | ( | const WacomMatch * | match | ) |

## ◆ 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

  db | A device database
  name | The name identifying the device
  error | If 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

  db | A device database
  path | A device path in the form of e.g. /dev/input/event0
  fallback | Whether we should create a generic if model is unknown
  error | If 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

  db | A device database
  vendor_id | The vendor ID of the device
  product_id | The product ID of the device
  error | If 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

  fd | The file descriptor to print to
  device | The device to print the description for.