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

Submitted by Carlos Garnacho on Jan. 27, 2017, 5:46 p.m.

Details

Message ID 20170127174658.631-1-carlosg@gnome.org
State New
Headers show
Series "protocol: Define further the behavior of input on the presence of grabs" ( rev: 3 ) in Wayland

Not browsing as part of any series.

Commit Message

Carlos Garnacho Jan. 27, 2017, 5:46 p.m.
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@gnome.org>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
---

 Changes since v3: Applied wording improvements from Yong Bakos, added
   the clarification suggested by Daniel, and made wl_touch.leave part of
   wl_touch.frame as suggested by Jonas (and that was the intended behavior).

   Also went ahead and bumped wl_seat version again to 7, since this is not
   1.13 material.

 protocol/wayland.xml | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 2 deletions(-)

Patch hide | download patch | download mbox

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 29b63be..7be23ec 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1651,7 +1651,7 @@ 
     </request>
    </interface>
 
-  <interface name="wl_seat" version="6">
+  <interface name="wl_seat" version="7">
     <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
@@ -1839,6 +1839,23 @@ 
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	While a pointer will not usually leave a surface while a button
+	is pressed, there are circumstances where this event may occur,
+	such as:
+
+	- When a popup is shown by this 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
+	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"/>
@@ -1880,6 +1897,10 @@ 
 	kernel's event code list. All other button codes above 0xFFFF are
 	currently undefined but may be used in future versions of this
 	protocol.
+
+	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"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2127,6 +2148,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 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 paired
+	key release events on this surface, and clients must undo their
+	internal 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"/>
@@ -2145,6 +2177,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"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2194,7 +2230,7 @@ 
     </event>
   </interface>
 
-  <interface name="wl_touch" version="6">
+  <interface name="wl_touch" version="7">
     <description summary="touchscreen input device">
       The wl_touch interface represents a touchscreen
       associated with a seat.
@@ -2226,6 +2262,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"/>
@@ -2336,6 +2376,30 @@ 
       <arg name="id" type="int" summary="the unique ID of this touch point"/>
       <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
     </event>
+
+    <!-- Version 7 additions -->
+
+    <event name="leave" since="7">
+      <description summary="leave event">
+	Notification that this touch point is no longer focused on a
+	certain surface. This event does not occur on its own. It is
+	sent before a wl_touch.frame event.
+
+	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 another client.
+	- When a drag-and-drop operation is initiated from this or
+	  any other surface.
+
+	This event will only be emitted on objects of version 6 or
+	higher, older clients will receive a wl_touch.up event per
+	remaining touchpoint instead.
+      </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">

Comments

Hi all,

I noticed that this patch did not land yet. I added to CC everyone who
commented on the v3 I believe.

Is this still relevant?


Thanks,
pq

On Fri, 27 Jan 2017 18:46:58 +0100
Carlos Garnacho <carlosg@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@gnome.org>
> Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
> ---
> 
>  Changes since v3: Applied wording improvements from Yong Bakos, added
>    the clarification suggested by Daniel, and made wl_touch.leave part of
>    wl_touch.frame as suggested by Jonas (and that was the intended behavior).
> 
>    Also went ahead and bumped wl_seat version again to 7, since this is not
>    1.13 material.
> 
>  protocol/wayland.xml | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 66 insertions(+), 2 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 29b63be..7be23ec 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1651,7 +1651,7 @@
>      </request>
>     </interface>
>  
> -  <interface name="wl_seat" version="6">
> +  <interface name="wl_seat" version="7">
>      <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
> @@ -1839,6 +1839,23 @@
>  
>  	The leave notification is sent before the enter notification
>  	for the new focus.
> +
> +	While a pointer will not usually leave a surface while a button
> +	is pressed, there are circumstances where this event may occur,
> +	such as:
> +
> +	- When a popup is shown by this 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
> +	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"/>
> @@ -1880,6 +1897,10 @@
>  	kernel's event code list. All other button codes above 0xFFFF are
>  	currently undefined but may be used in future versions of this
>  	protocol.
> +
> +	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"/>
>        <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> @@ -2127,6 +2148,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 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 paired
> +	key release events on this surface, and clients must undo their
> +	internal 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"/>
> @@ -2145,6 +2177,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"/>
>        <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> @@ -2194,7 +2230,7 @@
>      </event>
>    </interface>
>  
> -  <interface name="wl_touch" version="6">
> +  <interface name="wl_touch" version="7">
>      <description summary="touchscreen input device">
>        The wl_touch interface represents a touchscreen
>        associated with a seat.
> @@ -2226,6 +2262,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"/>
> @@ -2336,6 +2376,30 @@
>        <arg name="id" type="int" summary="the unique ID of this touch point"/>
>        <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
>      </event>
> +
> +    <!-- Version 7 additions -->
> +
> +    <event name="leave" since="7">
> +      <description summary="leave event">
> +	Notification that this touch point is no longer focused on a
> +	certain surface. This event does not occur on its own. It is
> +	sent before a wl_touch.frame event.
> +
> +	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 another client.
> +	- When a drag-and-drop operation is initiated from this or
> +	  any other surface.
> +
> +	This event will only be emitted on objects of version 6 or
> +	higher, older clients will receive a wl_touch.up event per
> +	remaining touchpoint instead.
> +      </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">
On Thu, Jan 17, 2019 at 05:27:44PM +0200, Pekka Paalanen wrote:
> Hi all,
> 
> I noticed that this patch did not land yet. I added to CC everyone who
> commented on the v3 I believe.
> 
> Is this still relevant?

