libwacom
Wacom model identification library
 All Files Functions Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Enumerations | Functions
libwacom.h File Reference
#include <stdint.h>
#include <stdio.h>

Go to the source code of this file.

Macros

#define _LIBWACOM_H_
 
#define LIBWACOM_DEPRECATED
 
#define WACOM_STYLUS_FALLBACK_ID   0xfffff
 
#define WACOM_ERASER_FALLBACK_ID   0xffffe
 

Typedefs

typedef struct _WacomDevice WacomDevice
 
typedef struct _WacomMatch WacomMatch
 
typedef struct _WacomStylus WacomStylus
 
typedef struct _WacomError WacomError
 
typedef struct _WacomDeviceDatabase WacomDeviceDatabase
 

Enumerations

enum  WacomErrorCode {
  WERROR_NONE, WERROR_BAD_ALLOC, WERROR_INVALID_PATH, WERROR_INVALID_DB,
  WERROR_BAD_ACCESS, WERROR_UNKNOWN_MODEL
}
 Possible error codes. More...
 
enum  WacomBusType { WBUSTYPE_UNKNOWN, WBUSTYPE_USB, WBUSTYPE_SERIAL, WBUSTYPE_BLUETOOTH }
 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
}
 Classes of devices. More...
 
enum  WacomStylusType {
  WSTYLUS_UNKNOWN, WSTYLUS_GENERAL, WSTYLUS_INKING, WSTYLUS_AIRBRUSH,
  WSTYLUS_CLASSIC, WSTYLUS_MARKER, WSTYLUS_STROKE, WSTYLUS_PUCK
}
 Class of stylus. 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

WacomErrorlibwacom_error_new (void)
 Allocate a new structure for error reporting. More...
 
void libwacom_error_free (WacomError **error)
 Free the error and associated memory. More...
 
enum WacomErrorCode libwacom_error_get_code (WacomError *error)
 
const char * libwacom_error_get_message (WacomError *error)
 
WacomDeviceDatabaselibwacom_database_new (void)
 Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions. More...
 
WacomDeviceDatabaselibwacom_database_new_for_path (const char *datadir)
 Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions, from the prefix path passes. More...
 
void libwacom_database_destroy (WacomDeviceDatabase *db)
 Free all memory used by the database. 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...
 
WacomClass libwacom_get_class (const WacomDevice *device)
 
const char * libwacom_get_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)
 
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...
 
const int * libwacom_get_supported_styli (const WacomDevice *device, int *num_styli)
 
int libwacom_has_ring (const WacomDevice *device)
 
int libwacom_has_ring2 (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 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)
 
const WacomStyluslibwacom_stylus_get_for_id (const WacomDeviceDatabase *db, int id)
 Get the WacomStylus for the given tool ID. More...
 
int libwacom_stylus_get_id (const WacomStylus *stylus)
 
const char * libwacom_stylus_get_name (const WacomStylus *stylus)
 
int libwacom_stylus_get_num_buttons (const WacomStylus *stylus)
 
int libwacom_stylus_has_eraser (const WacomStylus *stylus)
 
int libwacom_stylus_is_eraser (const WacomStylus *stylus)
 
int libwacom_stylus_has_lens (const WacomStylus *stylus)
 
WacomStylusType libwacom_stylus_get_type (const WacomStylus *stylus)
 
void libwacom_print_stylus_description (int fd, const WacomStylus *stylus)
 Print the description of this stylus to the given file. More...
 
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)
 

Macro Definition Documentation

#define _LIBWACOM_H_
#define LIBWACOM_DEPRECATED
#define WACOM_ERASER_FALLBACK_ID   0xffffe
#define WACOM_STYLUS_FALLBACK_ID   0xfffff

Typedef Documentation

typedef struct _WacomDevice WacomDevice
typedef struct _WacomDeviceDatabase WacomDeviceDatabase
typedef struct _WacomError WacomError
typedef struct _WacomMatch WacomMatch
typedef struct _WacomStylus WacomStylus

Enumeration Type Documentation

Bus types for tablets.

Enumerator
WBUSTYPE_UNKNOWN 

Unknown/unsupported bus type.

WBUSTYPE_USB 

USB tablet.

WBUSTYPE_SERIAL 

Serial tablet.

WBUSTYPE_BLUETOOTH 

Bluetooth tablet.

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 
enum WacomClass

Classes of devices.

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".

Enumerator
WCOMPARE_NORMAL 

compare the device only

WCOMPARE_MATCHES 

compare all possible matches too

Possible error codes.

Enumerator
WERROR_NONE 

No error has occured.

WERROR_BAD_ALLOC 

Allocation error.

WERROR_INVALID_PATH 

A path specified is invalid.

WERROR_INVALID_DB 

