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

[Carlos Garnacho]

Hey Daniel :),

On Tue, Nov 22, 2016 at 12:43 PM, Daniel Stone <daniel at fooishbar.org> wrote:
> 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 ...

Oh well... you're not alone, it's been in my backlog for a while too :).

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

Indeed, just explaining it thoroughly in one of the 2 events make
sense. I actually wonder if it could be explained generically for all
keyboard/pointer/touch (eg. a separate section), but it's probably
better anyway to state the per-interface specifics.

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

Yup, sounds wise, after all the client doesn't care that the focus
goes elsewhere, just about losing the focus itself.

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

Sounds good :), and thanks for bringing that again to the top of my
head, let me rescue the patch and reword as suggested.

Cheers,
  Carlos