[weston,5/6] xdg-shell: Rewrite documentation

Submitted by Jasper St. Pierre on Nov. 22, 2014, 8:28 p.m.

Details

Message ID 1416688110-21188-6-git-send-email-jstpierre@mecheye.net
State Superseded
Headers show

Not browsing as part of any series.

Commit Message

Jasper St. Pierre Nov. 22, 2014, 8:28 p.m.
This rewrites basically all of the text inside xdg-shell to be up to
date, clearer, and rid of wl_shell and X11 terminology.
---
 protocol/xdg-shell.xml | 256 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 156 insertions(+), 100 deletions(-)

Patch hide | download patch | download mbox

diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
index 360179d..3359cf7 100644
--- a/protocol/xdg-shell.xml
+++ b/protocol/xdg-shell.xml
@@ -31,11 +31,15 @@ 
 
   <interface name="xdg_shell" version="1">
     <description summary="create desktop-style surfaces">
-      This interface is implemented by servers that provide
-      desktop-style user interfaces.
-
-      It allows clients to associate a xdg_surface with
-      a basic surface.
+      xdg_shell allows clients to turn a wl_surface into a "real window"
+      which can be dragged, resized, stacked, and moved around by the
+      user. Everything about this interface is suited towards traditional
+      desktop environments.
+
+      Destroying a bound xdg_shell object while there are surfaces
+      still alive with roles from this interface is illegal and will
+      result in a protocol error. Make sure to destroy all surfaces
+      before destroying this object.
     </description>
 
     <enum name="version">
@@ -65,33 +69,26 @@ 
 
     <request name="get_xdg_surface">
       <description summary="create a shell surface from a surface">
-	Create a shell surface for an existing surface.
-
-	This request gives the surface the role of xdg_surface. If the
-	surface already has another role, it raises a protocol error.
-
-	Only one shell or popup surface can be associated with a given
-	surface.
+	This creates an xdg_surface for the given surface and gives it the
+	xdg_surface role. See the documentation of xdg_surface for more details.
       </description>
       <arg name="id" type="new_id" interface="xdg_surface"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </request>
 
     <request name="get_xdg_popup">
-      <description summary="create a shell surface from a surface">
-	Create a popup surface for an existing surface.
-
-	This request gives the surface the role of xdg_popup. If the
-	surface already has another role, it raises a protocol error.
+      <description summary="create a popup for a surface">
+	This creates an xdg_popup for the given surface and gives it the
+	xdg_popup role. See the documentation of xdg_surface for more details.
 
-	Only one shell or popup surface can be associated with a given
-	surface.
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event.
       </description>
       <arg name="id" type="new_id" interface="xdg_popup"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="parent" type="object" interface="wl_surface"/>
-      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
-      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
+      <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>
@@ -107,7 +104,7 @@ 
         respond to the ping request, or in what timeframe. Clients should
         try to respond in a reasonable amount of time.
       </description>
-      <arg name="serial" type="uint" summary="pass this to the callback"/>
+      <arg name="serial" type="uint" summary="pass this to the pong request"/>
     </event>
 
     <request name="pong">
@@ -120,8 +117,7 @@ 
   </interface>
 
   <interface name="xdg_surface" version="1">
-
-    <description summary="desktop-style metadata interface">
+    <description summary="A desktop window">
       An interface that may be implemented by a wl_surface, for
       implementations that provide a desktop-style user interface.
 
@@ -136,20 +132,22 @@ 
     </description>
 
     <request name="destroy" type="destructor">
-      <description summary="remove xdg_surface interface">
-	The xdg_surface interface is removed from the wl_surface object
-	that was turned into a xdg_surface with
-	xdg_shell.get_xdg_surface request. The xdg_surface properties,
-	like maximized and fullscreen, are lost. The wl_surface loses
-	its role as a xdg_surface. The wl_surface is unmapped.
+      <description summary="Destroy the xdg_surface">
+	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.
       </description>
     </request>
 
     <request name="set_parent">
-      <description summary="surface is a child of another surface">
-	Child surfaces are stacked above their parents, and will be
-	unmapped if the parent is unmapped too. They should not appear
-	on task bars and alt+tab.
+      <description summary="set the parent of this surface">
+	Set the "parent" of this surface. This window should be stacked
+	above a parent. The parent surface must be mapped as long as this
+	surface is mapped.
+
+	Parent windows should be set on dialogs, toolboxes, or other
+	"auxilliary" surfaces, so that the parent is raised when the dialog
+	is raised.
       </description>
       <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
     </request>
@@ -168,14 +166,19 @@ 
     </request>
 
     <request name="set_app_id">
-      <description summary="set surface class">
-	Set an id for the surface.
+      <description summary="set application ID">
+	Set an application identifier for the surface.
+
+	The app ID identifies the general class of applications to which
+	the surface belongs. The compositor can use this to group multiple
+	applications together, or to determine how to launch a new
+	application.
 
-	The app id identifies the general class of applications to which
-	the surface belongs.
+	See the desktop-entry specification [0] for more details on
+	application identifiers and how they relate to well-known DBus
+	names and .desktop files.
 
-	It should be the ID that appears in the new desktop entry
-	specification, the interface name.
+	[0] http://standards.freedesktop.org/desktop-entry-spec/
       </description>
       <arg name="app_id" type="string"/>
     </request>
@@ -187,29 +190,32 @@ 
         user a menu that they can use to maximize or minimize the window.
 
         This request asks the compositor to pop up such a window menu at
-        the given position, relative to the parent surface. There are
-        no guarantees as to what the window menu contains.
+        the given position, relative to the local surface coordinates of
+        the parent surface. There are no guarantees as to what menu items
+        the window menu contains.
 
-        Your surface must have focus on the seat passed in to pop up the
-        window menu.
+        This request must be used in response to some sort of user action
+        like a button press, key press, or touch down event.
       </description>
 
-      <arg name="seat" type="object" interface="wl_seat" summary="the seat to pop the window up on"/>
-      <arg name="serial" type="uint" summary="serial of the event to pop up the window for"/>
+      <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" summary="the x position to pop up the window menu at"/>
       <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
     </request>
 
     <request name="move">
       <description summary="start an interactive move">
-	Start a pointer-driven move of the surface.
+	Start an interactive, user-driven move of the surface.
+
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event.
 
-	This request must be used in response to a button press event.
 	The server may ignore move requests depending on the state of
 	the surface (e.g. fullscreen or maximized).
       </description>
-      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
-      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
+      <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>
 
     <enum name="resize_edge">
@@ -232,14 +238,16 @@ 
 
     <request name="resize">
       <description summary="start an interactive resize">
-	Start a pointer-driven resizing of the surface.
+	Start a user-driven, interactive resize of the surface.
+
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event.
 
-	This request must be used in response to a button press event.
 	The server may ignore resize requests depending on the state of
 	the surface (e.g. fullscreen or maximized).
       </description>
-      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
-      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
+      <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="edges" type="uint" summary="which edge or corner is being dragged"/>
     </request>
 
@@ -287,16 +295,21 @@ 
 
     <event name="configure">
       <description summary="suggest a surface change">
-	The configure event asks the client to resize its surface.
+	The configure event asks the client to resize its surface or to
+	change its state.
 
 	The width and height arguments specify a hint to the window
-        about how its surface should be resized in window geometry
-        coordinates. The states listed in the event specify how the
-        width/height arguments should be interpreted.
+	about how its surface should be resized in window geometry
+	coordinates.
+
+	The states listed in the event specify how the width/height
+	arguments should be interpreted, and possibly how it should be
+	drawn.
 
