fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-05-08 11:19:14 +02: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 * @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. * 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; struct libinput_tool;
/** /**
* @ingroup device * @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 * LIBINPUT_DEVICE_CAP_TABLET capability. The tool type defines the default
* usage of the tool as advertised by the manufacturer. Multiple different * 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, * 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 * The state of proximity for a tool on a device. The device must have the @ref
* LIBINPUT_DEVICE_CAP_TABLET capability. * 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 { enum libinput_tool_proximity_state {
LIBINPUT_TOOL_PROXIMITY_OUT = 0, LIBINPUT_TOOL_PROXIMITY_OUT = 0,
@ -248,6 +261,12 @@ enum libinput_event_type {
*/ */
LIBINPUT_EVENT_TOUCH_FRAME, 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, LIBINPUT_EVENT_TABLET_AXIS = 600,
/** /**
* Signals that a tool has come in or out of proximity of a device with * 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 * and these values may be extracted from them in the same way they are
* with @ref LIBINPUT_EVENT_TABLET_AXIS events. * with @ref LIBINPUT_EVENT_TABLET_AXIS events.
* *
* Some tools may always be in proximity. For these tools, events with * Some tools may always be in proximity. For these tools, events of
* state @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref * type @ref LIBINPUT_TOOL_PROXIMITY_IN are sent only once after @ref
* LIBINPUT_EVENT_DEVICE_ADDED, and likewise events with state @ref * LIBINPUT_EVENT_DEVICE_ADDED, and events of type @ref
* LIBINPUT_TOOL_PROXIMITY_OUT are sent only once before @ref * LIBINPUT_TOOL_PROXIMITY_OUT are sent only once before @ref
* LIBINPUT_EVENT_DEVICE_REMOVED. * LIBINPUT_EVENT_DEVICE_REMOVED.
* *
@ -268,10 +287,10 @@ enum libinput_event_type {
* event. * event.
* *
* When a tool goes out of proximity, the value of every axis should be * 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 * 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 * 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_PROXIMITY,
LIBINPUT_EVENT_TABLET_BUTTON, 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 * Y coordinates of the tablet tool, in mm from the top left corner of the
* tablet. Use libinput_event_tablet_get_x_transformed() and * tablet. Use libinput_event_tablet_get_x_transformed() and
* libinput_event_tablet_get_y_transformed() for transforming each * 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 * - @ref LIBINPUT_TABLET_AXIS_DISTANCE - The distance from the tablet's
* sensor, normalized from 0 to 1 * sensor, normalized from 0 to 1
* - @ref LIBINPUT_TABLET_AXIS_PRESSURE - The current pressure being applied on * - @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_event_tablet_axis_has_changed() returns 0 for that axis.
* libinput always includes all device axes in the event. * 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 event The libinput tablet event
* @param axis The axis to retrieve the value of * @param axis The axis to retrieve the value of
* @return The current value of the the axis * @return The current value of the the axis