[PATCH v3] 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>
---

v2: Reuse leave events for this purpose. This meant one had to be added
    on wl_touch.
v3: Improved wording (I hope!) largely inspired on the suggestions from
    Daniel Stone. Bumped wl_seat version to 6 for wl_touch.leave.

 protocol/wayland.xml | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 6c6d078..16fc0b3 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1669,7 +1669,7 @@
     </request>
    </interface>
 
-  <interface name="wl_seat" version="5">
+  <interface name="wl_seat" version="6">
     <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
@@ -1859,6 +1859,23 @@
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	Normally, a pointer will not leave a surface while there are
+	buttons pressed, there's however circumstances where this event
+	may be received in this situation, for example:
+
+	- When a popup is shown by this or other 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
+	pairing button release events on this surface, 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"/>
@@ -1893,6 +1910,10 @@
 	enter event.
         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_pointer.leave for more details.
       </description>
 
       <arg name="serial" type="uint" summary="serial number of the button event"/>
@@ -2136,6 +2157,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 other 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 pairing
+	key release events on this surface, 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"/>
@@ -2154,6 +2186,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"/>
@@ -2238,6 +2274,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"/>
@@ -2276,6 +2316,25 @@
     <request name="release" type="destructor" since="3">
       <description summary="release the touch object"/>
     </request>
+
+    <!-- Version 6 additions -->
+
+    <event name="leave" since="6">
+      <description summary="leave event">
+	Notification that this touch point is no longer focused on a
+	certain surface.
+
+	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 other client.
+	- When a drag-and-drop operation is initiated from this or
+	  any other surface.
+      </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