[PATCH v2 wayland] protocol: specify behavior of get_pointer when capabilities change

[Peter Hutterer]

Also applies to touch/keyboard

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
Changes to v1:
- make it clear that from the next version onwards sending events to an
  earlier wl_pointer object is a no-no.

 protocol/wayland.xml | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 7ca5049..471c1fe 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1396,6 +1396,30 @@
 	This is emitted whenever a seat gains or loses the pointer,
 	keyboard or touch capabilities.  The argument is a capability
 	enum containing the complete set of capabilities this seat has.
+
+	When the pointer capability is added, a client may create a
+	wl_pointer object using the wl_seat.get_pointer request. This object
+	will receive pointer events until the capability is removed in the
+	future.
+
+	When the pointer capability is removed, a client should destroy the
+	wl_pointer objects associated with the seat where the capability was
+	removed, using the wl_pointer.release request. No further pointer
+	events will be received on these objects.
+
+	If a seat regains the pointer capability and a client has a pointer
+	object obtained previously, that object may start sending pointer
+	events. This behavior was implemented in some compositors supporting
+	version 5 or less of the wl_seat interface and is considered a
+	misinterpretation of the intended behavior.
+	This behavior must not be relied upon by the client. A compositor
+	implementing version 6 or later of the wl_seat or wl_pointer
+	interface must not send events to a wl_pointer object created
+	before the most recent event notifying the client of an added
+	pointer capability.
+
+	The above behavior also applies to wl_keyboard and wl_touch with the
+	keyboard and touch capabilities, respectively.
       </description>
       <arg name="capabilities" type="uint" enum="capability"/>
     </event>
@@ -1406,7 +1430,9 @@
 	for this seat.
 
 	This request only takes effect if the seat has the pointer
-	capability.
+	capability, or has had the pointer capability in the past.
+	It is a protocol violation to issue this request on a seat that has
+	never had the pointer capability.
       </description>
       <arg name="id" type="new_id" interface="wl_pointer"/>
     </request>
@@ -1417,7 +1443,9 @@
 	for this seat.
 
 	This request only takes effect if the seat has the keyboard
-	capability.
+	capability, or has had the keyboard capability in the past.
+	It is a protocol violation to issue this request on a seat that has
+	never had the keyboard capability.
       </description>
       <arg name="id" type="new_id" interface="wl_keyboard"/>
     </request>
@@ -1428,7 +1456,9 @@
 	for this seat.
 
 	This request only takes effect if the seat has the touch
-	capability.
+	capability, or has had the touch capability in the past.
+	It is a protocol violation to issue this request on a seat that has
+	never had the touch capability.
       </description>
       <arg name="id" type="new_id" interface="wl_touch"/>
     </request>
-- 
2.5.0