-        A client should arrange a new surface, and then send a
-        ack_configure request with the serial sent in this configure
-        event before attaching a new surface.
+	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
@@ -311,14 +324,20 @@ 
 
     <request name="ack_configure">
       <description summary="ack a configure event">
-        When a configure event is received, a client should then ack it
-        using the ack_configure request to ensure that the compositor
-        knows the client has seen the event.
-
-        By this point, the state is confirmed, and the next attach should
-        contain the buffer drawn for the configure event you are acking.
+        When a configure event is received, if a client is updating
+        and redrawing its state in response to the configure event,
+        then the client needs to make an ack_configure request before
+        point the commit to mark this next commit as being a
+        reaction to the configure.
+
+        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.
       </description>
-      <arg name="serial" type="uint" summary="a serial to configure for"/>
+      <arg name="serial" type="uint" summary="the serial from the configure event"/>
     </request>
 
     <request name="set_window_geometry">
@@ -328,15 +347,20 @@ 
         portions like drop-shadows which should be ignored for the
         purposes of aligning, placing and constraining windows.
 
-        The default value is the full bounds of the surface, including any
-        subsurfaces. Once the window geometry of the surface is set once,
-        it is not possible to unset it, and it will remain the same until
+        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 width and height must be greater than zero.
       </description>
       <arg name="x" type="int"/>
       <arg name="y" type="int"/>
@@ -359,7 +383,18 @@ 
     </request>
     <request name="unset_fullscreen" />
 
-    <request name="set_minimized" />
+    <request name="set_minimized">
+      <description summary="set the window as minimized">
+	Request that the compositor minimize your surface. There is no
+	way to know if the surface is currently minimized, nor is there
+	any way to unset minimization on this surface.
+
+	If you are looking to throttle redrawing when minimized, please
+	instead use the wl_surface.frame event for this, as this will
+	also work with live previews on windows in Alt-Tab, Expose or
+	similar compositor features.
+      </description>
+    </request>
 
     <event name="close">
       <description summary="surface wants to be closed">
@@ -376,26 +411,48 @@ 
   </interface>
 
   <interface name="xdg_popup" version="1">
-    <description summary="desktop-style metadata interface">
-      An interface that may be implemented by a wl_surface, for
-      implementations that provide a desktop-style popups/menus. A popup
-      surface is a transient surface with an added pointer grab.
-
-      An existing implicit grab will be changed to owner-events mode,
-      and the popup grab will continue after the implicit grab ends
-      (i.e. releasing the mouse button does not cause the popup to be
-      unmapped).
-
-      The popup grab continues until the window is destroyed or a mouse
-      button is pressed in any other clients window. A click in any of
-      the clients surfaces is reported as normal, however, clicks in
-      other clients surfaces will be discarded and trigger the callback.
-
-      The x and y arguments specify the locations of the upper left
-      corner of the surface relative to the upper left corner of the
-      parent surface, in surface local coordinates.
-
-      xdg_popup surfaces are always transient for another surface.
+    <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
+      request.
+
+      The parent surface must have either an xdg_surface or xdg_popup
+      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.
+
+      When compositors choose to dismiss a popup if the user clicks
+      outside the window, they will likely dismiss every nested popup
+      as well.
+
+      The x and y arguments specify where the top left of the popup
+      should be placed, relative to the local surface coordinates of the
+      parent surface.
     </description>
 
     <enum name="error">
@@ -407,19 +464,18 @@ 
 
     <request name="destroy" type="destructor">
       <description summary="remove xdg_surface interface">
-	The xdg_surface interface is removed from the wl_surface object
-	that was turned into a xdg_surface with
-	xdg_shell.get_xdg_surface request. The xdg_surface properties,
-	like maximized and fullscreen, are lost. The wl_surface loses
-	its role as a xdg_surface. The wl_surface is unmapped.
+	This destroys the popup. Explicitly destroying the xdg_popup
+	object will also dismiss the popup, and unmap the surface.
+
+	If this xdg_popup is not the "topmost" popup, a protocol error
+	will be sent.
       </description>
     </request>
 
     <event name="popup_done">
       <description summary="popup interaction is done">
-	The popup_done event is sent out when a popup grab is broken,
-	that is, when the users clicks a surface that doesn't belong
-	to the client owning the popup surface.
+	The popup_done event is sent out when a popup is dismissed
+	by the compositor.
       </description>
     </event>
 

Comments

On Sat, 22 Nov 2014 12:28:29 -0800
"Jasper St. Pierre" <jstpierre@mecheye.net> wrote:

> This rewrites basically all of the text inside xdg-shell to be up to
> date, clearer, and rid of wl_shell and X11 terminology.
> ---
>  protocol/xdg-shell.xml | 256 ++++++++++++++++++++++++++++++-------------------
>  1 file changed, 156 insertions(+), 100 deletions(-)
> 
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 360179d..3359cf7 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -31,11 +31,15 @@
>  
>    <interface name="xdg_shell" version="1">
>      <description summary="create desktop-style surfaces">
> -      This interface is implemented by servers that provide
> -      desktop-style user interfaces.
> -
> -      It allows clients to associate a xdg_surface with
> -      a basic surface.
> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.
> +
> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.

Ok. We don't have a destroy request on xdg_shell interface currently,
and you are not adding one in this series, so this cannot be enforced.
Is that intentional, or should there be a destroy request?

I think having a destroy request on global interfaces should be
mandatory, so I'd recommend adding one.

What about clients that create multiple xdg_shell objects and then
further xdg_* objects from each? Do xdg_shell objects track which xdg_*
objects have been created from them?


>      </description>
>  
>      <enum name="version">
> @@ -65,33 +69,26 @@
>  
>      <request name="get_xdg_surface">
>        <description summary="create a shell surface from a surface">
> -	Create a shell surface for an existing surface.
> -
> -	This request gives the surface the role of xdg_surface. If the
> -	surface already has another role, it raises a protocol error.
> -
> -	Only one shell or popup surface can be associated with a given
> -	surface.
> +	This creates an xdg_surface for the given surface and gives it the
> +	xdg_surface role. See the documentation of xdg_surface for more details.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_surface"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>      </request>
>  
>      <request name="get_xdg_popup">
> -      <description summary="create a shell surface from a surface">
> -	Create a popup surface for an existing surface.
> -
> -	This request gives the surface the role of xdg_popup. If the
> -	surface already has another role, it raises a protocol error.
> +      <description summary="create a popup for a surface">
> +	This creates an xdg_popup for the given surface and gives it the
> +	xdg_popup role. See the documentation of xdg_surface for more details.

ITYM xdg_popup instead of xdg_surface.

>  
> -	Only one shell or popup surface can be associated with a given
> -	surface.
> +	This request must be used in response to some sort of user action
> +	like a button press, key press, or touch down event.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_popup"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>        <arg name="parent" type="object" interface="wl_surface"/>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
> +      <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>
> @@ -107,7 +104,7 @@
>          respond to the ping request, or in what timeframe. Clients should
>          try to respond in a reasonable amount of time.
>        </description>
> -      <arg name="serial" type="uint" summary="pass this to the callback"/>
> +      <arg name="serial" type="uint" summary="pass this to the pong request"/>
>      </event>
>  
>      <request name="pong">
> @@ -120,8 +117,7 @@
>    </interface>
>  
>    <interface name="xdg_surface" version="1">
> -
> -    <description summary="desktop-style metadata interface">
> +    <description summary="A desktop window">
>        An interface that may be implemented by a wl_surface, for
>        implementations that provide a desktop-style user interface.
>  
> @@ -136,20 +132,22 @@
>      </description>
>  
>      <request name="destroy" type="destructor">
> -      <description summary="remove xdg_surface interface">
> -	The xdg_surface interface is removed from the wl_surface object
> -	that was turned into a xdg_surface with
> -	xdg_shell.get_xdg_surface request. The xdg_surface properties,
> -	like maximized and fullscreen, are lost. The wl_surface loses
> -	its role as a xdg_surface. The wl_surface is unmapped.
> +      <description summary="Destroy the xdg_surface">
> +	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.

