[PATCH wayland-protocols v4 6/7] xdg-shell: Make xdg_popup non-grabbing by default
Jonas Ådahl
jadahl at gmail.com
Fri Jun 24 06:47:33 UTC 2016
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>
---
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
--
2.5.5
More information about the wayland-devel
mailing list