XDG decoration
此接口允许合成器通告对服务端装饰的支持。
窗口装饰是由管理它们的一方认为合适的一组窗口控件，例如用于移动、调整大小和更改窗口状态的用户界面组件。
客户端可以使用此协议请求由支持的合成器进行装饰。
如果合成器和客户端未使用此协议协商使用服务端装饰，客户端将继续自行装饰。
警告！此文件中描述的协议是实验性的，可能会进行不向后兼容的更改。向后兼容的更改可以与相应的接口版本号提升一起添加。 不向后兼容的更改通过提升协议和接口名称中的版本号并重置接口版本来完成。一旦协议被宣布为稳定，协议和接口名称中的 "z" 前缀和版本号将被移除，接口版本号将被重置。
get_toplevel_decoration(id: new_id<zxdg_toplevel_decoration_v1>, toplevel: object<xdg_toplevel>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<zxdg_toplevel_decoration_v1> | |
| toplevel | object<xdg_toplevel> |
创建与给定 toplevel 关联的新装饰对象。
对于版本 1 的对象，从已附加或提交 buffer 的 xdg_toplevel 创建 xdg_toplevel_decoration 是客户端错误，并且在第一个 xdg_toplevel_decoration.configure 事件之前客户端附加或操作 buffer 的任何尝试也必须被视为错误。
对于版本 2 或更新版本的对象，允许从已附加或提交 buffer 的 xdg_toplevel 创建 xdg_toplevel_decoration。如果已附加 buffer，surface 的初始装饰模式取决于在此请求之前是否已将 xdg_toplevel_decoration 对象与 surface 关联。
如果 xdg_toplevel_decoration 已与 surface 关联，然后在没有 surface 提交的情况下被销毁，则保留先前的装饰模式。
如果在此请求之前没有 xdg_toplevel_decoration 与 surface 关联，或者在先前与 surface 关联的 xdg_toplevel_decoration 对象被销毁后执行了 surface 提交，则装饰模式假定为客户端装饰。
装饰对象允许合成器为 toplevel surface 切换服务端窗口装饰。客户端可以请求切换到另一种模式。
xdg_toplevel_decoration 对象必须在其 xdg_toplevel 之前被销毁。
destroy()
在下一次提交时切换回没有任何服务端装饰的模式，除非首先为该 surface 创建了新的 xdg_toplevel_decoration。
set_mode(mode: uint<zxdg_toplevel_decoration_v1.mode>)
参数 | 类型 | 描述 |
|---|---|---|
| mode | uint<zxdg_toplevel_decoration_v1.mode> | the decoration mode |
设置 toplevel surface 的装饰模式。这通知合成器客户端偏好提供的装饰模式。
请求装饰模式后，合成器将通过发出 xdg_surface.configure 事件来响应。客户端应随后更新其内容，如果收到的模式是服务端装饰，则不绘制装饰。客户端在提交新内容时还必须确认 configure（参见 xdg_surface.ack_configure）。
合成器可以决定不使用客户端的模式，而是强制执行不同的模式。
装饰模式取决于 xdg_toplevel 状态的客户端可以在响应 xdg_surface.configure 事件时发送 set_mode 请求，并等待下一个 xdg_surface.configure 事件以防止不需要的状态。此类客户端负责防止 configure 循环，并确保不使用相同的装饰模式发送多个连续的 set_mode 请求。
如果客户端提供了无效的模式，合成器将引发 invalid_mode 协议错误。
unset_mode()
取消设置 toplevel surface 的装饰模式。这通知合成器客户端不偏好特定的装饰模式。
此请求与 set_mode 具有相同的语义。
configure(mode: uint<zxdg_toplevel_decoration_v1.mode>)
参数 | 类型 | 描述 |
|---|---|---|
| mode | uint<zxdg_toplevel_decoration_v1.mode> | the decoration mode |
configure 事件配置有效的装饰模式。配置的状态不应立即应用。客户端必须发送 ack_configure 以响应此事件。详情请参见 xdg_surface.configure 和 xdg_surface.ack_configure。
configure 事件可以随时发送。客户端必须服从指定的模式。
error { unconfigured_buffer, already_constructed, orphaned, invalid_mode }
参数 | 值 | 描述 |
|---|---|---|
| unconfigured_buffer | 0 | xdg_toplevel 在 configure 之前附加了 buffer |
| already_constructed | 1 | xdg_toplevel 已经有装饰对象 |
| orphaned | 2 | xdg_toplevel 在装饰对象之前被销毁 |
| invalid_mode | 3 | 无效的模式 |
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| zxdg_decoration_manager_v1 | 1 | 1 | x | 1 | 2 | 1 | 1 | 1 | 1 | x | x | 1 | 1 | 1 | 1 | 1 | 1 | x |
Copyright
Copyright © 2018 Simon Ser
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.