This is ok, but above this there is a paragraph that says:

	"On the server side the object is automatically destroyed when
	the related wl_surface is destroyed.  On client side,
	xdg_surface.destroy() must be called before destroying
	the wl_surface object."

I think that paragraph needs to have "On the server side the object is
automatically destroyed when the related wl_surface is destroyed."
deleted, because it contradicts with the existence of the destroy
request. This is likely a left-over from wl_shell_surface, where there
is no destroy request.


>        </description>
>      </request>
>  
>      <request name="set_parent">
> -      <description summary="surface is a child of another surface">
> -	Child surfaces are stacked above their parents, and will be
> -	unmapped if the parent is unmapped too. They should not appear
> -	on task bars and alt+tab.
> +      <description summary="set the parent of this surface">
> +	Set the "parent" of this surface. This window should be stacked
> +	above a parent. The parent surface must be mapped as long as this
> +	surface is mapped.
> +
> +	Parent windows should be set on dialogs, toolboxes, or other
> +	"auxilliary" surfaces, so that the parent is raised when the dialog
> +	is raised.
>        </description>
>        <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
>      </request>

...

> @@ -311,14 +324,20 @@
>  
>      <request name="ack_configure">
>        <description summary="ack a configure event">
> -        When a configure event is received, a client should then ack it
> -        using the ack_configure request to ensure that the compositor
> -        knows the client has seen the event.
> -
> -        By this point, the state is confirmed, and the next attach should
> -        contain the buffer drawn for the configure event you are acking.
> +        When a configure event is received, if a client is updating
> +        and redrawing its state in response to the configure event,
> +        then the client needs to make an ack_configure request before
> +        point the commit to mark this next commit as being a
> +        reaction to the configure.

"...an ack_configure request before point the commit to mark this next
commit..." I feel there is something odd in that sentence. s/point// maybe?


> +
> +        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.
>        </description>
> -      <arg name="serial" type="uint" summary="a serial to configure for"/>
> +      <arg name="serial" type="uint" summary="the serial from the configure event"/>
>      </request>

No other comments to this patch, but I think should dig up my old
review of the whole xdg_shell.xml file, and check what comments I
would like to restate after these changes. I'll try to do that "soon".


Thanks,
pq
On 11/22/2014 12:28 PM, Jasper St. Pierre wrote:

>     <interface name="xdg_shell" version="1">

> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.

I think this information should be moved to xdg_surface, which is much 
more the object the user is going to be thinking about. xdg_shell is 
just the factory used to create xdg_surface objects.

> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.

There does not appear to be a way to destroy a xdg_shell, actually.

> +      <description summary="set the parent of this surface">
> +	Set the "parent" of this surface. This window should be stacked
> +	above a parent. The parent surface must be mapped as long as this
> +	surface is mapped.
> +
> +	Parent windows should be set on dialogs, toolboxes, or other
> +	"auxilliary" surfaces, so that the parent is raised when the dialog
> +	is raised.

I think (or I hope) you mean "the child will be raised when the parent 
is raised"). You certainly should be able to raise the dialog without 
raising the parent, otherwise you have something identical to a subsurface.
I agree with Pekka's comments, I also have a couple of my own below.  (Most
of them are pretty trivial).  With Pekka's and my comments addressed, this
series looks good to me.
--Jason

On Sat, Nov 22, 2014 at 12:28 PM, Jasper St. Pierre <jstpierre@mecheye.net>
wrote:

> This rewrites basically all of the text inside xdg-shell to be up to
> date, clearer, and rid of wl_shell and X11 terminology.
> ---
>  protocol/xdg-shell.xml | 256
> ++++++++++++++++++++++++++++++-------------------
>  1 file changed, 156 insertions(+), 100 deletions(-)
>
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 360179d..3359cf7 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -31,11 +31,15 @@
>
>    <interface name="xdg_shell" version="1">
>      <description summary="create desktop-style surfaces">
> -      This interface is implemented by servers that provide
> -      desktop-style user interfaces.
> -
> -      It allows clients to associate a xdg_surface with
> -      a basic surface.
> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.
> +
> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.
>      </description>
>
>      <enum name="version">
> @@ -65,33 +69,26 @@
>
>      <request name="get_xdg_surface">
>        <description summary="create a shell surface from a surface">
> -       Create a shell surface for an existing surface.
> -
> -       This request gives the surface the role of xdg_surface. If the
> -       surface already has another role, it raises a protocol error.
> -
> -       Only one shell or popup surface can be associated with a given
> -       surface.
> +       This creates an xdg_surface for the given surface and gives it the
> +       xdg_surface role. See the documentation of xdg_surface for more
> details.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_surface"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>      </request>
>
>      <request name="get_xdg_popup">
> -      <description summary="create a shell surface from a surface">
> -       Create a popup surface for an existing surface.
> -
> -       This request gives the surface the role of xdg_popup. If the
> -       surface already has another role, it raises a protocol error.
> +      <description summary="create a popup for a surface">
> +       This creates an xdg_popup for the given surface and gives it the
> +       xdg_popup role. See the documentation of xdg_surface for more
> details.
>
> -       Only one shell or popup surface can be associated with a given
> -       surface.
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_popup"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>        <arg name="parent" type="object" interface="wl_surface"/>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab
> on the pointer"/>
> +      <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>
> @@ -107,7 +104,7 @@
>          respond to the ping request, or in what timeframe. Clients should
>          try to respond in a reasonable amount of time.
>        </description>
> -      <arg name="serial" type="uint" summary="pass this to the callback"/>
> +      <arg name="serial" type="uint" summary="pass this to the pong
> request"/>
>      </event>
>
>      <request name="pong">
> @@ -120,8 +117,7 @@
>    </interface>
>
>    <interface name="xdg_surface" version="1">
> -
> -    <description summary="desktop-style metadata interface">
> +    <description summary="A desktop window">
>        An interface that may be implemented by a wl_surface, for
>        implementations that provide a desktop-style user interface.
>
> @@ -136,20 +132,22 @@
>      </description>
>
>      <request name="destroy" type="destructor">
> -      <description summary="remove xdg_surface interface">
> -       The xdg_surface interface is removed from the wl_surface object
> -       that was turned into a xdg_surface with
> -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> -       like maximized and fullscreen, are lost. The wl_surface loses
> -       its role as a xdg_surface. The wl_surface is unmapped.
> +      <description summary="Destroy the xdg_surface">
> +       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.
>        </description>
>      </request>
>
>      <request name="set_parent">
> -      <description summary="surface is a child of another surface">
> -       Child surfaces are stacked above their parents, and will be
> -       unmapped if the parent is unmapped too. They should not appear
> -       on task bars and alt+tab.
> +      <description summary="set the parent of this surface">
> +       Set the "parent" of this surface. This window should be stacked
> +       above a parent. The parent surface must be mapped as long as this
> +       surface is mapped.
> +
> +       Parent windows should be set on dialogs, toolboxes, or other
> +       "auxilliary" surfaces, so that the parent is raised when the dialog
> +       is raised.
>

As Bill said, this seems to imply that raising parents raises children and
raising children raises parents.  Did you intend this to go both ways?