I'd say it's good clarifications, and making it possible to "leave"
touch points is still more correct than "up":ing or "cancel":ing them.

Just one minor comment about wording below.

> 
> 
> Thanks,
> pq
> 
> On Fri, 27 Jan 2017 18:46:58 +0100
> Carlos Garnacho <carlosg@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@gnome.org>
> > Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
> > ---
> > 
> >  Changes since v3: Applied wording improvements from Yong Bakos, added
> >    the clarification suggested by Daniel, and made wl_touch.leave part of
> >    wl_touch.frame as suggested by Jonas (and that was the intended behavior).
> > 
> >    Also went ahead and bumped wl_seat version again to 7, since this is not
> >    1.13 material.
> > 
> >  protocol/wayland.xml | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++--
> >  1 file changed, 66 insertions(+), 2 deletions(-)
> > 
> > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > index 29b63be..7be23ec 100644
> > --- a/protocol/wayland.xml
> > +++ b/protocol/wayland.xml
> > @@ -1651,7 +1651,7 @@
> >      </request>
> >     </interface>
> >  
> > -  <interface name="wl_seat" version="6">
> > +  <interface name="wl_seat" version="7">
> >      <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
> > @@ -1839,6 +1839,23 @@
> >  
> >  	The leave notification is sent before the enter notification
> >  	for the new focus.
> > +
> > +	While a pointer will not usually leave a surface while a button
> > +	is pressed, there are circumstances where this event may occur,
> > +	such as:
> > +
> > +	- When a popup is shown by this 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
> > +	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.

Clients can't "must" receive anything, a compositor either will or it
wont. Also is the "all other input evets from the seat" intentional? Or
should it be "all other pointer events from that seat"?


Jonas

> >        </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"/>
> > @@ -1880,6 +1897,10 @@
> >  	kernel's event code list. All other button codes above 0xFFFF are
> >  	currently undefined but may be used in future versions of this
> >  	protocol.
> > +
> > +	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"/>
> >        <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> > @@ -2127,6 +2148,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 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 paired
> > +	key release events on this surface, and clients must undo their
> > +	internal 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"/>
> > @@ -2145,6 +2177,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"/>
> >        <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> > @@ -2194,7 +2230,7 @@
> >      </event>
> >    </interface>
> >  
> > -  <interface name="wl_touch" version="6">
> > +  <interface name="wl_touch" version="7">
> >      <description summary="touchscreen input device">
> >        The wl_touch interface represents a touchscreen
> >        associated with a seat.
> > @@ -2226,6 +2262,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"/>
> > @@ -2336,6 +2376,30 @@
> >        <arg name="id" type="int" summary="the unique ID of this touch point"/>
> >        <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
> >      </event>
> > +
> > +    <!-- Version 7 additions -->
> > +
> > +    <event name="leave" since="7">
> > +      <description summary="leave event">
> > +	Notification that this touch point is no longer focused on a
> > +	certain surface. This event does not occur on its own. It is
> > +	sent before a wl_touch.frame event.
> > +
> > +	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 another client.
> > +	- When a drag-and-drop operation is initiated from this or
> > +	  any other surface.
> > +
> > +	This event will only be emitted on objects of version 6 or
> > +	higher, older clients will receive a wl_touch.up event per
> > +	remaining touchpoint instead.
> > +      </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">
>