From 72a1db68e24b9952d7716e9ba887fb8c6fa4d249 Mon Sep 17 00:00:00 2001 From: Peter Hutterer 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 --- 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 * not 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