protocol: explicitly describe wl_keyboard state

And the allowed state transitions.

There has been some confusion regarding which state transitions are
allowed. This change should clarify this.

Signed-off-by: Julian Orth <ju.orth@gmail.com>

1 files changed, 31 insertions, 7 deletions

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 091fa15..97ad2eb 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -2424,6 +2424,16 @@
     <description summary="keyboard input device">
       The wl_keyboard interface represents one or more keyboards
       associated with a seat.
+
+      Each wl_keyboard has the following logical state:
+
+      - an active surface (possibly null),
+      - the keys currently logically down,
+      - the active modifiers,
+      - the active group.
+
+      By default, the active surface is null, the keys currently logically down
+      are empty, the active modifiers and the active group are 0.
     </description>
 
     <enum name="keymap_format">
@@ -2458,10 +2468,15 @@
 
 	The compositor must send the wl_keyboard.modifiers event after this
 	event.
+
+	In the wl_keyboard logical state, this event sets the active surface to
+	the surface argument and the keys currently logically down to the keys
+	in the keys argument. The compositor must not send this event if the
+	wl_keyboard already had an active surface immediately before this event.
       </description>
       <arg name="serial" type="uint" summary="serial number of the enter event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
-      <arg name="keys" type="array" summary="the currently pressed keys"/>
+      <arg name="keys" type="array" summary="the keys currently logically down"/>
     </event>
 
     <event name="leave">
@@ -2472,10 +2487,10 @@
 	The leave notification is sent before the enter notification
 	for the new focus.
 
-	After this event client must assume that no keys are pressed,
-	it must stop key repeating if there's some going on and until
-	it receives the next wl_keyboard.modifiers event, the client
-	must also assume no modifiers are active.
+	In the wl_keyboard logical state, this event resets all values to their
+	defaults. The compositor must not send this event if the active surface
+	of the wl_keyboard was not equal to the surface argument immediately
+	before this event.
       </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"/>
@@ -2501,8 +2516,14 @@
 	If this event produces a change in modifiers, then the resulting
 	wl_keyboard.modifiers event must be sent after this event.
 
-	The compositor must not send this event without a surface of the client
-	having keyboard focus.
+	In the wl_keyboard logical state, this event adds the key to the keys
+	currently logically down (if the state argument is pressed) or removes
+	the key from the keys currently logically down (if the state argument is
+	released). The compositor must not send this event if the wl_keyboard
+	did not have an active surface immediately before this event. The
+	compositor must not send this event if state is pressed (resp. released)
+	and the key was already logically down (resp. was not logically down)
+	immediately before this event.
       </description>
       <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2522,6 +2543,9 @@
 	valid until it receives the next wl_keyboard.modifiers event. In order to
 	reset the modifier state again, the compositor can send a
 	wl_keyboard.modifiers event with no pressed modifiers.
+
+	In the wl_keyboard logical state, this event updates the modifiers and
+	group.
       </description>
       <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
       <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>