Tablet events

Events that come from tablet devices. More...

Data Structures

struct  libinput_event_tablet
 Tablet event representing an axis update, button press, or tool update. More...
 

Functions

struct libinput_eventlibinput_event_tablet_get_base_event (struct libinput_event_tablet *event)
 
int libinput_event_tablet_axis_has_changed (struct libinput_event_tablet *event, enum libinput_tablet_axis axis)
 Checks if an axis was updated in this event or return 0 otherwise. More...
 
double libinput_event_tablet_get_axis_value (struct libinput_event_tablet *event, enum libinput_tablet_axis axis)
 Return the axis value of a given axis for a tablet. More...
 
double libinput_event_tablet_get_axis_delta (struct libinput_event_tablet *event, enum libinput_tablet_axis axis)
 Return the delta for a given axis for a tablet. More...
 
double libinput_event_tablet_get_axis_delta_discrete (struct libinput_event_tablet *event, enum libinput_tablet_axis axis)
 Return the delta for a given axis for a tablet in discrete steps. More...
 
double libinput_event_tablet_get_x_transformed (struct libinput_event_tablet *event, uint32_t width)
 Return the current absolute x coordinate of the tablet event, transformed to screen coordinates. More...
 
double libinput_event_tablet_get_y_transformed (struct libinput_event_tablet *event, uint32_t height)
 Return the current absolute y coordinate of the tablet event, transformed to screen coordinates. More...
 
struct libinput_tool * libinput_event_tablet_get_tool (struct libinput_event_tablet *event)
 Returns the tool that was in use during this event. More...
 
enum libinput_tool_proximity_state libinput_event_tablet_get_proximity_state (struct libinput_event_tablet *event)
 Returns the new proximity state of a tool from a proximity event. More...
 
uint32_t libinput_event_tablet_get_button (struct libinput_event_tablet *event)
 Return the button that triggered this event. More...
 
enum libinput_button_state libinput_event_tablet_get_button_state (struct libinput_event_tablet *event)
 Return the button state of the event. More...
 
uint32_t libinput_event_tablet_get_seat_button_count (struct libinput_event_tablet *event)
 For the button of a LIBINPUT_EVENT_TABLET_BUTTON event, return the total number of buttons pressed on all devices on the associated seat after the the event was triggered. More...
 
uint32_t libinput_event_tablet_get_time (struct libinput_event_tablet *event)
 
uint64_t libinput_event_tablet_get_time_usec (struct libinput_event_tablet *event)
 
enum libinput_tool_type libinput_tool_get_type (struct libinput_tool *tool)
 Return the type of tool type for a tool object. More...
 
uint32_t libinput_tool_get_tool_id (struct libinput_tool *tool)
 Return the tool ID for a tool object. More...
 
struct libinput_tool * libinput_tool_ref (struct libinput_tool *tool)
 Increment the ref count of tool by one. More...
 
int libinput_tool_has_axis (struct libinput_tool *tool, enum libinput_tablet_axis axis)
 Return whether or not a tablet tool supports the specified axis. More...
 
int libinput_tool_has_button (struct libinput_tool *tool, uint32_t code)
 Check if a tablet tool has a button with the passed-in code (see linux/input.h). More...
 
struct libinput_tool * libinput_tool_unref (struct libinput_tool *tool)
 Decrement the ref count of tool by one. More...
 
uint32_t libinput_tool_get_serial (struct libinput_tool *tool)
 Return the serial number of a tool. More...
 
void * libinput_tool_get_user_data (struct libinput_tool *tool)
 Return the user data associated with a tool object. More...
 
void libinput_tool_set_user_data (struct libinput_tool *tool, void *user_data)
 Set the user data associated with a tool object. More...
 

Detailed Description

Events that come from tablet devices.

Function Documentation

int libinput_event_tablet_axis_has_changed ( struct libinput_event_tablet event,
enum libinput_tablet_axis  axis 
)

Checks if an axis was updated in this event or return 0 otherwise.

For tablet events that are not of type LIBINPUT_EVENT_TABLET_AXIS or type LIBINPUT_EVENT_TABLET_PROXIMITY, this function returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_AXIS and LIBINPUT_EVENT_TABLET_PROXIMITY.
Parameters
eventThe libinput tablet event
axisThe axis to check for updates
Returns
1 if the axis was updated or 0 otherwise
double libinput_event_tablet_get_axis_delta ( struct libinput_event_tablet event,
enum libinput_tablet_axis  axis 
)

Return the delta for a given axis for a tablet.

The interpretation of the value is axis-dependent:

Parameters
eventThe libinput tablet event
axisThe axis to retrieve the value of
Returns
The delta to the previous axis value
double libinput_event_tablet_get_axis_delta_discrete ( struct libinput_event_tablet event,
enum libinput_tablet_axis  axis 
)

Return the delta for a given axis for a tablet in discrete steps.

How a value translates into a discrete step depends on the axis:

Parameters
eventThe libinput tablet event
axisThe axis to retrieve the value of
Returns
The delta to the previous axis value in discrete steps
double libinput_event_tablet_get_axis_value ( struct libinput_event_tablet event,
enum libinput_tablet_axis  axis 
)

Return the axis value of a given axis for a tablet.

The interpretation of the value is dependent on the axis:

Note
This function may be called for a specific axis even if libinput_event_tablet_axis_has_changed() returns 0 for that axis. libinput always includes all device axes in the event.

If the event is of type LIBINPUT_EVENT_TABLET_PROXIMITY and the event is a proximity out event, the value returned is the last known value of the tool before it left proximity.

Parameters
eventThe libinput tablet event
axisThe axis to retrieve the value of
Returns
The current value of the the axis
struct libinput_event* libinput_event_tablet_get_base_event ( struct libinput_event_tablet event)
Returns
The generic libinput_event of this event
uint32_t libinput_event_tablet_get_button ( struct libinput_event_tablet event)

