fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-02-04 12:50:33 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve the tablet documentation

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2015-07-09 14:11:17 +10:00
parent b45fe45b1c
commit e14d1a08a4
1 changed files with 31 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
src/libinput.h
View file

@ -155,15 +155,20 @@ enum libinput_tablet_axis {
/**
* @ingroup device
*
* An object representing a tool being used by the device. It must have the @ref
* An object representing a tool being used by a device with the @ref
* LIBINPUT_DEVICE_CAP_TABLET capability.
*
* Tablet events generated by such a device are bound to a specific tool
* rather than coming from the device directly. Depending on the hardware it
* is possible to track the same physical tool across multiple
* struct libinput_device devices.
*/
struct libinput_tool;
/**
* @ingroup device
*
* Available tool types for a device. It must have the @ref
* Available tool types for a device with the @ref
* LIBINPUT_DEVICE_CAP_TABLET capability. The tool type defines the default
* usage of the tool as advertised by the manufacturer. Multiple different
* physical tools may share the same tool type, e.g. a Wacom Classic Pen,
@ -196,6 +201,14 @@ enum libinput_tool_type {
*
* The state of proximity for a tool on a device. The device must have the @ref
* LIBINPUT_DEVICE_CAP_TABLET capability.
*
* The proximity of a tool is a binary state signalling whether the tool is
* within detectable distance of the tablet device. A tool that is out of
* proximity cannot generate events.
*
* On some hardware a tool goes out of proximity when it ceases to touch the
* surface. On other hardware, the tool is still detectable within a short
* distance (a few cm) off the surface.
*/
enum libinput_tool_proximity_state {
LIBINPUT_TOOL_PROXIMITY_OUT = 0,
@ -248,6 +261,12 @@ enum libinput_event_type {
*/
LIBINPUT_EVENT_TOUCH_FRAME,
/**
* One or more axes have changed state on a device with the @ref
* LIBINPUT_DEVICE_CAP_TABLET capability. This event is only sent
* when the tool is in proximity, see @ref
* LIBINPUT_EVENT_TABLET_PROXIMITY for details.
*/
LIBINPUT_EVENT_TABLET_AXIS = 600,
/**
* Signals that a tool has come in or out of proximity of a device with
@ -257,9 +276,9 @@ enum libinput_event_type {
* and these values may be extracted from them in the same way they are
* with @ref LIBINPUT_EVENT_TABLET_AXIS events.
*
* Some tools may always be in proximity. For these tools, events with
* state @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref
* LIBINPUT_EVENT_DEVICE_ADDED, and likewise events with state @ref
* Some tools may always be in proximity. For these tools, events of
* type @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref
* LIBINPUT_EVENT_DEVICE_ADDED, and events of type @ref
* LIBINPUT_TOOL_PROXIMITY_OUT are sent only once before @ref
* LIBINPUT_EVENT_DEVICE_REMOVED.
*
@ -268,10 +287,10 @@ enum libinput_event_type {
* event.
*
* When a tool goes out of proximity, the value of every axis should be
* assumed to have a value of 0 and any buttons that are currently held
* assumed to have an undefined state and any buttons that are currently held
* down on the stylus are marked as released. Button release events for
* each button that was held down on the stylus are sent before the
* initial proximity out event.
* proximity out event.
*/
LIBINPUT_EVENT_TABLET_PROXIMITY,
LIBINPUT_EVENT_TABLET_BUTTON,
@ -1292,7 +1311,7 @@ libinput_event_tablet_axis_has_changed(struct libinput_event_tablet *event,
* 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.
* respective axis value into a different coordinate space.
* - @ref LIBINPUT_TABLET_AXIS_DISTANCE - The distance from the tablet's
* sensor, normalized from 0 to 1
* - @ref LIBINPUT_TABLET_AXIS_PRESSURE - The current pressure being applied on
@ -1316,6 +1335,10 @@ libinput_event_tablet_axis_has_changed(struct libinput_event_tablet *event,
* 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 @ref 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.
*
* @param event The libinput tablet event
* @param axis The axis to retrieve the value of
* @return The current value of the the axis