>        </description>
>        <arg name="parent" type="object" interface="xdg_surface"
> allow-null="true"/>
>      </request>
> @@ -168,14 +166,19 @@
>      </request>
>
>      <request name="set_app_id">
> -      <description summary="set surface class">
> -       Set an id for the surface.
> +      <description summary="set application ID">
> +       Set an application identifier for the surface.
> +
> +       The app ID identifies the general class of applications to which
> +       the surface belongs. The compositor can use this to group multiple
> +       applications together, or to determine how to launch a new
> +       application.
>
> -       The app id identifies the general class of applications to which
> -       the surface belongs.
> +       See the desktop-entry specification [0] for more details on
> +       application identifiers and how they relate to well-known DBus
> +       names and .desktop files.
>
> -       It should be the ID that appears in the new desktop entry
> -       specification, the interface name.
> +       [0] http://standards.freedesktop.org/desktop-entry-spec/
>        </description>
>        <arg name="app_id" type="string"/>
>      </request>
> @@ -187,29 +190,32 @@
>          user a menu that they can use to maximize or minimize the window.
>
>          This request asks the compositor to pop up such a window menu at
> -        the given position, relative to the parent surface. There are
> -        no guarantees as to what the window menu contains.
> +        the given position, relative to the local surface coordinates of
> +        the parent surface. There are no guarantees as to what menu items
> +        the window menu contains.
>
> -        Your surface must have focus on the seat passed in to pop up the
> -        window menu.
> +        This request must be used in response to some sort of user action
> +        like a button press, key press, or touch down event.
>        </description>
>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the
> seat to pop the window up on"/>
> -      <arg name="serial" type="uint" summary="serial of the event to pop
> up the window for"/>
> +      <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" summary="the x position to pop up the
> window menu at"/>
>        <arg name="y" type="int" summary="the y position to pop up the
> window menu at"/>
>      </request>
>
>      <request name="move">
>        <description summary="start an interactive move">
> -       Start a pointer-driven move of the surface.
> +       Start an interactive, user-driven move of the surface.
> +
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>
> -       This request must be used in response to a button press event.
>         The server may ignore move requests depending on the state of
>         the surface (e.g. fullscreen or maximized).
>        </description>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab
> on the pointer"/>
> +      <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>
>
>      <enum name="resize_edge">
> @@ -232,14 +238,16 @@
>
>      <request name="resize">
>        <description summary="start an interactive resize">
> -       Start a pointer-driven resizing of the surface.
> +       Start a user-driven, interactive resize of the surface.
> +
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>
> -       This request must be used in response to a button press event.
>         The server may ignore resize requests depending on the state of
>         the surface (e.g. fullscreen or maximized).
>        </description>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab
> on the pointer"/>
> +      <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="edges" type="uint" summary="which edge or corner is
> being dragged"/>
>      </request>
>
> @@ -287,16 +295,21 @@
>
>      <event name="configure">
>        <description summary="suggest a surface change">
> -       The configure event asks the client to resize its surface.
> +       The configure event asks the client to resize its surface or to
> +       change its state.
>
>         The width and height arguments specify a hint to the window
> -        about how its surface should be resized in window geometry
> -        coordinates. The states listed in the event specify how the
> -        width/height arguments should be interpreted.
> +       about how its surface should be resized in window geometry
> +       coordinates.
> +
> +       The states listed in the event specify how the width/height
> +       arguments should be interpreted, and possibly how it should be
> +       drawn.
>
> -        A client should arrange a new surface, and then send a
> -        ack_configure request with the serial sent in this configure
> -        event before attaching a new surface.
> +       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
> @@ -311,14 +324,20 @@
>
>      <request name="ack_configure">
>        <description summary="ack a configure event">
> -        When a configure event is received, a client should then ack it
> -        using the ack_configure request to ensure that the compositor
> -        knows the client has seen the event.
> -
> -        By this point, the state is confirmed, and the next attach should
> -        contain the buffer drawn for the configure event you are acking.
> +        When a configure event is received, if a client is updating
> +        and redrawing its state in response to the configure event,
> +        then the client needs to make an ack_configure request before
> +        point the commit to mark this next commit as being a
> +        reaction to the configure.
>

This sentence needs to be reworded.  The last half, in particular, makes no
sense.  You and I both know what it means, but it's not very clear.


> +
> +        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.
>        </description>
> -      <arg name="serial" type="uint" summary="a serial to configure for"/>
> +      <arg name="serial" type="uint" summary="the serial from the
> configure event"/>
>      </request>
>
>      <request name="set_window_geometry">
> @@ -328,15 +347,20 @@
>          portions like drop-shadows which should be ignored for the
>          purposes of aligning, placing and constraining windows.
>
> -        The default value is the full bounds of the surface, including any
> -        subsurfaces. Once the window geometry of the surface is set once,
> -        it is not possible to unset it, and it will remain the same until
> +        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 width and height must be greater than zero.
>        </description>
>        <arg name="x" type="int"/>
>        <arg name="y" type="int"/>
> @@ -359,7 +383,18 @@
>      </request>
>      <request name="unset_fullscreen" />
>
> -    <request name="set_minimized" />
> +    <request name="set_minimized">
> +      <description summary="set the window as minimized">
> +       Request that the compositor minimize your surface. There is no
> +       way to know if the surface is currently minimized, nor is there
> +       any way to unset minimization on this surface.
> +
> +       If you are looking to throttle redrawing when minimized, please
> +       instead use the wl_surface.frame event for this, as this will
> +       also work with live previews on windows in Alt-Tab, Expose or
> +       similar compositor features.
> +      </description>
> +    </request>
>
>      <event name="close">
>        <description summary="surface wants to be closed">
> @@ -376,26 +411,48 @@
>    </interface>
>
>    <interface name="xdg_popup" version="1">
> -    <description summary="desktop-style metadata interface">
> -      An interface that may be implemented by a wl_surface, for
> -      implementations that provide a desktop-style popups/menus. A popup
> -      surface is a transient surface with an added pointer grab.
> -
> -      An existing implicit grab will be changed to owner-events mode,
> -      and the popup grab will continue after the implicit grab ends
> -      (i.e. releasing the mouse button does not cause the popup to be
> -      unmapped).
> -
> -      The popup grab continues until the window is destroyed or a mouse
> -      button is pressed in any other clients window. A click in any of
> -      the clients surfaces is reported as normal, however, clicks in
> -      other clients surfaces will be discarded and trigger the callback.
> -
> -      The x and y arguments specify the locations of the upper left
> -      corner of the surface relative to the upper left corner of the
> -      parent surface, in surface local coordinates.
> -
> -      xdg_popup surfaces are always transient for another surface.
> +    <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.
>

no comma


> +
> +      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
> +      request.
> +
> +      The parent surface must have either an xdg_surface or xdg_popup
> +      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.
> +
> +      When compositors choose to dismiss a popup if the user clicks
> +      outside the window, they will likely dismiss every nested popup
> +      as well.
>

No need to specify clicking outside a window.  I would expect that to
happen for hotkeys screen locks, etc. as well.


> +
> +      The x and y arguments specify where the top left of the popup
> +      should be placed, relative to the local surface coordinates of the
> +      parent surface.
>      </description>
>
>      <enum name="error">
> @@ -407,19 +464,18 @@
>
>      <request name="destroy" type="destructor">
>        <description summary="remove xdg_surface interface">
>

I believe you mean "xdg_popup" here.


> -       The xdg_surface interface is removed from the wl_surface object
> -       that was turned into a xdg_surface with
> -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> -       like maximized and fullscreen, are lost. The wl_surface loses
> -       its role as a xdg_surface. The wl_surface is unmapped.
> +       This destroys the popup. Explicitly destroying the xdg_popup
> +       object will also dismiss the popup, and unmap the surface.
> +
> +       If this xdg_popup is not the "topmost" popup, a protocol error
> +       will be sent.
>        </description>
>      </request>
>
>      <event name="popup_done">
>        <description summary="popup interaction is done">
> -       The popup_done event is sent out when a popup grab is broken,
> -       that is, when the users clicks a surface that doesn't belong
> -       to the client owning the popup surface.
> +       The popup_done event is sent out when a popup is dismissed
> +       by the compositor.
>        </description>
>      </event>
>
> --
> 2.1.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
2014-11-22 22:28 GMT+02:00 Jasper St. Pierre <jstpierre@mecheye.net>:
> This rewrites basically all of the text inside xdg-shell to be up to
> date, clearer, and rid of wl_shell and X11 terminology.
> ---
>  protocol/xdg-shell.xml | 256 ++++++++++++++++++++++++++++++-------------------
>  1 file changed, 156 insertions(+), 100 deletions(-)
>
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 360179d..3359cf7 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -31,11 +31,15 @@
>
>    <interface name="xdg_shell" version="1">
>      <description summary="create desktop-style surfaces">
> -      This interface is implemented by servers that provide
> -      desktop-style user interfaces.
> -
> -      It allows clients to associate a xdg_surface with
> -      a basic surface.
> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.
> +
> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.
>      </description>
>
>      <enum name="version">
> @@ -65,33 +69,26 @@
>
>      <request name="get_xdg_surface">
>        <description summary="create a shell surface from a surface">
> -       Create a shell surface for an existing surface.
> -
> -       This request gives the surface the role of xdg_surface. If the
> -       surface already has another role, it raises a protocol error.
> -
> -       Only one shell or popup surface can be associated with a given
> -       surface.
> +       This creates an xdg_surface for the given surface and gives it the
> +       xdg_surface role. See the documentation of xdg_surface for more details.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_surface"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>      </request>
>
>      <request name="get_xdg_popup">
> -      <description summary="create a shell surface from a surface">
> -       Create a popup surface for an existing surface.
> -
> -       This request gives the surface the role of xdg_popup. If the
> -       surface already has another role, it raises a protocol error.
> +      <description summary="create a popup for a surface">
> +       This creates an xdg_popup for the given surface and gives it the
> +       xdg_popup role. See the documentation of xdg_surface for more details.
>
> -       Only one shell or popup surface can be associated with a given
> -       surface.
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>        </description>
>        <arg name="id" type="new_id" interface="xdg_popup"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>        <arg name="parent" type="object" interface="wl_surface"/>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
> +      <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>
> @@ -107,7 +104,7 @@
>          respond to the ping request, or in what timeframe. Clients should
>          try to respond in a reasonable amount of time.
>        </description>
> -      <arg name="serial" type="uint" summary="pass this to the callback"/>
> +      <arg name="serial" type="uint" summary="pass this to the pong request"/>
>      </event>
>
>      <request name="pong">
> @@ -120,8 +117,7 @@
>    </interface>
>
>    <interface name="xdg_surface" version="1">
> -
> -    <description summary="desktop-style metadata interface">
> +    <description summary="A desktop window">
>        An interface that may be implemented by a wl_surface, for
>        implementations that provide a desktop-style user interface.
>
> @@ -136,20 +132,22 @@
>      </description>
>
>      <request name="destroy" type="destructor">
> -      <description summary="remove xdg_surface interface">
> -       The xdg_surface interface is removed from the wl_surface object
> -       that was turned into a xdg_surface with
> -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> -       like maximized and fullscreen, are lost. The wl_surface loses
> -       its role as a xdg_surface. The wl_surface is unmapped.
> +      <description summary="Destroy the xdg_surface">
> +       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.
>        </description>
>      </request>
>
>      <request name="set_parent">
> -      <description summary="surface is a child of another surface">
> -       Child surfaces are stacked above their parents, and will be
> -       unmapped if the parent is unmapped too. They should not appear
> -       on task bars and alt+tab.
> +      <description summary="set the parent of this surface">
> +       Set the "parent" of this surface. This window should be stacked
> +       above a parent. The parent surface must be mapped as long as this
> +       surface is mapped.
> +
> +       Parent windows should be set on dialogs, toolboxes, or other
> +       "auxilliary" surfaces, so that the parent is raised when the dialog
> +       is raised.
>        </description>
>        <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
>      </request>
> @@ -168,14 +166,19 @@
>      </request>
>
>      <request name="set_app_id">
> -      <description summary="set surface class">
> -       Set an id for the surface.
> +      <description summary="set application ID">
> +       Set an application identifier for the surface.
> +
> +       The app ID identifies the general class of applications to which
> +       the surface belongs. The compositor can use this to group multiple
> +       applications together, or to determine how to launch a new
> +       application.


Given this is an application specific property why is it in
xdg_surface instead of being in xdg_shell?

