[v3,3/3] xdg-shell: Give compositor control over configure

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

Details

Message ID 20180720090934.10308-4-wl@ongy.net
State New
Series "Change wording in xdg-shell stable"
Headers show

Commit Message

wl@ongy.net July 20, 2018, 9:09 a.m.
From: Markus Ongyerth <wl@ongy.net>

The `[un]set_(fullscreen/maximized)` requests text requires compositors
to respon to the request with a configure event.

with the asynchronous nature of wayland protocols, this provides
essentially no benefit and might entice consumers to rely on details
that are not guaranteed.

A client can neither way for the configure event in a blocking manner
(it might receive xdg-wm-base pings, or xdg-toplevel close) before the
configure.
Nor can it rely on the next configure to be related to the event either,
since it's possible for a previous configure to already be on the wire.
Abusing this as secondary sync isn't safe either, since the compositor
might delay the response (e.g.  qubes-like considerations to heavily
restrict fullscreen).

Furthermore it was always possible for compositors to miss events
(though only in weird cases) when they destroyed the xdg-toplevel on the
server side without the client noticing.
---
 stable/xdg-shell/xdg-shell.xml | 65 +++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 28 deletions(-)

Patch hide | download patch | download mbox

diff --git a/stable/xdg-shell/xdg-shell.xml b/stable/xdg-shell/xdg-shell.xml
index 08708dd..ef8a562 100644
--- a/stable/xdg-shell/xdg-shell.xml
+++ b/stable/xdg-shell/xdg-shell.xml
@@ -866,18 +866,20 @@ 
 	Maximize the surface.
 
 	After requesting that the surface should be maximized, the compositor
-	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).
+	will send a configure event with the changed state.
+	Should the compositor decide to not honour the request, it may not
+	send anything in response.
+	Should the compositor update the client state, the client must redraw
+	with the configured state and acknowledge the configure before
+	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
 	be used.
 
-	If the surface was already maximized, the compositor will still emit
-	a configure event with the "maximized" state.
+	If the surface's state does not change (either it was already maximized,
+	or the compositor decided against maximizing it) it may still emit a
+	configure event.
 
 	If the surface is in a fullscreen state, this request has no direct
 	effect. It may alter the state the surface is returned to when
@@ -890,20 +892,20 @@ 
 	Unmaximize the surface.
 
 	After requesting that the surface should be unmaximized, the compositor
-	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).
+	will send a configure event with the changed state.
+	Should the compositor decide to not honour the request, it may not
+	send anything in response.
+	Should the compositor update the client state, it should try to
+	configure the client with the geometry it had before maximizing.
+	The client then must redraw with the configured state and acknowledge
+	the configure before 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
 	applicable.
 
-	If the surface was already not maximized, the compositor will still
-	emit a configure event without the "maximized" state.
+	If the surface state did not change, the compositor may still emit a
+	configure event.
 
 	If the surface is in a fullscreen state, this request has no direct
 	effect. It may alter the state the surface is returned to when
@@ -916,11 +918,16 @@ 
 	Make the surface fullscreen.
 
 	After requesting that the surface should be fullscreened, the
-	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
+	compositor will send a configure event with the changed state.
+	Should the compositor decide to not honour the request, it may not
+	send anything in response.
+	Should the compositor update the client state, the client must redraw
+	with the configured state and acknowledge the configure before
 	committing the new content (see ack_configure).
 
+	If the surface state did not change, the compositor may still emit a
+	configure event.
+
 	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,
 	it's up to the compositor to choose which display will be used to map
@@ -944,21 +951,23 @@ 
       <description summary="unset the window as fullscreen">
 	Make the surface no longer fullscreen.
 
+
 	After requesting that the surface should be unfullscreened, the
-	compositor will respond by emitting a configure event.
-	Whether this actually removes the fullscreen state of the client is
-	subject to compositor policies.
+	compositor will send a configure event with the changed state.
+	Should the compositor decide to not honour the request, it may not
+	send anything in response.
+	Should the compositor update the client state it should try to include
+	the client geometry from before going to fullscreen. The client must
+	redraw with the configured state and acknowledge the configure before
+	committing the new content (see ack_configure).
+
+	If the surface state did not change, the compositor may still emit a
+	configure event.
 
 	Making a surface unfullscreen sets states for the surface based on the following:
 	* the state(s) it may have had before becoming fullscreen
 	* any state(s) decided by the compositor
 	* any state(s) requested by the client while the surface was fullscreen
-
-	The compositor may include the previous window geometry dimensions in
-	the configure event, if applicable.
-
-	The client must also acknowledge the configure when committing the new
-	content (see ack_configure).
       </description>
     </request>