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

Tue May 17 19:10:27 UTC 2016

On May 11, 2016, at 12:50 AM, Jonas Ådahl <jadahl at gmail.com> 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>

All seems pretty clear to me and is
Reviewed-by: Yong Bakos <ybakos at humanoriented.com>

yong


> ---
> 
> Changes since v1:
> 
> - various grammatical fixes
> 
> 
> Jonas
> 
> 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 90cf7c2..2edc341 100644
> --- a/unstable/xdg-shell/xdg-shell-unstable-v6.xml
> +++ b/unstable/xdg-shell/xdg-shell-unstable-v6.xml
> @@ -158,16 +158,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>
> @@ -666,46 +661,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.
> -
> -      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.
> +      A newly created xdg_popup will be stacked on top of all previously created
> +      xdg_popup surfaces associated with the same xdg_toplevel.
> 
> -      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
> @@ -714,9 +693,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">
> @@ -729,6 +705,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.
> +
> +	If there currently is an existing popup with an explicit grab, the
> +	parent of this popup must be that grabbing popup. The new popup will
> +	take over the grab previously held by the current topmost grabbing
> +	popup. If the topmost grabbing popup is destroyed, the grab will be
> +	returned to the parent popup, if the parent popup 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
> -- 
> 2.5.5
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel