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

Submitted by wl@ongy.net on July 20, 2018, 9:09 a.m.

Details

Message ID 20180720090934.10308-3-wl@ongy.net
State Accepted
Commit 3ad11c68abda92a70a18691e1b15e6a31f6b27fa
Headers show
Series "Change wording in xdg-shell stable" ( rev: 2 ) in Wayland

Not browsing as part of any series.

Commit Message

wl@ongy.net July 20, 2018, 9:09 a.m.
From: Markus Ongyerth <wl@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.
---
 stable/xdg-shell/xdg-shell.xml | 45 +++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 22 deletions(-)

Patch hide | download patch | download mbox

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

Comments

On July 20, 2018 10:09 AM, <wl@ongy.net> wrote:
> From: Markus Ongyerth <wl@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@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel