From eef4b95f59ccc3eedcb01cd6e06556488bf8f71c Mon Sep 17 00:00:00 2001 From: Jonas Ådahl Date: Fri, 4 Dec 2015 14:58:12 +0800 Subject: xdg-shell: Make xdg_popup non-grabbing by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Mike Blumenkrantz Reviewed-by: Yong Bakos Acked-by: Quentin Glidic --- unstable/xdg-shell/xdg-shell-unstable-v6.xml | 115 +++++++++++++++++---------- 1 file changed, 73 insertions(+), 42 deletions(-) (limited to 'unstable') diff --git a/unstable/xdg-shell/xdg-shell-unstable-v6.xml b/unstable/xdg-shell/xdg-shell-unstable-v6.xml index e4d552c..0771668 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. - - @@ -675,46 +670,30 @@ - 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,11 +702,13 @@ 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. + + + + This destroys the popup. Explicitly destroying the xdg_popup @@ -738,6 +719,56 @@ + + + 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. + + + + + + The popup_done event is sent out when a popup is dismissed by the -- cgit v1.2.3