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

[Michael Forney]

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>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 473 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20141202/3b3b24e2/attachment.sig>