Attachment 124567 Details for Bug 85879 – A draft of the interface

[patch] A draft of the interface

0001-touchpad-add-a-special-direct-touch-mode-for-the-inp.patch (text/plain), 12.73 KB, created by Peter Hutterer on 2016-06-17 05:57:22 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Peter Hutterer

Created: 2016-06-17 05:57:22 UTC

Size: 12.73 KB

patch

obsolete

>From 72a1db68e24b9952d7716e9ba887fb8c6fa4d249 Mon Sep 17 00:00:00 2001
>From: Peter Hutterer <peter.hutterer@who-t.net>
>Date: Fri, 17 Jun 2016 15:45:59 +1000
>Subject: [PATCH libinput] touchpad: add a special direct touch mode for the
> input of logograms
>
>Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
>---
> doc/Makefile.am               |   1 +
> doc/page-hierarchy.dox        |   1 +
> doc/touchpad-direct-touch.dox |  26 +++++
> src/libinput.c                |   3 +
> src/libinput.h                | 229 ++++++++++++++++++++++++++++++++++++++++++
> src/libinput.sym              |  13 +++
> 6 files changed, 273 insertions(+)
> create mode 100644 doc/touchpad-direct-touch.dox
>
>diff --git a/doc/Makefile.am b/doc/Makefile.am
>index eb5d3c0..685bf81 100644
>--- a/doc/Makefile.am
>+++ b/doc/Makefile.am
>@@ -24,6 +24,7 @@ header_files = \
> 	$(srcdir)/tapping.dox \
> 	$(srcdir)/test-suite.dox \
> 	$(srcdir)/tools.dox \
>+	$(srcdir)/touchpad-direct-touch.dox \
> 	$(srcdir)/touchpad-jumping-cursors.dox \
> 	$(srcdir)/touchpads.dox
> 
>diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox
>index 8455fca..44116ed 100644
>--- a/doc/page-hierarchy.dox
>+++ b/doc/page-hierarchy.dox
>@@ -9,6 +9,7 @@
> - @subpage t440_support
> - @subpage touchpad_jumping_cursor
> - @subpage absolute_coordinate_ranges
>+- @subpage touchpad_direct_touch
> 
> @page touchscreens Touchscreens
> 
>diff --git a/doc/touchpad-direct-touch.dox b/doc/touchpad-direct-touch.dox
>new file mode 100644
>index 0000000..c477644
>--- /dev/null
>+++ b/doc/touchpad-direct-touch.dox
>@@ -0,0 +1,26 @@
>+/**
>+@page touchpad_direct_touch Touch events on pointer devices
>+
>+libinput maps touchpads into the pointer device interface and maps touch
>+events into the respective pointer motion or scroll events. For some
>+specialized use-cases direct touch input from the touchpad is required. One
>+example is use of the touchpad surface as canvas to logograms that are not
>+otherwise easily accessible through the keyboard.
>+
>+The direct touch mode on touchpad devices relies on the touchpad being
>+switched into a custom mode via the function
>+libinput_device_config_tptouch_set_enabled(). Once the touchpad is in this
>+mode it will not generate further pointer events but only send direct touch
>+input that must be interpreted by the caller as such.
>+
>+While in direct touch mode the touchpad will disable advanced touchpad
>+features such as gestures, scrolling or clickfinger/software button areas.
>+Which features remain enabled is device-dependent.
>+
>+The protocol for touchpad direct touches is similar to the protocol used for
>+multi-touch devices and libinput will generally forwards multiple touches
>+as-is. On some devices where the accuracy of multiple touches on the
>+touchpad cannot be guaranteed, libinput may restrict the device to a single
>+touch.
>+
>+*/
>diff --git a/src/libinput.c b/src/libinput.c
>index 6ff4e9a..f10d866 100644
>--- a/src/libinput.c
>+++ b/src/libinput.c
>@@ -2586,6 +2586,9 @@ event_type_to_str(enum libinput_event_type type)
> 	CASE_RETURN_STRING(LIBINPUT_EVENT_GESTURE_PINCH_BEGIN);
> 	CASE_RETURN_STRING(LIBINPUT_EVENT_GESTURE_PINCH_UPDATE);
> 	CASE_RETURN_STRING(LIBINPUT_EVENT_GESTURE_PINCH_END);
>+	CASE_RETURN_STRING(LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN);
>+	CASE_RETURN_STRING(LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP);
>+	CASE_RETURN_STRING(LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION);
> 	case LIBINPUT_EVENT_NONE:
> 		abort();
> 	}
>diff --git a/src/libinput.h b/src/libinput.h
>index ed3eb7d..684ee4a 100644
>--- a/src/libinput.h
>+++ b/src/libinput.h
>@@ -401,6 +401,22 @@ enum libinput_event_type {
> 	LIBINPUT_EVENT_GESTURE_PINCH_BEGIN,
> 	LIBINPUT_EVENT_GESTURE_PINCH_UPDATE,
> 	LIBINPUT_EVENT_GESTURE_PINCH_END,
>+
>+	/**
>+	 * A touch down event on a touchpad device. See @ref
>+	 * touchpad_direct_touch for details.
>+	 */
>+	LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN = 900,
>+	/**
>+	 * A touch up event on a touchpad device. See @ref
>+	 * touchpad_direct_touch for details.
>+	 */
>+	LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP,
>+	/**
>+	 * A touch motion event on a touchpad device. See @ref
>+	 * touchpad_direct_touch for details.
>+	 */
>+	LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION,
> };
> 
> /**
>@@ -446,6 +462,7 @@ struct libinput_seat;
>  *
>  * The base event type. Use libinput_event_get_pointer_event() or similar to
>  * get the actual event type.
>+
>  *
>  * @warning Unlike other structs events are considered transient and
>  * <b>not</b> refcounted.
>@@ -513,6 +530,23 @@ struct libinput_event_tablet_tool;
> struct libinput_event_tablet_pad;
> 
> /**
>+ * @ingroup event_touchpad_touch
>+ * @struct libinput_event_touchpad_touch
>+ *
>+ * Touch event representing a touch down, move or up on a touchpad-like
>+ * device that was switched into direct mode. See @ref touchpad_direct_touch
>+ * for details.
>+ *
>+ * @note This event does NOT represent a normal touchpad input event.
>+ *
>+ * Valid event types for this event are
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN,
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION,
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP.
>+ */
>+struct libinput_event_touchpad_touch;
>+
>+/**
>  * @defgroup event Accessing and destruction of events
>  */
> 
>@@ -647,6 +681,17 @@ struct libinput_event_tablet_pad *
> libinput_event_get_tablet_pad_event(struct libinput_event *event);
> 
> /**
>+ * Return the touchpad touch event that is this input event. If the event type does not
>+ * match the touchpad touch event types, this function returns NULL.
>+ *
>+ * The inverse of this function is libinput_event_touchpad_touch_get_base_event().
>+ *
>+ * @return A touchpad touch event, or NULL for other events
>+ */
>+struct libinput_event_touchpad_touch *
>+libinput_event_get_touchpad_touch_event(struct libinput_event *event);
>+
>+/**
>  * @ingroup event
>  *
>  * Return the device event that is this input event. If the event type does
>@@ -2388,6 +2433,118 @@ uint64_t
> libinput_event_tablet_pad_get_time_usec(struct libinput_event_tablet_pad *event);
> 
> /**
>+ * @defgroup event_touchpad_touch Touchpad touch events
>+ *
>+ * Events from touchpad devices when switched into direct touch mode. See
>+ * @ref touchpad_direct_touch for details.
>+ *
>+ * @note This page does NOT describe normal touch events from touchpads.
>+ * These events are for a special and niche use-case, e.g. drawing of
>+ * logograms. For normal touchpad events see @ref event_pointer.
>+ */
>+
>+/**
>+ * @ingroup event_touchpad_touch
>+ *
>+ * @return The generic libinput_event of this event
>+ */
>+struct libinput_event *
>+libinput_event_touchpad_touch_get_base_event(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>+ * @ingroup event_touchpad_touch
>+ *
>+ * @note This is not a normal event from touchpads. See @ref
>+ * touchpad_direct_touch for details.
>+ *
>+ * @return The event time for this event
>+ */
>+uint32_t
>+libinput_event_touchpad_touch_get_time(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>+ * @ingroup event_touchpad_touch
>+ *
>+ * @note This is not a normal event from touchpads. See @ref
>+ * touchpad_direct_touch for details.
>+ *
>+ * @return The event time for this event in microseconds
>+ */
>+uint64_t
>+libinput_event_touchpad_touch_get_time_usec(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>+ * @ingroup event_touchpad_touch
>+ *
>+ * @note This is not a normal event from touchpads. See @ref
>+ * touchpad_direct_touch for details.
>+ *
>+ * Get the slot of this touch event. See the kernel's multitouch
>+ * protocol B documentation for more information. On single-touch touchpads
>+ * this function always returns 0.
>+ *
>+ * For events not of type @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN, @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP, @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION, this function returns 0.
>+ *
>+ * @note It is an application bug to call this function for events of type
>+ * other than @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN,
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP,
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION.
>+ *
>+ * @return The slot of this touchpad touch event
>+ */
>+uint32_t
>+libinput_event_touchpad_touch_get_slot(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>+ * @ingroup event_touchpad_touch
>+ *
>+ * @note This is not a normal event from touchpads. See @ref
>+ * touchpad_direct_touch for details.
>+ *
>+ * Return the current absolute x coordinate of the touch event, in mm from
>+ * the top left corner of the device.
>+ *
>+ * For events not of type @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN, @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION, this function returns 0.
>+ *
>+ * @note It is an application bug to call this function for events of type
>+ * other than @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN or @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION.
>+ *
>+ * @param event The libinput touchpad touch event
>+ * @return The current absolute x coordinate
>+ */
>+double
>+libinput_event_touchpad_touch_get_x(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>+ * @ingroup event_touch
>+ *
>+ * Return the current absolute y coordinate of the touch event, in mm from
>+ * the top left corner of the device.
>+ *
>+ * For events not of type @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN, @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION, this function returns 0.
>+ *
>+ * @note It is an application bug to call this function for events of type
>+ * other than @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN or @ref
>+ * LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION.
>+ *
>+ * @param event The libinput touchpad_touch event
>+ * @return The current absolute y coordinate
>+ */
>+double
>+libinput_event_touchpad_touch_get_y(
>+				struct libinput_event_touchpad_touch *event);
>+
>+/**
>  * @defgroup base Initialization and manipulation of libinput contexts
>  */
> 
>@@ -4754,6 +4911,78 @@ libinput_device_config_rotation_get_angle(struct libinput_device *device);
> unsigned int
> libinput_device_config_rotation_get_default_angle(struct libinput_device *device);
> 
>+/**
>+ * @ingroup config
>+ *
>+ * Returns non-zero if this touchpad-like device can be switched into a
>+ * direct touch mode. See @ref touchpad_direct_touch for details.
>+ *
>+ * @param device A device with the @ref LIBINPUT_DEVICE_CAP_POINTER
>+ * capability.
>+ * @return nonzero if the device can be switched to direct touch mode, zero
>+ * otherwise
>+ */
>+int
>+libinput_device_config_tptouch_is_available(struct libinput_device *device);
>+
>+/**
>+ * @ingroup config
>+ *
>+ * Possible states for the touchpad direct touch feature. See @ref
>+ * touchpad_direct_touch for details.
>+ */
>+enum libinput_config_tptouch_state {
>+	LIBINPUT_CONFIG_TOUCHPAD_TOUCH_DISABLED,
>+	LIBINPUT_CONFIG_TOUCHPAD_TOUCH_ENABLED,
>+};
>+
>+/**
>+ * @ingroup config
>+ *
>+ * Enable or disable the direct touch mode on a touchpad device. When
>+ * enabled, the touchpad stops sending normal pointer events and instead
>+ * acts like a direct touch input device, sending the events
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_DOWN,
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_MOTION, and
>+ * @ref LIBINPUT_EVENT_TOUCHPAD_TOUCH_UP.
>+ *
>+ * This usually means that touchpad functions such as two-finger scrolling
>+ * of physical software buttons are disabled while this mode is active.
>+ * See @ref touchpad_direct_touch for more details
>+ *
>+ * @note The selected state may not take effect immediately. The device may
>+ * require changing to a neutral state first before activating the new
>+ * method.
>+ *
>+ * Disabling the direct touch mode on a device that does not have a direct
>+ * touch mode always succeeds.
>+ */
>+enum libinput_config_status
>+libinput_device_config_tptouch_set_enabled(struct libinput_device *device,
>+					   enum libinput_config_tptouch_state state);
>+
>+/**
>+ * @ingroup config
>+ *
>+ * @retval LIBINPUT_CONFIG_TOUCHPAD_TOUCH_DISABLED touchpad direct touch
>+ * state is disabled
>+ * @retval LIBINPUT_CONFIG_TOUCHPAD_TOUCH_ENABLED touchpad direct touch
>+ * state is enabled
>+ */
>+enum libinput_config_tptouch_state
>+libinput_device_config_tptouch_get_enabled(struct libinput_device *device);
>+
>+/**
>+ * @ingroup config
>+ *
>+ * @retval LIBINPUT_CONFIG_DIRECTTOUCH_DISABLED touchpad direct touch state
>+ * is disabled by default
>+ * @retval LIBINPUT_CONFIG_DIRECTTOUCH_ENABLED touchpad direct touch state
>+ * is enabled by default
>+ */
>+enum libinput_config_tptouch_state
>+libinput_device_config_tptouch_get_default_enabled(struct libinput_device *device);
>+
> #ifdef __cplusplus
> }
> #endif
>diff --git a/src/libinput.sym b/src/libinput.sym
>index c6a0e4c..b05e46a 100644
>--- a/src/libinput.sym
>+++ b/src/libinput.sym
>@@ -259,3 +259,16 @@ LIBINPUT_1.4 {
> 	libinput_device_config_rotation_is_available;
> 	libinput_device_config_rotation_set_angle;
> } LIBINPUT_1.3;
>+
>+TOUCHPAD_TOUCH_SUPPORT {
>+	libinput_device_config_tptouch_get_default_enabled;
>+	libinput_device_config_tptouch_get_enabled;
>+	libinput_device_config_tptouch_set_enabled;
>+	libinput_event_get_touchpad_touch_event;
>+	libinput_event_touchpad_touch_get_base_event;
>+	libinput_event_touchpad_touch_get_slot;
>+	libinput_event_touchpad_touch_get_time;
>+	libinput_event_touchpad_touch_get_time_usec;
>+	libinput_event_touchpad_touch_get_x;
>+	libinput_event_touchpad_touch_get_y;
>+} LIBINPUT_1.4;
>-- 
>2.7.4
>

Actions: View | Splinter Review

Attachments on bug 85879: 124567

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.