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

[Yong Bakos]

Hi Carlos,

> On Nov 23, 2016, at 9:32 AM, Carlos Garnacho <carlosg at gnome.org> wrote:
> 
> 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>

Some minor writing suggestions are inline below.


> ---
> 
> 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:

While a pointer will not usually leave a surface while a button is
pressed, there are circumstances where where this event may occur, such as:


> +
> +	- When a popup is shown by this or other client.

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
> +	pairing button release events on this surface, clients must undo

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"/>
> @@ -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.

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 pairing

paired

> +	key release events on this surface, clients must undo their internal

, and clients must...


> +	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.

or another client.


Regards,
yong


> +	- 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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel