On May 11, 2016, at 12:50 AM, Jonas Ådahl <[email protected]> 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 <[email protected]> > Signed-off-by: Mike Blumenkrantz <[email protected]>
All seems pretty clear to me and is Reviewed-by: Yong Bakos <[email protected]> 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 > [email protected] > https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
