From 824cea61e686a739034b95473e557a7c29e75a83 Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Tue, 13 Apr 2021 11:33:48 +1000
Subject: pointer-gestures: add hold gestures

Hold gestures merely denote "there are fingers on the touchpad but they are
not moving". As touchpad touches are generally fully abstracted, a client
cannot currently know when a user is interacting with the touchpad without
moving - no motion events will be sent in this case.

The two use-cases here are:
- hold-to-interact: where a hold gesture is active for some time
  a menu could pop up, or some object is selected, etc.
- hold-to-cancel: where e.g. kinetic scrolling is currently active, the start
  of a hold gesture can be used to stop the scroll

Since hold gestures by definition do not have movement, there is no need for
an "update" stage in the gesture.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 .../pointer-gestures-unstable-v1.xml               | 83 +++++++++++++++++++---
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml b/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml
index 3df578b..f92a116 100644
--- a/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml
+++ b/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml
@@ -1,14 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <protocol name="pointer_gestures_unstable_v1">
 
-  <interface name="zwp_pointer_gestures_v1" version="2">
+  <interface name="zwp_pointer_gestures_v1" version="3">
     <description summary="touchpad gestures">
       A global interface to provide semantic touchpad gestures for a given
       pointer.
 
-      Two gestures are currently supported: swipe and pinch.
-      All gestures follow a three-stage cycle: begin, update, end and
-      are identified by a unique id.
+      Three gestures are currently supported: swipe, pinch, and hold.
+      Pinch and swipe gestures follow a three-stage cycle: begin, update,
+      end, hold gestures follow a two-stage cycle: begin and end. All
+      gestures are identified by a unique id.
 
       Warning! The protocol described in this file is experimental and
       backward incompatible changes may be made. Backward compatible changes
@@ -42,10 +43,22 @@
 
     <request name="release" type="destructor" since="2">
       <description summary="destroy the pointer gesture object">
-	Destroy the pointer gesture object. Swipe and pinch objects created via this
-	gesture object remain valid.
+	Destroy the pointer gesture object. Swipe, pinch and hold objects
+	created via this gesture object remain valid.
       </description>
     </request>
+
+    <!-- Version 3 additions -->
+
+    <request name="get_hold_gesture" since="3">
+      <description summary="get hold gesture">
+	Create a hold gesture object. See the
+	wl_pointer_gesture_hold interface for details.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_pointer_gesture_hold_v1"/>
+      <arg name="pointer" type="object" interface="wl_pointer"/>
+    </request>
+
   </interface>
 
   <interface name="zwp_pointer_gesture_swipe_v1" version="2">
@@ -58,7 +71,7 @@
       implementation-dependent.
 
       A gesture consists of three stages: begin, update (optional) and end.
-      There cannot be multiple simultaneous pinch or swipe gestures on a
+      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
       same pointer/seat, how compositors prevent these situations is
       implementation-dependent.
 
@@ -121,7 +134,7 @@
       such a gesture is detected are implementation-dependent.
 
       A gesture consists of three stages: begin, update (optional) and end.
-      There cannot be multiple simultaneous pinch or swipe gestures on a
+      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
       same pointer/seat, how compositors prevent these situations is
       implementation-dependent.
 
@@ -181,6 +194,60 @@
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
       <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
     </event>
+
   </interface>
 
+  <interface name="zwp_pointer_gesture_hold_v1" version="3">
+    <description summary="a hold gesture object">
+      A hold gesture object notifies a client about a single- or
+      multi-finger hold gesture detected on an indirect input device such as
+      a touchpad. The gesture is usually initiated by one or more fingers
+      being held down without significant movement. The precise conditions
+      of when such a gesture is detected are implementation-dependent.
+
+      In particular, this gesture may be used to cancel kinetic scrolling.
+
+      A hold gesture consists of two stages: begin and end. Unlike pinch and
+      swipe there is no update stage.
+      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
+      same pointer/seat, how compositors prevent these situations is
+      implementation-dependent.
+
+      A gesture may be cancelled by the compositor or the hardware.
+      Clients should not consider performing permanent or irreversible
+      actions until the end of a gesture has been received.
+    </description>
+
+    <request name="destroy" type="destructor" since="3">
+      <description summary="destroy the hold gesture object"/>
+    </request>
+
+    <event name="begin" since="3">
+      <description summary="multi-finger hold begin">
+	This event is sent when a hold gesture is detected on the device.
+      </description>
+      <arg name="serial" type="uint"/>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="fingers" type="uint" summary="number of fingers"/>
+    </event>
+
+    <event name="end" since="3">
+      <description summary="multi-finger hold end">
+	This event is sent when a hold gesture ceases to
+	be valid. This may happen when the holding fingers are lifted or
+	the gesture is cancelled, for example if the fingers move past an
+	implementation-defined threshold, the finger count changes or the hold
+	gesture changes into a different type of gesture.
+
+	When a gesture is cancelled, the client may need to undo state changes
+	caused by this gesture. What causes a gesture to be cancelled is
+	implementation-dependent.
+      </description>
+      <arg name="serial" type="uint"/>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+      <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
+    </event>
+
+  </interface>
 </protocol>
-- 
cgit v1.2.3