From 8315aaf1ac57337c73da6a3cfd934d2dfed63c1c Mon Sep 17 00:00:00 2001 From: Jonas Ådahl Date: Fri, 4 Dec 2015 14:10:19 +0800 Subject: xdg-shell: Turn xdg_surface into a generic base interface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split out toplevel window like requests and events into a new interface called xdg_toplevel, and turn xdg_surface into a generic base interface which others extends. xdg_popup is changed to extend the xdg_surface. The configure event in xdg_surface was split up making xdg_surface.configure an event only carrying the serial number, while a new xdg_toplevel.configure event carries the other data previously sent via xdg_surface.configure. xdg_toplevel.configure is made to extend, via the latch-state mechanism, xdg_surface.configure and depends on that event to synchronize state. Other future xdg_surface based extensions are meant to also extend xdg_surface.configure for relevant window type dependend state synchronization. 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 | 280 ++++++++++++++++----------- 1 file changed, 170 insertions(+), 110 deletions(-) (limited to 'unstable/xdg-shell') diff --git a/unstable/xdg-shell/xdg-shell-unstable-v6.xml b/unstable/xdg-shell/xdg-shell-unstable-v6.xml index ce57153..3268077 100644 --- a/unstable/xdg-shell/xdg-shell-unstable-v6.xml +++ b/unstable/xdg-shell/xdg-shell-unstable-v6.xml @@ -54,11 +54,14 @@ - This creates an xdg_surface for the given surface and gives it the - xdg_surface role. A wl_surface can only be given an xdg_surface role - once. If get_xdg_surface is called with a wl_surface that already has - an active xdg_surface associated with it, or if it had any other role, - an error is raised. + This creates an xdg_surface for the given surface. While xdg_surface + itself is not a role, the corresponding surface may only be assigned + a role extending xdg_surface, such as xdg_toplevel or xdg_popup. + + This creates an xdg_surface for the given surface. An xdg_surface is + used as basis to define a role to a given surface, such as xdg_toplevel + or xdg_popup. It also manages functionality shared between xdg_surface + based surface roles. See the documentation of xdg_surface for more details about what an xdg_surface is and how it is used. @@ -67,29 +70,6 @@ - - - This creates an xdg_popup for the given surface and gives it the - xdg_popup role. A wl_surface can only be given an xdg_popup role - once. If get_xdg_popup is called with a wl_surface that already has - an active xdg_popup associated with it, or if it had any other role, - an error is raised. - - 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. - - - - - - - - - - The ping event asks the client if it's still alive. Pass the @@ -117,13 +97,23 @@ - + An interface that may be implemented by a wl_surface, for implementations that provide a desktop-style user interface. - It provides requests to treat surfaces like windows, allowing to set - properties like maximized, fullscreen, minimized, and to move and resize - them, and associate metadata like title and app id. + It provides a base set of functionality required to construct user + interface elements requiring management by the compositor, such as + toplevel windows, menus, etc. The types of functionality are split into + xdg_surface roles. + + Creating an xdg_surface does not set the role for a wl_surface. In order + to map an xdg_surface, the client must create a role-specific object + using, e.g., get_toplevel, get_popup. The wl_surface for any given + xdg_surface can have at most one role, and may not be assigned any role + not based on xdg_surface. + + A role must be assigned before any other requests are made to the + xdg_surface object. The client must call wl_surface.commit on the corresponding wl_surface for the xdg_surface state to take effect. @@ -133,12 +123,147 @@ manipulate a buffer prior to the first xdg_surface.configure call must also be treated as errors. - For a surface to be mapped by the compositor the client must have - committed both an xdg_surface state and a buffer. + For a surface to be mapped by the compositor, the following conditions + must be met: (1) the client has assigned a xdg_surface based role to the + surface, (2) the client has set and committed the xdg_surface state and + the role dependent state to the surface and (3) the client has committed a + buffer to the surface. + + + + + - + + Destroy the xdg_surface object. An xdg_surface must only be destroyed + after its role object has been destroyed. + + + + + + This creates an xdg_toplevel object for the given xdg_surface and gives + the associated wl_surface the xdg_toplevel role. + + See the documentation of xdg_toplevel for more details about what an + xdg_toplevel is and how it is used. + + + + + + + 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. + + + + + + + + + + + + The window geometry of a surface is its "visible bounds" from the + user's perspective. Client-side decorations often have invisible + portions like drop-shadows which should be ignored for the + purposes of aligning, placing and constraining windows. + + The window geometry is double buffered, and will be applied at the + time wl_surface.commit of the corresponding wl_surface is called. + + Once the window geometry of the surface is set, it is not possible to + unset it, and it will remain the same until set_window_geometry is + called again, even if a new subsurface or buffer is attached. + + If never set, the value is the full bounds of the surface, + including any subsurfaces. This updates dynamically on every + commit. This unset is meant for extremely simple clients. + + The arguments are given in the surface-local coordinate space of + the wl_surface associated with this xdg_surface. + + The width and height must be greater than zero. Setting an invalid size + will raise an error. When applied, the effective window geometry will be + the set window geometry clamped to the bounding rectangle of the + combined geometry of the surface of the xdg_surface and the associated + subsurfaces. + + + + + + + + + + When a configure event is received, if a client commits the + surface in response to the configure event, then the client + must make an ack_configure request sometime before the commit + request, passing along the serial of the configure event. + + For instance, for toplevel surfaces the compositor might use this + information to move a surface to the top left only when the client has + drawn itself for the maximized or fullscreen state. + + If the client receives multiple configure events before it + can respond to one, it only has to ack the last configure event. + + A client is not required to commit immediately after sending + an ack_configure request - it may even ack_configure several times + before its next surface commit. + + A client may send multiple ack_configure requests before committing, but + only the last request sent before a commit indicates which configure + event the client really is responding to. + + + + + + + The configure event marks the end of a configure sequence. A configure + sequence is a set of one or more events configuring the state of the + xdg_surface, including the final xdg_surface.configure event. + + Where applicable, xdg_surface surface roles will during a configure + sequence extend this event as a latched state sent as events before the + xdg_surface.configure event. Such events should be considered to make up + a set of atomically applied configuration states, where the + xdg_surface.configure commits the accumulated state. + + Clients should arrange their surface for the new states, and then send + an ack_configure request with the serial sent in this configure event at + some point before committing the new surface. + + If the client receives multiple configure events before it can respond + to one, it is free to discard all but the last event it received. + + + + + + + + This interface defines an xdg_surface role which allows a surface to, + among other things, set window-like properties such as maximize, + fullscreen, and minimize, set application-specific metadata like title and + id, and well as trigger user interactive operations such as interactive + resize and move. + + + + Unmap and destroy the window. The window will be effectively hidden from the user's point of view, and all state like maximization, fullscreen, and so on, will be lost. @@ -155,7 +280,7 @@ "auxiliary" surfaces, so that the parent is raised when the dialog is raised. - + @@ -348,8 +473,9 @@ - The configure event asks the client to resize its surface or to - change its state. + This configure event asks the client to resize its toplevel surface or + to change its state. The configured state should not be applied + immediately. See xdg_surface.configure for details. The width and height arguments specify a hint to the window about how its surface should be resized in window geometry @@ -364,81 +490,15 @@ arguments should be interpreted, and possibly how it should be drawn. - Clients should arrange their surface for the new size and - states, and then send a ack_configure request with the serial - sent in this configure event at some point before committing - the new surface. - - If the client receives multiple configure events before it - can respond to one, it is free to discard all but the last - event it received. + Clients must send an ack_configure in response to this event. See + xdg_surface.configure and xdg_surface.ack_configure for details. - - - - When a configure event is received, if a client commits the - surface in response to the configure event, then the client - must make an ack_configure request sometime before the commit - request, passing along the serial of the configure event. - - For instance, the compositor might use this information to move - a surface to the top left only when the client has drawn itself - for the maximized or fullscreen state. - - If the client receives multiple configure events before it - can respond to one, it only has to ack the last configure event. - - A client is not required to commit immediately after sending - an ack_configure request - it may even ack_configure several times - before its next surface commit. - - The compositor expects that the most recently received - ack_configure request at the time of a commit indicates which - configure event the client is responding to. - - - - - - - The window geometry of a window is its "visible bounds" from the - user's perspective. Client-side decorations often have invisible - portions like drop-shadows which should be ignored for the - purposes of aligning, placing and constraining windows. - - The window geometry is double buffered, and will be applied at the - time wl_surface.commit of the corresponding wl_surface is called. - - Once the window geometry of the surface is set once, it is not - possible to unset it, and it will remain the same until - set_window_geometry is called again, even if a new subsurface or - buffer is attached. - - If never set, the value is the full bounds of the surface, - including any subsurfaces. This updates dynamically on every - commit. This unset mode is meant for extremely simple clients. - - If responding to a configure event, the window geometry in here - must respect the sizing negotiations specified by the states in - the configure event. - - The arguments are given in the surface local coordinate space of - the wl_surface associated with this xdg_surface. - - The width and height must be greater than zero. - - - - - - - Set a maximum size for the window. @@ -447,7 +507,7 @@ not try to configure the window beyond this size. The width and height arguments are in window geometry coordinates. - See set_window_geometry. + See xdg_surface.set_window_geometry. Values set in this way are double-buffered. They will get applied on the next commit. @@ -488,7 +548,7 @@ not try to configure the window below this size. The width and height arguments are in window geometry coordinates. - See set_window_geometry. + See xdg_surface.set_window_geometry. Values set in this way are double-buffered. They will get applied on the next commit. @@ -631,7 +691,7 @@ their own is clicked should dismiss the popup using the destroy request. - The parent surface must have either an xdg_surface or xdg_popup + 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 @@ -653,7 +713,7 @@ 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 local surface coordinates of the parent surface. See - xdg_shell.get_xdg_popup. + xdg_surface.get_popup. The client must call wl_surface.commit on the corresponding wl_surface for the xdg_popup state to take effect. -- cgit v1.2.3