[PATCH v2] 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.

Changes since v1:
  - Reuse leave events for this purpose. This meant one had to be added
    on wl_touch.

Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
---
 protocol/wayland.xml | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 83df68a..84ce850 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1665,6 +1665,19 @@
 
 	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, the pairing button release will not be
+	emitted, clients should undo the effect of those pressed
+	buttons and forget about their state.
       </description>
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
@@ -1699,6 +1712,14 @@
 	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, most commonly due to input being actively taken away
+        or being redirected into this surface (eg. popups), either
+        state must be expected to be received separately. If no such
+        input redirection happened in between, the same surface that
+        received the "pressed" state is expected to receive the
+        "released" state too.
       </description>
 
       <arg name="serial" type="uint"/>
@@ -1798,6 +1819,17 @@
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	There are circumstances that force a focus switch, possibly
+	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, the pairing key release will not be
+	emitted, clients should undo the effect of those pressed
+	pressed and forget about their state.
       </description>
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
@@ -1816,6 +1848,14 @@
 	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, most commonly due to input being actively taken away
+        or being redirected into this surface (eg. popups), either
+        state must be expected to be received separately. If no such
+        input redirection happened in between, the same surface that
+        received the "pressed" state is expected to receive the
+        "released" state too.
       </description>
 
       <arg name="serial" type="uint"/>
@@ -1938,6 +1978,25 @@
     <request name="release" type="destructor" since="3">
       <description summary="release the touch object"/>
     </request>
+
+    <!-- Version 5 additions -->
+
+    <event name="leave" since="5">
+      <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="2">
-- 
2.5.0