Return the button that triggered this event.

For tablet events that are not of type LIBINPUT_EVENT_TABLET_BUTTON, this function returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_BUTTON.
Parameters
eventThe libinput tablet event
Returns
the button triggering this event
enum libinput_button_state libinput_event_tablet_get_button_state ( struct libinput_event_tablet event)

Return the button state of the event.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_BUTTON.
Parameters
eventThe libinput tablet event
Returns
the button state triggering this event
enum libinput_tool_proximity_state libinput_event_tablet_get_proximity_state ( struct libinput_event_tablet event)

Returns the new proximity state of a tool from a proximity event.

Used to check whether or not a tool came in or out of proximity during an event of type LIBINPUT_EVENT_TABLET_PROXIMITY.

See Handling of proximity events for recommendations on proximity handling.

Parameters
eventThe libinput tablet event
Returns
The new proximity state of the tool from the event.
uint32_t libinput_event_tablet_get_seat_button_count ( struct libinput_event_tablet event)

For the button of a LIBINPUT_EVENT_TABLET_BUTTON event, return the total number of buttons pressed on all devices on the associated seat after the the event was triggered.

"

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_BUTTON. For other events, this function returns 0.
Returns
the seat wide pressed button count for the key of this event
uint32_t libinput_event_tablet_get_time ( struct libinput_event_tablet event)
Parameters
eventThe libinput tablet event
Returns
The event time for this event
uint64_t libinput_event_tablet_get_time_usec ( struct libinput_event_tablet event)
Parameters
eventThe libinput tablet event
Returns
The event time for this event in microseconds
struct libinput_tool* libinput_event_tablet_get_tool ( struct libinput_event_tablet event)

Returns the tool that was in use during this event.

By default, each tool will stay valid for as long as it is being used, and is destroyed when another tool comes into proximity. However, the lifetime of the tool may be extended by using libinput_tool_ref() to increment the reference count of the tool. This guarantees that whenever the tool comes back into proximity of the tablet, that the same structure will be used to represent the tool.

Note
On tablets where the serial number of tools is not reported, each tool cannot be guaranteed to be unique.
Parameters
eventThe libinput tablet event
Returns
The new tool triggering this event
double libinput_event_tablet_get_x_transformed ( struct libinput_event_tablet event,
uint32_t  width 
)

Return the current absolute x coordinate of the tablet event, transformed to screen coordinates.

Note
This function may be called for a specific axis even if libinput_event_tablet_axis_has_changed() returns 0 for that axis. libinput always includes all device axes in the event.
Parameters
eventThe libinput tablet event
widthThe current output screen width
Returns
the current absolute x coordinate transformed to a screen coordinate
double libinput_event_tablet_get_y_transformed ( struct libinput_event_tablet event,
uint32_t  height 
)

Return the current absolute y coordinate of the tablet event, transformed to screen coordinates.

Note
This function may be called for a specific axis even if libinput_event_tablet_axis_has_changed() returns 0 for that axis. libinput always includes all device axes in the event.
Parameters
eventThe libinput tablet event
heightThe current output screen height
Returns
the current absolute y coordinate transformed to a screen coordinate
uint32_t libinput_tool_get_serial ( struct libinput_tool *  tool)

Return the serial number of a tool.

Note
Not all tablets report a serial number along with the type of tool being used. If the hardware does not provide a unique serial number, the serial number is always 0.
Parameters
toolThe libinput tool
Returns
The new tool serial triggering this event
uint32_t libinput_tool_get_tool_id ( struct libinput_tool *  tool)

Return the tool ID for a tool object.

If nonzero, this number identifies the specific type of the tool with more precision than the type returned in libinput_tool_get_type(). Not all tablets support a tool ID.

Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom Cintiq and Wacom Intuos Pro series.

Parameters
toolThe libinput tool
Returns
The tool ID for this tool object or 0 if none is provided
See also
libinput_tool_get_type
enum libinput_tool_type libinput_tool_get_type ( struct libinput_tool *  tool)

Return the type of tool type for a tool object.

Parameters
toolThe libinput tool
Returns
The tool type for this tool object
See also
libinput_tool_get_tool_id
void* libinput_tool_get_user_data ( struct libinput_tool *  tool)

Return the user data associated with a tool object.

Parameters
toolThe libinput tool
Returns
The user data associated with the tool object
int libinput_tool_has_axis ( struct libinput_tool *  tool,
enum libinput_tablet_axis  axis 
)

Return whether or not a tablet tool supports the specified axis.

Parameters
toolThe tool to check the axis capabilities of
axisThe axis to check for support
Returns
Whether or not the axis is supported
int libinput_tool_has_button ( struct libinput_tool *  tool,
uint32_t  code 
)

Check if a tablet tool has a button with the passed-in code (see linux/input.h).

Parameters
toolA tablet tool
codebutton code to check for
Returns
1 if the tool supports this button code, 0 if it does not
struct libinput_tool* libinput_tool_ref ( struct libinput_tool *  tool)

Increment the ref count of tool by one.

Parameters
toolThe tool to increment the ref count of
Returns
The passed tool
void libinput_tool_set_user_data ( struct libinput_tool *  tool,
void *  user_data 
)

Set the user data associated with a tool object.

Parameters
toolThe libinput tool
user_dataThe user data to associate with the tool object
struct libinput_tool* libinput_tool_unref ( struct libinput_tool *  tool)

Decrement the ref count of tool by one.

When the ref count of tool reaches 0, the memory allocated for tool will be freed.

Parameters
toolThe tool to decrement the ref count of
Returns
NULL if the tool was destroyed otherwise the passed tool