1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
* \title Qt Wayland Compositor Examples - Server Side Decoration Compositor
* \example server-side-decoration
* \brief Server Side Decoration Compositor is a simple example that demonstrates server side window decorations on xdg-shell.
* \ingroup qtwaylandcompositor-examples
*
* \image server-side-decoration.png
*
* \section1 Introduction
*
* Server Side Decoration Compositor is a desktop-style Wayland compositor example implementing
* server-side window decorations.
*
* For an introduction to the basic principles of creating a \l{Qt Wayland Compositor} with Qt,
* see the \l{Qt Wayland Compositor Examples - Minimal QML}{Minimal QML example}.
*
* \section1 Decorations
*
* The term \e{window decorations} refers to the additional UI that accompanies most windows in the
* windowing system. Examples of this are:
*
* \list
* \li The graphical frame around the window surface, which a user can click and drag to resize
* the window.
* \li The title bar of the window, which might be used to move the window.
* \li The system tool buttons for maximizing, minimizing and closing a window.
* \endlist
*
* Traditionally in Wayland, it has been the client's task to render these decorations. At the same
* time, the position, size and state of the window is the compositor's domain.
* Some \l{Shell Extensions - Qt Wayland Compositor}{shell extensions} optionally support
* \e{server-side decorations}. This enables a compositor to communicate to clients that they should
* not draw their own window decorations. Instead, the compositor is responsible for drawing the
* window decorations. This corresponds to how decorations are handled on other windowing systems,
* such as macOS, Windows and X11. It is worth noting that certain clients may not support this at
* all. If the system is expected to run such applications, then this should also be taken into
* account.
*
* Benefits of server-side decorations:
* \list
* \li Clients do not have to reserve space for system UI in their Wayland buffers.
* \li Qt Quick and OpenGL-based clients do not have to render into a separate FBO and copy
* the content into their Wayland buffers.
* \li Client windows will have a consistent appearance, independent of which UI toolkit is in
* use.
* \li System functionality, such as resizing, closing and changing window state, is centralized
* in the server instead of being shared between the server and client.
* \endlist
*
* \section1 The Code
*
* The example compositor only supports the \l{XdgShell} extension. It initializes the extension in
* the usual way and adds surfaces to a \l ListModel in order to access them later.
*
* \snippet server-side-decoration/main.qml XdgShell
*
* In addition, the example initializes the \l XdgDecorationManagerV1 extension. This allows it
* to communicate to the client that it prefers server-side decorations.
*
* Since the interface is optional, it could be that the client does not support it and will always
* draw its own decorations. Therefore, the mode is only "preferred" and we need to check the actual
* mode of the top-level window before we decorate it.
*
* \snippet server-side-decoration/main.qml decoration
*
* For each window, we create a simple title bar above it. The title bar has a gradient, some text,
* a \l DragHandler which manages its position, and a close button.
*
* The image shows a client which supports the decoration manager extensions on the upper left-hand
* side, and the same client with client-side decorations on the lower, right-hand side.
*/
|