>
> -       The app id identifies the general class of applications to which
> -       the surface belongs.
> +       See the desktop-entry specification [0] for more details on
> +       application identifiers and how they relate to well-known DBus
> +       names and .desktop files.
>
> -       It should be the ID that appears in the new desktop entry
> -       specification, the interface name.
> +       [0] http://standards.freedesktop.org/desktop-entry-spec/
>        </description>
>        <arg name="app_id" type="string"/>
>      </request>
> @@ -187,29 +190,32 @@
>          user a menu that they can use to maximize or minimize the window.
>
>          This request asks the compositor to pop up such a window menu at
> -        the given position, relative to the parent surface. There are
> -        no guarantees as to what the window menu contains.
> +        the given position, relative to the local surface coordinates of
> +        the parent surface. There are no guarantees as to what menu items
> +        the window menu contains.
>
> -        Your surface must have focus on the seat passed in to pop up the
> -        window menu.
> +        This request must be used in response to some sort of user action
> +        like a button press, key press, or touch down event.
>        </description>
>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the seat to pop the window up on"/>
> -      <arg name="serial" type="uint" summary="serial of the event to pop up the window for"/>
> +      <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" summary="the x position to pop up the window menu at"/>
>        <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
>      </request>
>
>      <request name="move">
>        <description summary="start an interactive move">
> -       Start a pointer-driven move of the surface.
> +       Start an interactive, user-driven move of the surface.
> +
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>
> -       This request must be used in response to a button press event.
>         The server may ignore move requests depending on the state of
>         the surface (e.g. fullscreen or maximized).
>        </description>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
> +      <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>
>
>      <enum name="resize_edge">
> @@ -232,14 +238,16 @@
>
>      <request name="resize">
>        <description summary="start an interactive resize">
> -       Start a pointer-driven resizing of the surface.
> +       Start a user-driven, interactive resize of the surface.
> +
> +       This request must be used in response to some sort of user action
> +       like a button press, key press, or touch down event.
>
> -       This request must be used in response to a button press event.
>         The server may ignore resize requests depending on the state of
>         the surface (e.g. fullscreen or maximized).
>        </description>
> -      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
> -      <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
> +      <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="edges" type="uint" summary="which edge or corner is being dragged"/>
>      </request>
>
> @@ -287,16 +295,21 @@
>
>      <event name="configure">
>        <description summary="suggest a surface change">
> -       The configure event asks the client to resize its surface.
> +       The configure event asks the client to resize its surface or to
> +       change its state.
>
>         The width and height arguments specify a hint to the window
> -        about how its surface should be resized in window geometry
> -        coordinates. The states listed in the event specify how the
> -        width/height arguments should be interpreted.
> +       about how its surface should be resized in window geometry
> +       coordinates.
> +
> +       The states listed in the event specify how the width/height
> +       arguments should be interpreted, and possibly how it should be
> +       drawn.
>
> -        A client should arrange a new surface, and then send a
> -        ack_configure request with the serial sent in this configure
> -        event before attaching a new surface.
> +       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
> @@ -311,14 +324,20 @@
>
>      <request name="ack_configure">
>        <description summary="ack a configure event">
> -        When a configure event is received, a client should then ack it
> -        using the ack_configure request to ensure that the compositor
> -        knows the client has seen the event.
> -
> -        By this point, the state is confirmed, and the next attach should
> -        contain the buffer drawn for the configure event you are acking.
> +        When a configure event is received, if a client is updating
> +        and redrawing its state in response to the configure event,
> +        then the client needs to make an ack_configure request before
> +        point the commit to mark this next commit as being a
> +        reaction to the configure.
> +
> +        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.
>        </description>
> -      <arg name="serial" type="uint" summary="a serial to configure for"/>
> +      <arg name="serial" type="uint" summary="the serial from the configure event"/>
>      </request>
>
>      <request name="set_window_geometry">
> @@ -328,15 +347,20 @@
>          portions like drop-shadows which should be ignored for the
>          purposes of aligning, placing and constraining windows.
>
> -        The default value is the full bounds of the surface, including any
> -        subsurfaces. Once the window geometry of the surface is set once,
> -        it is not possible to unset it, and it will remain the same until
> +        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 width and height must be greater than zero.
>        </description>
>        <arg name="x" type="int"/>
>        <arg name="y" type="int"/>
> @@ -359,7 +383,18 @@
>      </request>
>      <request name="unset_fullscreen" />
>
> -    <request name="set_minimized" />
> +    <request name="set_minimized">
> +      <description summary="set the window as minimized">
> +       Request that the compositor minimize your surface. There is no
> +       way to know if the surface is currently minimized, nor is there
> +       any way to unset minimization on this surface.
> +
> +       If you are looking to throttle redrawing when minimized, please
> +       instead use the wl_surface.frame event for this, as this will
> +       also work with live previews on windows in Alt-Tab, Expose or
> +       similar compositor features.
> +      </description>
> +    </request>
>
>      <event name="close">
>        <description summary="surface wants to be closed">
> @@ -376,26 +411,48 @@
>    </interface>
>
>    <interface name="xdg_popup" version="1">
> -    <description summary="desktop-style metadata interface">
> -      An interface that may be implemented by a wl_surface, for
> -      implementations that provide a desktop-style popups/menus. A popup
> -      surface is a transient surface with an added pointer grab.
> -
> -      An existing implicit grab will be changed to owner-events mode,
> -      and the popup grab will continue after the implicit grab ends
> -      (i.e. releasing the mouse button does not cause the popup to be
> -      unmapped).
> -
> -      The popup grab continues until the window is destroyed or a mouse
> -      button is pressed in any other clients window. A click in any of
> -      the clients surfaces is reported as normal, however, clicks in
> -      other clients surfaces will be discarded and trigger the callback.
> -
> -      The x and y arguments specify the locations of the upper left
> -      corner of the surface relative to the upper left corner of the
> -      parent surface, in surface local coordinates.
> -
> -      xdg_popup surfaces are always transient for another surface.
> +    <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
> +      request.
> +
> +      The parent surface must have either an xdg_surface or xdg_popup
> +      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.
> +
> +      When compositors choose to dismiss a popup if the user clicks
> +      outside the window, they will likely dismiss every nested popup
> +      as well.
> +
> +      The x and y arguments specify where the top left of the popup
> +      should be placed, relative to the local surface coordinates of the
> +      parent surface.
>      </description>
>
>      <enum name="error">
> @@ -407,19 +464,18 @@
>
>      <request name="destroy" type="destructor">
>        <description summary="remove xdg_surface interface">
> -       The xdg_surface interface is removed from the wl_surface object
> -       that was turned into a xdg_surface with
> -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> -       like maximized and fullscreen, are lost. The wl_surface loses
> -       its role as a xdg_surface. The wl_surface is unmapped.
> +       This destroys the popup. Explicitly destroying the xdg_popup
> +       object will also dismiss the popup, and unmap the surface.
> +
> +       If this xdg_popup is not the "topmost" popup, a protocol error
> +       will be sent.
>        </description>
>      </request>
>
>      <event name="popup_done">
>        <description summary="popup interaction is done">
> -       The popup_done event is sent out when a popup grab is broken,
> -       that is, when the users clicks a surface that doesn't belong
> -       to the client owning the popup surface.
> +       The popup_done event is sent out when a popup is dismissed
> +       by the compositor.
>        </description>
>      </event>
>
> --
> 2.1.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
On Sat, Nov 22, 2014 at 12:28:29PM -0800, Jasper St. Pierre wrote:
> This rewrites basically all of the text inside xdg-shell to be up to
> date, clearer, and rid of wl_shell and X11 terminology.

Thanks for updating this, Jasper!

> ---
>  protocol/xdg-shell.xml | 256 ++++++++++++++++++++++++++++++-------------------
>  1 file changed, 156 insertions(+), 100 deletions(-)
> 
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 360179d..3359cf7 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -31,11 +31,15 @@
>  
>    <interface name="xdg_shell" version="1">
>      <description summary="create desktop-style surfaces">
> -      This interface is implemented by servers that provide
> -      desktop-style user interfaces.
> -
> -      It allows clients to associate a xdg_surface with
> -      a basic surface.
> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.
> +
> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.
>      </description>
>  
>      <enum name="version">
> @@ -65,33 +69,26 @@
>  
>      <request name="get_xdg_surface">
>        <description summary="create a shell surface from a surface">
> -	Create a shell surface for an existing surface.
> -
> -	This request gives the surface the role of xdg_surface. If the
> -	surface already has another role, it raises a protocol error.
> -
> -	Only one shell or popup surface can be associated with a given
> -	surface.
> +	This creates an xdg_surface for the given surface and gives it the
> +	xdg_surface role. See the documentation of xdg_surface for more details.
>        </description>

I think it should be at least strongly recommended that the client do a
round trip after the get_xdg_surface request to check for a configure
event, because that way it can make sure to draw its first frame using
the states and geometry the compositor might want to specify. This
should work fine for both tiling and floating compositors, and will
prevent a potential unnecessary redraw and/or missing the first frame.

>        <arg name="id" type="new_id" interface="xdg_surface"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>      </request>
...snip...
>      <request name="ack_configure">
>        <description summary="ack a configure event">
> -        When a configure event is received, a client should then ack it
> -        using the ack_configure request to ensure that the compositor
> -        knows the client has seen the event.
> -
> -        By this point, the state is confirmed, and the next attach should
> -        contain the buffer drawn for the configure event you are acking.
> +        When a configure event is received, if a client is updating
> +        and redrawing its state in response to the configure event,
> +        then the client needs to make an ack_configure request before
> +        point the commit to mark this next commit as being a
> +        reaction to the configure.
> +
> +        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.
>        </description>

Right now the only way a tiling compositor can know when it can move a
window for a "retile" operation is if the xdg_surface is in the
maximized state, and the client follows the "window geometry specified
in the configure event must be obeyed by the client" requirement for the
maximized state (gtk+ does not¹).

