[PATCH wayland v4] protocol: Define further the behavior of input on the presence of grabs

[Carlos Garnacho]

The leave events in the respective device interfaces has been further
documented so those can convey the necessary info when input is being
redirected out of their currently focused surface.

Only wl_touch is missing something semantically similar, a wl_touch.leave
event has been added so the touch interface can cope with such input
redirection situations on individual touchpoints.

Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>
---

 Changes since v3: Applied wording improvements from Yong Bakos, added
   the clarification suggested by Daniel, and made wl_touch.leave part of
   wl_touch.frame as suggested by Jonas (and that was the intended behavior).

   Also went ahead and bumped wl_seat version again to 7, since this is not
   1.13 material.

 protocol/wayland.xml | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 29b63be..7be23ec 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1651,7 +1651,7 @@
     </request>
    </interface>
 
-  <interface name="wl_seat" version="6">
+  <interface name="wl_seat" version="7">
     <description summary="group of input devices">
       A seat is a group of keyboards, pointer and touch devices. This
       object is published as a global during start up, or when such a
@@ -1839,6 +1839,23 @@
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	While a pointer will not usually leave a surface while a button
+	is pressed, there are circumstances where this event may occur,
+	such as:
+
+	- When a popup is shown by this or another client.
+	- When a drag-and-drop operation is initiated from this or
+	  any other surface.
+	- Other compositor-specific grabs, like pointer gestures.
+
+	In these situations, a leave event will be emitted with no
+	paired button release event on this surface, and clients must
+	undo their internal state related to the ongoing button presses.
+
+	Clients must either receive a release or a leave event in a
+	timely manner, and strictly before all other input events from
+	that seat.
       </description>
       <arg name="serial" type="uint" summary="serial number of the leave event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
@@ -1880,6 +1897,10 @@
 	kernel's event code list. All other button codes above 0xFFFF are
 	currently undefined but may be used in future versions of this
 	protocol.
+
+	Clients should note that pressed/released events may not be paired;
+	in some cases, a leave event will be sent in place of a released event.
+	See wl_pointer.leave for more details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the button event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2127,6 +2148,17 @@
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	There may be circumstances that force the keyboard focus to be taken
+	away from a surface while there are pressed keys, for example:
+
+	- When a popup is shown by this or another client.
+	- When a drag-and-drop operation is initiated from this or
+	  any other surface.
+
+	In these situations, a leave event will be emitted with no paired
+	key release events on this surface, and clients must undo their
+	internal state related to the ongoing key presses.
       </description>
       <arg name="serial" type="uint" summary="serial number of the leave event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
@@ -2145,6 +2177,10 @@
 	A key was pressed or released.
 	The time argument is a timestamp with millisecond
 	granularity, with an undefined base.
+
+	Clients should note that pressed/released events may not be paired;
+	in some cases, a leave event will be sent in place of a released event.
+	See wl_keyboard.leave for more details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2194,7 +2230,7 @@
     </event>
   </interface>
 
-  <interface name="wl_touch" version="6">
+  <interface name="wl_touch" version="7">
     <description summary="touchscreen input device">
       The wl_touch interface represents a touchscreen
       associated with a seat.
@@ -2226,6 +2262,10 @@
 	The touch point has disappeared. No further events will be sent for
 	this touch point and the touch point's ID is released and may be
 	reused in a future touch down event.
+
+	Clients should note that down/up events may not be paired;
+	in some cases, a leave event will be sent in place of a wl_touch.up
+	event. See wl_touch.leave for more details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the touch up event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2336,6 +2376,30 @@
       <arg name="id" type="int" summary="the unique ID of this touch point"/>
       <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
     </event>
+
+    <!-- Version 7 additions -->
+
+    <event name="leave" since="7">
+      <description summary="leave event">
+	Notification that this touch point is no longer focused on a
+	certain surface. This event does not occur on its own. It is
+	sent before a wl_touch.frame event.
+
+	Note that, because touch points are always implicitly grabbed,
+	this event will only be emitted when the touch point is taken
+	away from this surface through explicit means, for example:
+
+	- When a popup is shown by this or another client.
+	- When a drag-and-drop operation is initiated from this or
+	  any other surface.
+
+	This event will only be emitted on objects of version 6 or
+	higher, older clients will receive a wl_touch.up event per
+	remaining touchpoint instead.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="id" type="int" summary="the unique ID of this touch point"/>
+    </event>
   </interface>
 
   <interface name="wl_output" version="3">
-- 
2.9.3