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

[Daniel Stone]

Hi Carlos,

On 12 November 2015 at 12:31, 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.

Just over a year later. :\ I think I'd put this message into a tab to
review later, then at some point Chrome lost all my tabs and that was
one of them ...

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

The client _must_ either receive a release or a leave event in a
timely manner, and strictly before all other input events from that
seat.

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

Hm, to be honest, I'd just go with: 'Clients should note that
pressed/released events may not be paired; in some cases, a leave
event will be sent in lieu of a released event. See that event's
documentation for more details'.

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

I'd probably avoid specifically mentioning focus switching here.

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

Same comment as with wl_pointer's leave.

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

This looks fine to me, though is missing its counterpart comment in
wl_touch::down.

Would you be OK with those changes?

Cheers,
Daniel