tablet: a tip event can replace an axis event

When we're only dealing with BTN_TOUCH we can make the tip event independent
of the axis event. Now that we handle pressure thresholds to trigger tip state
this does not work, we'd have to send an axis event with the new pressure and
then a tip event. Since the pressure triggers the tip event this seems
disconnected.

Make the tip event officially capable of carrying axes. A caller can then
decide how to forward this to the next layer.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Jason Gerecke <jason.gerecke@wacom.com>

1 files changed, 26 insertions, 2 deletions

diff --git a/src/libinput.h b/src/libinput.h
index ab57b4cb..7b9236de 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -273,6 +273,10 @@ enum libinput_event_type {
 	 * changes from this initial state. It is possible for a tool to
 	 * enter and leave proximity without sending an event of type @ref
 	 * LIBINPUT_EVENT_TABLET_TOOL_AXIS.
+	 *
+	 * An event of type @ref LIBINPUT_EVENT_TABLET_TOOL_AXIS is sent
+	 * when the tip state does not change. See the documentation for
+	 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP for more details.
 	 */
 	LIBINPUT_EVENT_TABLET_TOOL_AXIS = 600,
 	/**
@@ -309,10 +313,30 @@ enum libinput_event_type {
 	 * LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for the tip down event, and
 	 * immediately before for the tip up event.
 	 *
-	 * If a button and/or axis state change occurs at the same time as a
-	 * tip state change, the order of events is device-dependent.
+	 * The decision when a tip touches the surface is device-dependent
+	 * and may be derived from pressure data or other means. If the tip
+	 * state is changed by axes changing state, the
+	 * @ref LIBINPUT_EVENT_TABLET_TOOL_TIP event includes the changed
+	 * axes and no additional axis event is sent for this state change.
+	 * In other words, a caller must look at both @ref
+	 * LIBINPUT_EVENT_TABLET_TOOL_AXIS and @ref
+	 * LIBINPUT_EVENT_TABLET_TOOL_TIP events to know the current state
+	 * of the axes.
+	 *
+	 * If a button state change occurs at the same time as a tip state
+	 * change, the order of events is device-dependent.
 	 */
 	LIBINPUT_EVENT_TABLET_TOOL_TIP,
+	/**
+	 * Signals that a tool has changed a logical button state on a
+	 * device with the @ref LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
+	 *
+	 * Button state changes occur on their own and do not include axis
+	 * state changes. If button and axis state changes occur within the
+	 * same logical hardware event, the order of the @ref
+	 * LIBINPUT_EVENT_TABLET_TOOL_BUTTON and @ref
+	 * LIBINPUT_EVENT_TABLET_TOOL_AXIS event is device-specific.
+	 */
 	LIBINPUT_EVENT_TABLET_TOOL_BUTTON,
 
 	LIBINPUT_EVENT_GESTURE_SWIPE_BEGIN = 800,