[PATCH v3 2/3] xdg-shell: Make sure wording reflects expectations

[Simon Ser]

On July 20, 2018 10:09 AM, <wl at ongy.net> wrote:
> From: Markus Ongyerth <wl at ongy.net>
>
> The wording in xdg-shell's `set_*` requests implies the compositor
> *will* honour the client's request.
> This would give clients the control over their actual state, while the
> general expectation is that clients kindly ask for state changes which
> the compositor may follow.
> This patch ensures the actual protocol text reflects these expectations.

Reviewed-By: Simon Ser <contact at emersion.fr>

> ---
>  stable/xdg-shell/xdg-shell.xml | 45 +++++++++++++++++-----------------
>  1 file changed, 23 insertions(+), 22 deletions(-)
>
> diff --git a/stable/xdg-shell/xdg-shell.xml b/stable/xdg-shell/xdg-shell.xml
> index 213b227..08708dd 100644
> --- a/stable/xdg-shell/xdg-shell.xml
> +++ b/stable/xdg-shell/xdg-shell.xml
> @@ -866,11 +866,11 @@
>  	Maximize the surface.
>
>  	After requesting that the surface should be maximized, the compositor
> -	will respond by emitting a configure event with the "maximized" state
> -	and the required window geometry. The client should then update its
> -	content, drawing it in a maximized state. The client must also
> -	acknowledge the configure when committing the new content (see
> -	ack_configure).
> +	will respond by emitting a configure event. Whether this configure
> +	actually sets the window maximized is subject to compositor policies.
> +	The client must then update its content, drawing in the configured
> +	state. The client must also acknowledge the configure when committing
> +	the new content (see ack_configure).
>
>  	It is up to the compositor to decide how and where to maximize the
>  	surface, for example which output and what region of the screen should
> @@ -880,8 +880,8 @@
>  	a configure event with the "maximized" state.
>
>  	If the surface is in a fullscreen state, this request has no direct
> -	effect. It will alter the state the surface is returned to when
> -	unmaximized if not overridden by the compositor.
> +	effect. It may alter the state the surface is returned to when
> +	unmaximized unless overridden by the compositor.
>        </description>
>      </request>
>
> @@ -890,13 +890,13 @@
>  	Unmaximize the surface.
>
>  	After requesting that the surface should be unmaximized, the compositor
> -	will respond by emitting a configure event without the "maximized"
> -	state. If available, the compositor will include the window geometry
> -	dimensions the window had prior to being maximized in the configure
> -	event. The client must then update its content, drawing it in a
> -	regular state, i.e. potentially with shadow, etc. The client must also
> -	acknowledge the configure when committing the new content (see
> -	ack_configure).
> +	will respond by emitting a configure event. Whether this actually
> +	un-maximizes the window is subject to compositor policies.
> +	If available and applicable, the compositor will include the window
> +	geometry dimensions the window had prior to being maximized in the
> +	configure event. The client must then update its content, drawing it in
> +	the configured state. The client must also acknowledge the configure
> +	when committing the new content (see ack_configure).
>
>  	It is up to the compositor to position the surface after it was
>  	unmaximized; usually the position the surface had before maximizing, if
> @@ -906,8 +906,8 @@
>  	emit a configure event without the "maximized" state.
>
>  	If the surface is in a fullscreen state, this request has no direct
> -	effect. It will alter the state the surface is returned to when
> -	unmaximized if not overridden by the compositor.
> +	effect. It may alter the state the surface is returned to when
> +	unmaximized unless overridden by the compositor.
>        </description>
>      </request>
>
> @@ -916,10 +916,10 @@
>  	Make the surface fullscreen.
>
>  	After requesting that the surface should be fullscreened, the
> -	compositor will respond by emitting a configure event with the
> -	"fullscreen" state and the fullscreen window geometry. The client must
> -	also acknowledge the configure when committing the new content (see
> -	ack_configure).
> +	compositor will respond by emitting a configure event. Whether the
> +	client is actually put into a fullscreen state is subject to compositor
> +	policies. The client must also acknowledge the configure when
> +	committing the new content (see ack_configure).
>
>  	The output passed by the request indicates the client's preference as
>  	to which display it should be set fullscreen on. If this value is NULL,
> @@ -945,8 +945,9 @@
>  	Make the surface no longer fullscreen.
>
>  	After requesting that the surface should be unfullscreened, the
> -	compositor will respond by emitting a configure event without the
> -	"fullscreen" state.
> +	compositor will respond by emitting a configure event.
> +	Whether this actually removes the fullscreen state of the client is
> +	subject to compositor policies.
>
>  	Making a surface unfullscreen sets states for the surface based on the following:
>  	* the state(s) it may have had before becoming fullscreen
> --
> 2.18.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel