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_event * | libinput_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... | |
enum libinput_tool_tip_state | libinput_event_tablet_get_tip_state (struct libinput_event_tablet *event) |
Returns the new tip state of a tool from a tip 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... | |
uint64_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... | |
uint64_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
-
event The libinput tablet event axis The 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:
- LIBINPUT_TABLET_AXIS_REL_WHEEL - A relative wheel on the tool, similar or equivalent to a mouse wheel. The value is a delta from the device's previous position, in degrees. For all other axes, see libinput_event_tablet_get_axis_value() for details.
- Parameters
-
event The libinput tablet event axis The 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:
- LIBINPUT_TABLET_AXIS_REL_WHEEL - the returned value is the number of physical mouse wheel clicks. For all other axes, this function returns 0.
- Parameters
-
event The libinput tablet event axis The 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:
- LIBINPUT_TABLET_AXIS_X and LIBINPUT_TABLET_AXIS_Y - the X and Y coordinates of the tablet tool, in mm from the top left corner of the tablet. Use libinput_event_tablet_get_x_transformed() and libinput_event_tablet_get_y_transformed() for transforming each respective axis value into a different coordinate space.
- LIBINPUT_TABLET_AXIS_DISTANCE - The distance from the tablet's sensor, normalized from 0 to 1
- LIBINPUT_TABLET_AXIS_PRESSURE - The current pressure being applied on the tool in use, normalized from 0 to 1
- LIBINPUT_TABLET_AXIS_TILT_X and LIBINPUT_TABLET_AXIS_TILT_Y - normalized value between -1 and 1 that indicates the X or Y tilt of the tool
- LIBINPUT_TABLET_AXIS_ROTATION_Z - The z rotation of the tool in degrees, clockwise from the tool's logical neutral position. For the LIBINPUT_TOOL_TYPE_MOUSE and LIBINPUT_TOOL_TYPE_LENS tools the logical neutral position is pointing to the current logical north of the tablet. For the LIBINPUT_TOOL_TYPE_BRUSH tool, the logical neutral position is with the buttons pointing up.
- LIBINPUT_TABLET_AXIS_SLIDER - A slider on the tool, normalized from 0 to 1. e.g. the wheel-like tool on the Wacom Airbrush.
- LIBINPUT_TABLET_AXIS_REL_WHEEL - A relative wheel on the tool, similar or equivalent to a mouse wheel. The value is always 0, use libinput_event_tablet_get_axis_delta() instead.
- 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
-
event The libinput tablet event axis The 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
-
event The 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
-
event The 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
-
event The 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
-
event The libinput tablet event
- Returns
- The event time for this event
uint64_t libinput_event_tablet_get_time_usec | ( | struct libinput_event_tablet * | event | ) |
- Parameters
-
event The libinput tablet event
- Returns
- The event time for this event in microseconds
enum libinput_tool_tip_state libinput_event_tablet_get_tip_state | ( | struct libinput_event_tablet * | event | ) |
Returns the new tip state of a tool from a tip event.
Used to check whether or not a tool came in contact with the tablet surface or left contact with the tablet surface during an event of type LIBINPUT_EVENT_TABLET_TIP.
- Parameters
-
event The libinput tablet event
- Returns
- The new tip state of the tool from the event.
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
-
event The 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
-
event The libinput tablet event width The 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
-
event The libinput tablet event height The current output screen height
- Returns
- the current absolute y coordinate transformed to a screen coordinate
uint64_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
-
tool The libinput tool
- Returns
- The new tool serial triggering this event
uint64_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
-
tool The 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
-
tool The 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
-
tool The 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
-
tool The tool to check the axis capabilities of axis The 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
-
tool A tablet tool code button 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
-
tool The 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
-
tool The libinput tool user_data The 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
-
tool The tool to decrement the ref count of
- Returns
- NULL if the tool was destroyed otherwise the passed tool