From 82ed6a62462c1e67c57dc0174602992dbed80562 Mon Sep 17 00:00:00 2001 From: Julian Orth Date: Fri, 19 Jul 2024 15:42:11 +0200 Subject: [PATCH] Add xdg-decoration-v2 protocol This protocol allows compositors and clients to announce their capabilities, preferences, and intents regarding decorations. Neither party is forced to draw or not draw decorations. For example, GNOME would always announce that it does NOT support drawing SSD. A tiling compositor would always announce that it does NOT support NOT drawing SSD while the toplevel is tiled. If the user switches a window from tiled to floating, the compositor might announce that it now supports NOT drawing SSD. If the client has announced that it can draw and prefers drawing CSD, the compositor might announce that it will stop drawing SSD after the next configure/ack sequence. Some examples: 1. A compositor that only supports drawing SSD: The compositor can essentially ignore the client's announced configuration. It will always send the following events: ``` xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_drawing_ssd xdg_toplevel_ssd_configuration_v2.draws_ssd xdg_toplevel_ssd_configuration_v2.commit ``` 2. A compositor that only supports NOT drawing SSD: The compositor can essentially ignore the client's announced configuration. It will always send the following events: ``` xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.commit ``` 3. A client that only supports drawing CSD: The client can essentially ignore the compositors's announced configuration. It will always send the following requests: ``` -> xdg_toplevel_csd_configuration_v2.supports_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit ``` 4. A client that only supports NOT drawing CSD: The client can essentially ignore the compositors's announced configuration. It will always send the following requests: ``` -> xdg_toplevel_csd_configuration_v2.supports_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit ``` 5. A compositor that fully supports NOT drawing SSD and has a poor implementation of drawing SSD: The compositor would announce support for both modes and a preference for NOT drawing SSD. If a client announces support for darwing CSD, the compositor will never draw SSD even if the client prefers SSD: ``` xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.commit -> xdg_toplevel_csd_configuration_v2.supports_drawing_csd -> xdg_toplevel_csd_configuration_v2.supports_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.commit ``` 6. A compositor that supports both drawing SSD and NOT drawing SSD: If it encounters a client that does NOT support drawing CSD, it should always draw SSD: ``` -> xdg_toplevel_csd_configuration_v2.supports_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.draws_ssd xdg_toplevel_ssd_configuration_v2.commit ``` If it encounters a client that does ONLY support drawing CSD, it should never draw SSD (unless overwritten by a user preference): ``` -> xdg_toplevel_csd_configuration_v2.supports_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.commit ``` If it encounters a client that supports both, then it might consider a configured user preference or might consider the preference announced by the client: ``` xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_drawing_ssd xdg_toplevel_ssd_configuration_v2.draws_ssd xdg_toplevel_ssd_configuration_v2.commit -> xdg_toplevel_csd_configuration_v2.supports_drawing_csd -> xdg_toplevel_csd_configuration_v2.supports_not_drawing_csd -> xdg_toplevel_csd_configuration_v2.prefers_drawing_csd -> xdg_toplevel_csd_configuration_v2.commit xdg_toplevel_ssd_configuration_v2.supports_drawing_ssd xdg_toplevel_ssd_configuration_v2.supports_not_drawing_ssd xdg_toplevel_ssd_configuration_v2.prefers_drawing_ssd xdg_toplevel_ssd_configuration_v2.commit ``` If the client does not care in such a situation, it need not announce its own configuration and can just follow the compositors preference. Additionally, the protocol allows the client to receive a default configuration without having to first create a toplevel. Signed-off-by: Julian Orth --- staging/xdg-decoration/README | 4 + staging/xdg-decoration/xdg-decoration-v2.xml | 279 +++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 staging/xdg-decoration/README create mode 100644 staging/xdg-decoration/xdg-decoration-v2.xml diff --git a/staging/xdg-decoration/README b/staging/xdg-decoration/README new file mode 100644 index 0000000..dde6b51 --- /dev/null +++ b/staging/xdg-decoration/README @@ -0,0 +1,4 @@ +xdg_decoration protocol + +Maintainers: +Julian Orth diff --git a/staging/xdg-decoration/xdg-decoration-v2.xml b/staging/xdg-decoration/xdg-decoration-v2.xml new file mode 100644 index 0000000..9f4c84b --- /dev/null +++ b/staging/xdg-decoration/xdg-decoration-v2.xml @@ -0,0 +1,279 @@ + + + + Copyright © 2018 Simon Ser + Copyright © 2024 Julian Orth + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + + + This protocol allows compositors and clients to inform each other of their + capabilities, preferences, and intent to draw decorations. + + This protocol imposes no requirements on compositors or clients. Both + parties are permitted to draw decorations at the same time. Both parties + are permitted to draw no decorations at the same time. + + If a client uses this protocol but never announces a configuration, the + compositor must behave as if the client had not used this protocol. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + + + + + This global allows clients to retrieve the compositor's default SSD + configuration and to create per-toplevel decoration objects. + + + + + This has no effect on other objects created by this object. + + + + + + The client can make this request to get the default SSD configuration of + the compositor. This is useful if the clients wants to execute logic + that depends on the compositor's capabilities and preferences before + creating any toplevels. + + The draws_ssd event has no effect for the new object and the commit + event will not be part of an xdg_surface.configure sequence. + + + + + + + Only a single decoration object can exist for an xdg_toplevel at a time. + If the client tries to create a second decoration object before + destroying the first one, the already_constructed error will be raised. + + + + + + + + In response to this event, the client might want to make a + get_default_toplevel_ssd_configuration request to update the default + configuration. + + + + + + + This protocol allows compositors and clients to inform each other of their + capabilities, preferences, and intent to draw decorations. + + After this object has been created, the compositor will immediately emit + a configure_ssd event. The compositor can emit this event at any time to + announce a change of its configuration. + + The client can announce its CSD configuration at any time by making a + configure_csd request. + + The client may destroy the underlying toplevel before destroying this + object. The behavior is as if the client had made the stop request on + this object. + + + + + + + + + The client should first make a stop request before destroying this + object to avoid races with configure_ssd events. + + This has no effect on the client's CSD configuration. If the client + wants to reset its CSD configuration, it should explicitly make a + configure_csd request first. + + This has no effect on existing xdg_toplevel_csd_configuration_v2 + objects. + + + + + + The compositor will reply with a done event and will no longer emit + configure_ssd events afterwards. + + + + + + The client should avoid making this request unless its configuration + changes. + + + + + + + The client should destroy this object after receiving this event. + + + + + + The server should avoid sending this event unless its configuration + changes. + + + + + + + + This object allows the client to inform the compositor about its + client-side decorations (CSD) support and preferences. + + The configuration consists of the following state: + + 1. Whether the client supports drawing CSD (default = false) + 2. Whether the client supports not drawing CSD (default = false) + 3. Whether the client prefers drawing CSD (default = no preference) + + The client can modify this state with the provided requests and then + commit it. If the client does not modify parts of the state, those parts + will be set to the defaults mentioned above. + + If the client announces no support for drawing CSD, then the compositor + should assume that no CSD will be drawn in any case unless the client + explicitly changes its configuration. + + If the client announce no support for not drawing CSD, then the compositor + should assume that CSD will always be drawn in any case unless the client + explicitly changes its configuration. + + + + + + + + + + + + + + + + + + + + + The compositor will use the new xdg_toplevel_ssd_configuration_v2 object + to announce its own configuration. + + + + + + + + This object allows the compositor to inform the client about its + server-side decorations (SSD) support, preferences, and intent. + + The configuration consists of the following state: + + 1. Whether the compositor supports drawing SSD (default = false) + 2. Whether the compositor supports not drawing SSD (default = false) + 3. Whether the compositor prefers drawing SSD (default = no preference) + 4. Whether the compositor intents to draw SSD (default = false) + + The compositor can modify this state with the provided events and then + commit it. If the compositor does not modify parts of the state, those + parts will be set to the defaults mentioned above. + + If the compositor announce no support for drawing SSD, then the client + should assume that no SSD will be drawn in any case unless the compositor + explicitly changes its configuration. + + If the compositor announce no support for not drawing SSD, then the client + should assume that SSD will always be drawn in any case unless the + compositor explicitly changes its configuration. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This event is part of an xdg_surface.configure sequence. The intent to + draw SSD will take affect when the client acknowledges the new + configuration and commits its new state. + + The client should destroy this object after receiving this event. + + + +