1 files changed, 58 insertions, 27 deletions
diff --git a/examples/wayland/overview-compositor/doc/src/overview-compositor.qdoc b/examples/wayland/overview-compositor/doc/src/overview-compositor.qdoc
index 50408bc56..8ac3dfae0 100644
--- a/examples/wayland/overview-compositor/doc/src/overview-compositor.qdoc
+++ b/examples/wayland/overview-compositor/doc/src/overview-compositor.qdoc
@@ -1,34 +1,65 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 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$
-**
-****************************************************************************/
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
- * \title Qt Wayland Compositor Examples - Overview Compositor
+ * \title Overview Compositor
  * \example overview-compositor
+ * \examplecategory {Embedded}
  * \brief Overview Compositor shows how to switch between clients in a grid.
  *
+ * \section1 Introduction
+ *
+ * Overview Compositor demonstrates selecting and activating an application
+ * from a grid of currently connected clients.
+ *
+ * \image overview-compositor.jpg
+ *
+ * For an introduction to the basic principles of creating a \l{Qt Wayland Compositor} with Qt,
+ * see the \l{Minimal QML}{Minimal QML example}.
+ *
+ * \section1 Application Grid
+ *
+ * In this example, the compositor supports two different modes of operation:
+ *
+ * \list
+ *   \li A \e fullscreen mode, where a single application window occupies the whole compositor
+ *       window and is interactable.
+ *   \li An \e overview mode, where all application windows are visible in a grid. Clicking on a
+ *       window in the grid causes it to be selected. The compositor enters fullscreen mode,
+ *       showing the selected application window.
+ * \endlist
+ *
+ * When a client connects to the compositor and creates a top-level surface, the surface will be
+ * connected to a \l{Shell Extensions - Qt Wayland Compositor}{shell extension}. The example only
+ * supports the \l{XdgShell} extension, so the client will connect to this.
+ *
+ * \snippet overview-compositor/main.qml XdgShell
+ *
+ * For each surface, we tell the client to configure it as fullscreen. In addition, the surfaces
+ * are added to a \l ListModel for easy access.
+ *
+ * This model is used by a \l Repeater to create \l{ShellSurfaceItem}{ShellSurfaceItems} inside
+ * a \l{Grid}. The \l Grid component positions the items in a grid.
+ *
+ * \snippet overview-compositor/main.qml toplevels repeater
+ *
+ * For each of the items, we create a \l MouseArea which covers the item and intercepts all mouse
+ * and touch input. This is only active when the compositor is in \e{overview} mode, and activates
+ * the application that was clicked.
+ *
+ * When the compositor goes into fullscreen mode, the same \l Grid component is used, but is scaled
+ * and translated into a position where the single selected cell fills the compositor's window. The
+ * idea is to "zoom in" on the selected cell, allowing the user to interact with the application it
+ * contains.
+ *
+ * \snippet overview-compositor/main.qml zoom transform
+ *
+ * At the bottom side of the window, there is a button which toggles between the modes. This can
+ * be used to bring back the application grid while the compositor is in fullscreen mode.
+ *
+ * This example shows one way to have the compositor visualize clients in different modes. Another
+ * way to achieve similar effects is to create multiple Qt Quick items that refer to the same
+ * surface. See \l{Multi Output}{the Multi Output example} for a demonstration.
+ *
  * \ingroup qtwaylandcompositor-examples
  */