So I wonder, why not require that the application do an attach + commit
sometime soon after acking a configure (I'm not sure how to phrase this
precisely)? This way, the compositor can always expect an attach after
it sends a configure, so it will be able to move windows around
correctly even if they don't handle the maximized state correctly. I
think this should be an okay requirement to make because if the
compositor sent a configure request, the client almost certainly needs
to repaint anyway, and if it really does not, it can just re-attach the
already-attached buffer.

¹: https://bugzilla.gnome.org/show_bug.cgi?id=740946

> -      <arg name="serial" type="uint" summary="a serial to configure for"/>
> +      <arg name="serial" type="uint" summary="the serial from the configure event"/>
>      </request>
Some framework-y applications have multiple apps in one process, like
LibreOffice. There's also the Chrome / Firefox "web apps" system where you
can launch Chrome / Firefox with a URL as if the web apps were native
native.

Perhaps they should create a new xdg_shell for every app they create? I
don't know how difficult that would be for them to do.

On Mon, Dec 1, 2014 at 1:35 AM, Giulio Camuffo <giuliocamuffo@gmail.com>
wrote:
>
> 2014-11-22 22:28 GMT+02:00 Jasper St. Pierre <jstpierre@mecheye.net>:
> > This rewrites basically all of the text inside xdg-shell to be up to
> > date, clearer, and rid of wl_shell and X11 terminology.
> > ---
> >  protocol/xdg-shell.xml | 256
> ++++++++++++++++++++++++++++++-------------------
> >  1 file changed, 156 insertions(+), 100 deletions(-)
> >
> > diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> > index 360179d..3359cf7 100644
> > --- a/protocol/xdg-shell.xml
> > +++ b/protocol/xdg-shell.xml
> > @@ -31,11 +31,15 @@
> >
> >    <interface name="xdg_shell" version="1">
> >      <description summary="create desktop-style surfaces">
> > -      This interface is implemented by servers that provide
> > -      desktop-style user interfaces.
> > -
> > -      It allows clients to associate a xdg_surface with
> > -      a basic surface.
> > +      xdg_shell allows clients to turn a wl_surface into a "real window"
> > +      which can be dragged, resized, stacked, and moved around by the
> > +      user. Everything about this interface is suited towards
> traditional
> > +      desktop environments.
> > +
> > +      Destroying a bound xdg_shell object while there are surfaces
> > +      still alive with roles from this interface is illegal and will
> > +      result in a protocol error. Make sure to destroy all surfaces
> > +      before destroying this object.
> >      </description>
> >
> >      <enum name="version">
> > @@ -65,33 +69,26 @@
> >
> >      <request name="get_xdg_surface">
> >        <description summary="create a shell surface from a surface">
> > -       Create a shell surface for an existing surface.
> > -
> > -       This request gives the surface the role of xdg_surface. If the
> > -       surface already has another role, it raises a protocol error.
> > -
> > -       Only one shell or popup surface can be associated with a given
> > -       surface.
> > +       This creates an xdg_surface for the given surface and gives it
> the
> > +       xdg_surface role. See the documentation of xdg_surface for more
> details.
> >        </description>
> >        <arg name="id" type="new_id" interface="xdg_surface"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> >      </request>
> >
> >      <request name="get_xdg_popup">
> > -      <description summary="create a shell surface from a surface">
> > -       Create a popup surface for an existing surface.
> > -
> > -       This request gives the surface the role of xdg_popup. If the
> > -       surface already has another role, it raises a protocol error.
> > +      <description summary="create a popup for a surface">
> > +       This creates an xdg_popup for the given surface and gives it the
> > +       xdg_popup role. See the documentation of xdg_surface for more
> details.
> >
> > -       Only one shell or popup surface can be associated with a given
> > -       surface.
> > +       This request must be used in response to some sort of user action
> > +       like a button press, key press, or touch down event.
> >        </description>
> >        <arg name="id" type="new_id" interface="xdg_popup"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> >        <arg name="parent" type="object" interface="wl_surface"/>
> > -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> > -      <arg name="serial" type="uint" summary="serial of the implicit
> grab on the pointer"/>
> > +      <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>
> > @@ -107,7 +104,7 @@
> >          respond to the ping request, or in what timeframe. Clients
> should
> >          try to respond in a reasonable amount of time.
> >        </description>
> > -      <arg name="serial" type="uint" summary="pass this to the
> callback"/>
> > +      <arg name="serial" type="uint" summary="pass this to the pong
> request"/>
> >      </event>
> >
> >      <request name="pong">
> > @@ -120,8 +117,7 @@
> >    </interface>
> >
> >    <interface name="xdg_surface" version="1">
> > -
> > -    <description summary="desktop-style metadata interface">
> > +    <description summary="A desktop window">
> >        An interface that may be implemented by a wl_surface, for
> >        implementations that provide a desktop-style user interface.
> >
> > @@ -136,20 +132,22 @@
> >      </description>
> >
> >      <request name="destroy" type="destructor">
> > -      <description summary="remove xdg_surface interface">
> > -       The xdg_surface interface is removed from the wl_surface object
> > -       that was turned into a xdg_surface with
> > -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> > -       like maximized and fullscreen, are lost. The wl_surface loses
> > -       its role as a xdg_surface. The wl_surface is unmapped.
> > +      <description summary="Destroy the xdg_surface">
> > +       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.
> >        </description>
> >      </request>
> >
> >      <request name="set_parent">
> > -      <description summary="surface is a child of another surface">
> > -       Child surfaces are stacked above their parents, and will be
> > -       unmapped if the parent is unmapped too. They should not appear
> > -       on task bars and alt+tab.
> > +      <description summary="set the parent of this surface">
> > +       Set the "parent" of this surface. This window should be stacked
> > +       above a parent. The parent surface must be mapped as long as this
> > +       surface is mapped.
> > +
> > +       Parent windows should be set on dialogs, toolboxes, or other
> > +       "auxilliary" surfaces, so that the parent is raised when the
> dialog
> > +       is raised.
> >        </description>
> >        <arg name="parent" type="object" interface="xdg_surface"
> allow-null="true"/>
> >      </request>
> > @@ -168,14 +166,19 @@
> >      </request>
> >
> >      <request name="set_app_id">
> > -      <description summary="set surface class">
> > -       Set an id for the surface.
> > +      <description summary="set application ID">
> > +       Set an application identifier for the surface.
> > +
> > +       The app ID identifies the general class of applications to which
> > +       the surface belongs. The compositor can use this to group
> multiple
> > +       applications together, or to determine how to launch a new
> > +       application.
>
>
> Given this is an application specific property why is it in
> xdg_surface instead of being in xdg_shell?
>
> >
> > -       The app id identifies the general class of applications to which
> > -       the surface belongs.
> > +       See the desktop-entry specification [0] for more details on
> > +       application identifiers and how they relate to well-known DBus
> > +       names and .desktop files.
> >
> > -       It should be the ID that appears in the new desktop entry
> > -       specification, the interface name.
> > +       [0] http://standards.freedesktop.org/desktop-entry-spec/
> >        </description>
> >        <arg name="app_id" type="string"/>
> >      </request>
> > @@ -187,29 +190,32 @@
> >          user a menu that they can use to maximize or minimize the
> window.
> >
> >          This request asks the compositor to pop up such a window menu at
> > -        the given position, relative to the parent surface. There are
> > -        no guarantees as to what the window menu contains.
> > +        the given position, relative to the local surface coordinates of
> > +        the parent surface. There are no guarantees as to what menu
> items
> > +        the window menu contains.
> >
> > -        Your surface must have focus on the seat passed in to pop up the
> > -        window menu.
> > +        This request must be used in response to some sort of user
> action
> > +        like a button press, key press, or touch down event.
> >        </description>
> >
> > -      <arg name="seat" type="object" interface="wl_seat" summary="the
> seat to pop the window up on"/>
> > -      <arg name="serial" type="uint" summary="serial of the event to
> pop up the window for"/>
> > +      <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" summary="the x position to pop up the
> window menu at"/>
> >        <arg name="y" type="int" summary="the y position to pop up the
> window menu at"/>
> >      </request>
> >
> >      <request name="move">
> >        <description summary="start an interactive move">
> > -       Start a pointer-driven move of the surface.
> > +       Start an interactive, user-driven move of the surface.
> > +
> > +       This request must be used in response to some sort of user action
> > +       like a button press, key press, or touch down event.
> >
> > -       This request must be used in response to a button press event.
> >         The server may ignore move requests depending on the state of
> >         the surface (e.g. fullscreen or maximized).
> >        </description>
> > -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> > -      <arg name="serial" type="uint" summary="serial of the implicit
> grab on the pointer"/>
> > +      <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>
> >
> >      <enum name="resize_edge">
> > @@ -232,14 +238,16 @@
> >
> >      <request name="resize">
> >        <description summary="start an interactive resize">
> > -       Start a pointer-driven resizing of the surface.
> > +       Start a user-driven, interactive resize of the surface.
> > +
> > +       This request must be used in response to some sort of user action
> > +       like a button press, key press, or touch down event.
> >
> > -       This request must be used in response to a button press event.
> >         The server may ignore resize requests depending on the state of
> >         the surface (e.g. fullscreen or maximized).
> >        </description>
> > -      <arg name="seat" type="object" interface="wl_seat" summary="the
> wl_seat whose pointer is used"/>
> > -      <arg name="serial" type="uint" summary="serial of the implicit
> grab on the pointer"/>
> > +      <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="edges" type="uint" summary="which edge or corner is
> being dragged"/>
> >      </request>
> >
> > @@ -287,16 +295,21 @@
> >
> >      <event name="configure">
> >        <description summary="suggest a surface change">
> > -       The configure event asks the client to resize its surface.
> > +       The configure event asks the client to resize its surface or to
> > +       change its state.
> >
> >         The width and height arguments specify a hint to the window
> > -        about how its surface should be resized in window geometry
> > -        coordinates. The states listed in the event specify how the
> > -        width/height arguments should be interpreted.
> > +       about how its surface should be resized in window geometry
> > +       coordinates.
> > +
> > +       The states listed in the event specify how the width/height
> > +       arguments should be interpreted, and possibly how it should be
> > +       drawn.
> >
> > -        A client should arrange a new surface, and then send a
> > -        ack_configure request with the serial sent in this configure
> > -        event before attaching a new surface.
> > +       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
> > @@ -311,14 +324,20 @@
> >
> >      <request name="ack_configure">
> >        <description summary="ack a configure event">
> > -        When a configure event is received, a client should then ack it
> > -        using the ack_configure request to ensure that the compositor
> > -        knows the client has seen the event.
> > -
> > -        By this point, the state is confirmed, and the next attach
> should
> > -        contain the buffer drawn for the configure event you are acking.
> > +        When a configure event is received, if a client is updating
> > +        and redrawing its state in response to the configure event,
> > +        then the client needs to make an ack_configure request before
> > +        point the commit to mark this next commit as being a
> > +        reaction to the configure.
> > +
> > +        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.
> >        </description>
> > -      <arg name="serial" type="uint" summary="a serial to configure
> for"/>
> > +      <arg name="serial" type="uint" summary="the serial from the
> configure event"/>
> >      </request>
> >
> >      <request name="set_window_geometry">
> > @@ -328,15 +347,20 @@
> >          portions like drop-shadows which should be ignored for the
> >          purposes of aligning, placing and constraining windows.
> >
> > -        The default value is the full bounds of the surface, including
> any
> > -        subsurfaces. Once the window geometry of the surface is set
> once,
> > -        it is not possible to unset it, and it will remain the same
> until
> > +        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 width and height must be greater than zero.
> >        </description>
> >        <arg name="x" type="int"/>
> >        <arg name="y" type="int"/>
> > @@ -359,7 +383,18 @@
> >      </request>
> >      <request name="unset_fullscreen" />
> >
> > -    <request name="set_minimized" />
> > +    <request name="set_minimized">
> > +      <description summary="set the window as minimized">
> > +       Request that the compositor minimize your surface. There is no
> > +       way to know if the surface is currently minimized, nor is there
> > +       any way to unset minimization on this surface.
> > +
> > +       If you are looking to throttle redrawing when minimized, please
> > +       instead use the wl_surface.frame event for this, as this will
> > +       also work with live previews on windows in Alt-Tab, Expose or
> > +       similar compositor features.
> > +      </description>
> > +    </request>
> >
> >      <event name="close">
> >        <description summary="surface wants to be closed">
> > @@ -376,26 +411,48 @@
> >    </interface>
> >
> >    <interface name="xdg_popup" version="1">
> > -    <description summary="desktop-style metadata interface">
> > -      An interface that may be implemented by a wl_surface, for
> > -      implementations that provide a desktop-style popups/menus. A popup
> > -      surface is a transient surface with an added pointer grab.
> > -
> > -      An existing implicit grab will be changed to owner-events mode,
> > -      and the popup grab will continue after the implicit grab ends
> > -      (i.e. releasing the mouse button does not cause the popup to be
> > -      unmapped).
> > -
> > -      The popup grab continues until the window is destroyed or a mouse
> > -      button is pressed in any other clients window. A click in any of
> > -      the clients surfaces is reported as normal, however, clicks in
> > -      other clients surfaces will be discarded and trigger the callback.
> > -
> > -      The x and y arguments specify the locations of the upper left
> > -      corner of the surface relative to the upper left corner of the
> > -      parent surface, in surface local coordinates.
> > -
> > -      xdg_popup surfaces are always transient for another surface.
> > +    <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
> > +      request.
> > +
> > +      The parent surface must have either an xdg_surface or xdg_popup
> > +      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.
> > +
> > +      When compositors choose to dismiss a popup if the user clicks
> > +      outside the window, they will likely dismiss every nested popup
> > +      as well.
> > +
> > +      The x and y arguments specify where the top left of the popup
> > +      should be placed, relative to the local surface coordinates of the
> > +      parent surface.
> >      </description>
> >
> >      <enum name="error">
> > @@ -407,19 +464,18 @@
> >
> >      <request name="destroy" type="destructor">
> >        <description summary="remove xdg_surface interface">
> > -       The xdg_surface interface is removed from the wl_surface object
> > -       that was turned into a xdg_surface with
> > -       xdg_shell.get_xdg_surface request. The xdg_surface properties,
> > -       like maximized and fullscreen, are lost. The wl_surface loses
> > -       its role as a xdg_surface. The wl_surface is unmapped.
> > +       This destroys the popup. Explicitly destroying the xdg_popup
> > +       object will also dismiss the popup, and unmap the surface.
> > +
> > +       If this xdg_popup is not the "topmost" popup, a protocol error
> > +       will be sent.
> >        </description>
> >      </request>
> >
> >      <event name="popup_done">
> >        <description summary="popup interaction is done">
> > -       The popup_done event is sent out when a popup grab is broken,
> > -       that is, when the users clicks a surface that doesn't belong
> > -       to the client owning the popup surface.
> > +       The popup_done event is sent out when a popup is dismissed
> > +       by the compositor.
> >        </description>
> >      </event>
> >
> > --
> > 2.1.0
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel@lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>