The passed DB is invalid.

WERROR_BAD_ACCESS 

Invalid permissions to access the path.

WERROR_UNKNOWN_MODEL 

Unsupported/unknown device.

Enumerator
WFALLBACK_NONE 
WFALLBACK_GENERIC 

Tablet integration.

Enumerator
WACOM_DEVICE_INTEGRATED_NONE 
WACOM_DEVICE_INTEGRATED_DISPLAY 
WACOM_DEVICE_INTEGRATED_SYSTEM 
Enumerator
WACOM_STATUS_LED_UNAVAILABLE 
WACOM_STATUS_LED_RING 
WACOM_STATUS_LED_RING2 
WACOM_STATUS_LED_TOUCHSTRIP 
WACOM_STATUS_LED_TOUCHSTRIP2 

Class of stylus.

Enumerator
WSTYLUS_UNKNOWN 
WSTYLUS_GENERAL 
WSTYLUS_INKING 
WSTYLUS_AIRBRUSH 
WSTYLUS_CLASSIC 
WSTYLUS_MARKER 
WSTYLUS_STROKE 
WSTYLUS_PUCK 

Function Documentation

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
void libwacom_database_destroy ( WacomDeviceDatabase db)

Free all memory used by the database.

Parameters
dbA Tablet and Stylus database.
WacomDeviceDatabase* libwacom_database_new ( void  )

Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions.

Returns
A new database or NULL on error.
WacomDeviceDatabase* libwacom_database_new_for_path ( const char *  datadir)

Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions, from the prefix path passes.

This is only useful for diagnostics applications.

Returns
A new database or NULL on error.
void libwacom_destroy ( WacomDevice device)

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

Parameters
deviceThe device to delete
void libwacom_error_free ( WacomError **  error)

Free the error and associated memory.

Resets error to NULL.

Parameters
errorA reference to a error struct.
See Also
libwacom_error_new
enum WacomErrorCode libwacom_error_get_code ( WacomError error)
Returns
The code for this error.
const char* libwacom_error_get_message ( WacomError error)
Returns
A human-readable message for this error
WacomError* libwacom_error_new ( void  )

Allocate a new structure for error reporting.

Returns
A newly allocated error structure or NULL if the allocation failed.
WacomBusType libwacom_get_bustype ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The bustype of this device.
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
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
WacomClass libwacom_get_class ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The class of the device
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
WacomIntegrationFlags libwacom_get_integration_flags ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the integration flags for the device
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
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.
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!
const char* libwacom_get_name ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The human-readable name for this device
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
int libwacom_get_num_strips ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
the number of touch strips on the tablet otherwise
int libwacom_get_product_id ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The numeric product ID for this device
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
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
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
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
const int* libwacom_get_supported_styli ( const WacomDevice device,
int *  num_styli 
)
Parameters
deviceThe tablet to query
num_styliReturn location for the number of listed styli
Returns
an array of Styli IDs supported by the device
int libwacom_get_vendor_id ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
The numeric vendor ID for this device
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
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
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
int libwacom_has_stylus ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device supports styli or zero otherwise
int libwacom_has_touch ( const WacomDevice device)
Parameters
deviceThe tablet to query
Returns
non-zero if the device supports touch or zero otherwise
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.
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)
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 of freed. Use free() to free the list.
WacomBusType libwacom_match_get_bustype ( const WacomMatch match)
const char* libwacom_match_get_match_string ( const WacomMatch match)
uint32_t libwacom_match_get_product_id ( const WacomMatch match)
uint32_t libwacom_match_get_vendor_id ( const WacomMatch match)
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.
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.
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.

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.
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.
void libwacom_print_stylus_description ( int  fd,
const WacomStylus stylus 
)

Print the description of this stylus to the given file.

Parameters
fdThe file descriptor
stylusThe stylus to print the description for.
const WacomStylus* libwacom_stylus_get_for_id ( const WacomDeviceDatabase db,
int  id 
)

Get the WacomStylus for the given tool ID.

Parameters
dbA Tablet and Stylus database.
idThe Tool ID for this stylus
Returns
A WacomStylus representing the stylus. Do not free.
int libwacom_stylus_get_id ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
the ID of the tool
const char* libwacom_stylus_get_name ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
The name of the stylus
int libwacom_stylus_get_num_buttons ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
The number of buttons on the stylus
WacomStylusType libwacom_stylus_get_type ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
The type of stylus
int libwacom_stylus_has_eraser ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
Whether the stylus has an eraser
int libwacom_stylus_has_lens ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
Whether the stylus has a lens
int libwacom_stylus_is_eraser ( const WacomStylus stylus)
Parameters
stylusThe stylus to query
Returns
Whether the stylus is actually an eraser