服务器端装饰合成器
服务器端装饰合成器是一个简单的示例，用于演示 xdg-shell 上的服务器端窗口装饰效果。
简介
服务器端装饰合成器是一个桌面风格的 Wayland 合成器示例，实现了服务器端的窗口装饰。
有关使用 Qt Wayland Compositor ，请参阅“Minimal Qml”示例。
装饰
“窗口装饰”一词指的是窗口系统中大多数窗口所附带的附加用户界面元素。例如：
- 围绕窗口区域的图形边框，用户可以点击并拖动它来调整窗口大小。
- 窗口的标题栏，可用于移动窗口。
- 用于最大化、最小化和关闭窗口的系统工具按钮。
在 Wayland 中，传统上由客户端负责渲染这些装饰。与此同时，窗口的位置、大小和状态则属于合成器的管辖范围。某些shell 扩展可选地支持服务器端装饰。这使得合成器能够通知客户端，使其无需自行绘制窗口装饰。 取而代之的是，由合成器负责绘制窗口装饰。这与其他窗口系统（如 macOS、Windows 和 X11）中处理装饰的方式一致。值得注意的是，某些客户端可能完全不支持此功能。如果系统预计会运行此类应用程序，则也应将此因素纳入考量。
服务器端装饰的优势：
- 客户端无需在 Wayland 缓冲区中为系统 UI 预留空间。
- Qt Quick 基于 OpenGL 的客户端也不必渲染到单独的 FBO 中，再将内容复制到其 Wayland 缓冲区中。
- 客户端窗口将具有一致的外观，与使用的 UI 工具包无关。
- 系统功能（如调整大小、关闭以及更改窗口状态）集中在服务器端，而非由服务器和客户端共同处理。
代码
示例合成器仅支持XdgShell 扩展。它以通常的方式初始化该扩展，并将表面添加到ListModel 中，以便稍后访问它们。
XdgShell {
onToplevelCreated: (toplevel, xdgSurface) => shellSurfaces.append({shellSurface: xdgSurface});
}
XdgDecorationManagerV1 {
preferredMode: XdgToplevel.ServerSideDecoration
}此外，该示例还初始化了XdgDecorationManagerV1 扩展。这使其能够向客户端传达其更倾向于使用服务器端装饰的信息。
由于该接口是可选的，客户端可能不支持它，并始终绘制自己的装饰。因此，该模式仅为“首选”模式，我们在对顶级窗口进行装饰之前，需要先检查其实际模式。
Column {
id: chrome
width: shellSurfaceItem.implicitWidth
Rectangle {
visible: modelData.toplevel.decorationMode === XdgToplevel.ServerSideDecoration
width: parent.width
height: 30
gradient: "HeavyRain";
Text {
text: modelData.toplevel.title
anchors.centerIn: parent
}
Item {
anchors.right: parent.right
width: 30
height: 30
Text { text: "X"; anchors.centerIn: parent }
TapHandler {
onTapped: modelData.toplevel.sendClose()
}
}
DragHandler {
target: chrome
}
}
ShellSurfaceItem {
id: shellSurfaceItem
moveItem: parent
shellSurface: modelData
onSurfaceDestroyed: shellSurfaces.remove(index)
}
}对于每个窗口，我们都在其上方创建一个简单的标题栏。该标题栏包含渐变效果、一些文本、一个用于管理其位置的DragHandler ，以及一个关闭按钮。
上图左上角展示了一个支持装饰管理器扩展的客户端，右下角则展示了同一客户端使用客户端侧装饰的效果。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
