[PATCH wayland-protocols v4 6/7] xdg-shell: Make xdg_popup non-grabbing by default

[Quentin Glidic]

On 24/06/2016 08:47, Jonas Ådahl wrote:
> Turn xdg_popup into plain temporary child surfaces without any grabbing
> or mapping order requirements by default.
>
> In order to create grabbing popup chains, a new request 'grab' is
> introduced which enables more or less the same semantics and
> requirements as xdg_popup previously had related to grabbing, stacking
> and mapping order.
>
> This enables using xdg_popup for creating tooltips and other user
> interface elements that does not want to take an explicit grab.
>
> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> Signed-off-by: Mike Blumenkrantz <zmike at samsung.com>
> Reviewed-by: Yong Bakos <ybakos at humanoriented.com>
> ---

Sounds good:
Acked-by: Quentin Glidic <sardemff7+git at sardemff7.net>

Cheers,


>
> Changes since v3:
>
>  - Reword the grab parent surface requirements.
>
>
>  unstable/xdg-shell/xdg-shell-unstable-v6.xml | 110 +++++++++++++++++----------
>  1 file changed, 68 insertions(+), 42 deletions(-)
>
> diff --git a/unstable/xdg-shell/xdg-shell-unstable-v6.xml b/unstable/xdg-shell/xdg-shell-unstable-v6.xml
> index e4d552c..4c5dab4 100644
> --- a/unstable/xdg-shell/xdg-shell-unstable-v6.xml
> +++ b/unstable/xdg-shell/xdg-shell-unstable-v6.xml
> @@ -164,16 +164,11 @@
>  	This creates an xdg_popup object for the given xdg_surface and gives the
>  	associated wl_surface the xdg_popup role.
>
> -	This request must be used in response to some sort of user action like a
> -	button press, key press, or touch down event.
> -
>  	See the documentation of xdg_popup for more details about what an
>  	xdg_popup is and how it is used.
>        </description>
>        <arg name="id" type="new_id" interface="zxdg_popup_v6"/>
>        <arg name="parent" type="object" interface="zxdg_surface_v6"/>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
> -      <arg name="serial" type="uint" summary="the serial of the user event"/>
>        <arg name="x" type="int"/>
>        <arg name="y" type="int"/>
>      </request>
> @@ -675,46 +670,30 @@
>
>    <interface name="zxdg_popup_v6" version="1">
>      <description summary="short-lived, popup surfaces for menus">
> -      A popup surface is a short-lived, temporary surface that can be
> -      used to implement menus. It takes an explicit grab on the surface
> -      that will be dismissed when the user dismisses the popup. This can
> -      be done by the user clicking outside the surface, using the keyboard,
> -      or even locking the screen through closing the lid or a timeout.
> -
> -      When the popup is dismissed, a popup_done event will be sent out,
> -      and at the same time the surface will be unmapped. The xdg_popup
> -      object is now inert and cannot be reactivated, so clients should
> -      destroy it. Explicitly destroying the xdg_popup object will also
> -      dismiss the popup and unmap the surface.
> -
> -      Clients will receive events for all their surfaces during this
> -      grab (which is an "owner-events" grab in X11 parlance). This is
> -      done so that users can navigate through submenus and other
> -      "nested" popup windows without having to dismiss the topmost
> -      popup.
> -
> -      Clients that want to dismiss the popup when another surface of
> -      their own is clicked should dismiss the popup using the destroy
> +      A popup surface is a short-lived, temporary surface. It can be used to
> +      implement for example menus, popovers, tooltips and other similar user
> +      interface concepts.
> +
> +      A popup can be made to take an explicit grab. See xdg_popup.grab for
> +      details.
> +
> +      When the popup is dismissed, a popup_done event will be sent out, and at
> +      the same time the surface will be unmapped. See the xdg_popup.popup_done
> +      event for details.
> +
> +      Explicitly destroying the xdg_popup object will also dismiss the popup and
> +      unmap the surface. Clients that want to dismiss the popup when another
> +      surface of their own is clicked should dismiss the popup using the destroy
>        request.
>
>        The parent surface must have either the xdg_toplevel or xdg_popup surface
>        role.
>
> -      Specifying an xdg_popup for the parent means that the popups are
> -      nested, with this popup now being the topmost popup. Nested
> -      popups must be destroyed in the reverse order they were created
> -      in, e.g. the only popup you are allowed to destroy at all times
> -      is the topmost one.
> +      A newly created xdg_popup will be stacked on top of all previously created
> +      xdg_popup surfaces associated with the same xdg_toplevel.
>
> -      If there is an existing popup when creating a new popup, the
> -      parent must be the current topmost popup.
> -
> -      A parent surface must be mapped before the new popup is mapped.
> -
> -      When compositors choose to dismiss a popup, they will likely
> -      dismiss every nested popup as well. When a compositor dismisses
> -      popups, it will follow the same dismissing order as required
> -      from the client.
> +      The parent of an xdg_popup must be mapped (see the xdg_surface
> +      description) before the xdg_popup itself.
>
>        The x and y arguments passed when creating the popup object specify
>        where the top left of the popup should be placed, relative to the
> @@ -723,9 +702,6 @@
>
>        The client must call wl_surface.commit on the corresponding wl_surface
>        for the xdg_popup state to take effect.
> -
> -      For a surface to be mapped by the compositor the client must have
> -      committed both the xdg_popup state and a buffer.
>      </description>
>
>      <request name="destroy" type="destructor">
> @@ -738,6 +714,56 @@
>        </description>
>      </request>
>
> +    <request name="grab">
> +      <description summary="make the popup take an explicit grab">
> +	This request makes the created popup take an explicit grab. An explicit
> +	grab will be dismissed when the user dismisses the popup, or when the
> +	client destroys the xdg_popup. This can be done by the user clicking
> +	outside the surface, using the keyboard, or even locking the screen
> +	through closing the lid or a timeout.
> +
> +	If the compositor denies the grab, the popup will be immediately
> +	dismissed.
> +
> +	This request must be used in response to some sort of user action like a
> +	button press, key press, or touch down event. The serial number of the
> +	event should be passed as 'serial'.
> +
> +	The parent of a grabbing popup must either be a xdg_toplevel surface or
> +	another xdg_popup with an explicit grab. If the parent is another
> +	xdg_popup it means that the popups are nested, with this popup now being
> +	the topmost popup.
> +
> +	Nested popups must be destroyed in the reverse order they were created
> +	in, e.g. the only popup you are allowed to destroy at all times is the
> +	topmost one.
> +
> +	When compositors choose to dismiss a popup, they may dismiss every
> +	nested grabbing popup as well. When a compositor dismisses popups, it
> +	will follow the same dismissing order as required from the client.
> +
> +	The parent of a grabbing popup must either be another xdg_popup with an
> +	active explicit grab, or an xdg_popup or xdg_toplevel, if there are no
> +	explicit grabs already taken.
> +
> +	If the topmost grabbing popup is destroyed, the grab will be returned to
> +	the parent of the popup, if that parent previously had an explicit grab.
> +
> +	If the parent is a grabbing popup which has already been dismissed, this
> +	popup will be immediately dismissed. If the parent is a popup that did
> +	not take an explicit grab, an error will be raised.
> +
> +	Clients will receive events for all their surfaces during this grab
> +	(which is an "owner-events" grab in X11 parlance). This is done so that
> +	users can navigate through submenus and other "nested" popup windows
> +	without having to dismiss the topmost popup.
> +      </description>
> +
> +      <arg name="seat" type="object" interface="wl_seat"
> +	   summary="the wl_seat of the user event"/>
> +      <arg name="serial" type="uint" summary="the serial of the user event"/>
> +    </request>
> +
>      <event name="popup_done">
>        <description summary="popup interaction is done">
>  	The popup_done event is sent out when a popup is dismissed by the
>


-- 

Quentin “Sardem FF7” Glidic