1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtwaylandcompositor-shellextensions.html
6 \title Shell Extensions - Qt Wayland Compositor
8 In Wayland, \e{shells} are extensions which provide \e{surface semantics}. This means that they
9 provide ways for the server and client to communicate about surfaces. Surfaces, in this context,
10 are often also referred to as "windows", which is typically the representation of the surface in
13 Shell extensions provide tools for the client and server to communicate about certain things:
15 \li They can provide a way for the client to inform the server about the purpose of a surface:
16 Is it a tool-tip, a pop-up menu, or a regular application window, for instance? Based on
17 this, the server can decide on the geometry of the window and how the user can interact
19 \li They can also provide protocols for manipulating the surface, such as resizing, moving,
23 Like other extensions, support for shells is added to a compositor by instantiating them
24 as direct children of the \l WaylandCompositor top-level object. The shell extensions supported
25 by Qt are: \l{WlShell}, \l{XdgShell} and \l{IviApplication}.
28 \li \l XdgShell is an appropriate shell for desktop-style systems, where any number of
29 applications can connect and where windows can be manually resized and repositioned by
31 \li \l IviApplication is a minimalistic protocol, originally intended for In-vehicle
32 Infotainment systems. It is useful for embedded systems, where a pre-defined set of
33 applications can run, often with pre-assigned screen real estate. For some more details
34 on this protocol, see the \l{IVI Compositor}{IVI Compositor example}.
35 \li \l QtShell is a specialized shell for Qt applications which supports the window management
36 features available in Qt. It may be suitable on a platform where both the compositor and
37 client applications are written with Qt, and where applications are trusted not to abuse
38 features such as manual window positioning and "bring-to-front".
39 \li \l WlShell is mostly useful for compatibility with third-party applications. This is also
40 a desktop-style shell, but it has been deprecated and replaced by \l XdgShell.
43 When designing an embedded system from the bottom up, there are no rules determining which
44 shell extension to use. It will typically be either \l XdgShell or \l{IviApplication}. The
45 decision should be influenced by what features the system will need, and whether there are
46 applications involved which are not written in Qt and which have their own requirements.
48 A Qt Wayland Compositor can also support multiple shell extensions at once. See the
49 \l{Minimal QML}{Minimal QML example} for an example where all three shell extensions listed