doc: Expand multi-screen documentation

Add some snippets to the example, as well as some explanation on
certain tricks that might not be obvious.

Task-number: QTBUG-91674
Change-Id: I8370afa0e70c98a4c152c8f753d9f5e37aa79da2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 57 insertions, 9 deletions

diff --git a/examples/wayland/multi-screen/doc/src/multi-screen.qdoc b/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
index 5e8e74557..e21fcf808 100644
--- a/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
+++ b/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -31,19 +31,57 @@
  * \brief Multi Screen is a desktop-style Wayland compositor for multiple screens.
  * \ingroup qtwaylandcompositor-examples
  *
+ * \section1 Introduction
+ *
  * Multi-screen is a desktop-style Wayland compositor example for multiple
  * screens.
  *
- * When a client creates a shell surface, one ShellSurfaceItem is created on
- * each screen. The ShellSurfaceItem will be visible only on one (or two)
- * screens at a time. ShellSurfaceItem positions are synchronized so that when
- * windows enter one screen they are moved off another at the same time.
+ * 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 Supporting multiple screens
+ *
+ * For each available screen on the system, the example creates a \c CompositorScreen, which is
+ * a subclass of \l WaylandOutput. If there is only one physical screen available, the example
+ * emulates three screens with dummy data.
+ *
+ * \snippet multi-screen/qml/main.qml screens
+ *
+ * Each \l WaylandOutput contains a \l{Window}, which is used for containing client content, as
+ * is the standard setup with \l{Qt Wayland Compositor}. Since each \l Window is isolated from the
+ * others, we cannot share any Qt Quick items between them. Therefore, when a client connects and
+ * a \l ShellSurface is created, one \l ShellSurfaceItem is created on each of the screens.
+ *
+ * \snippet multi-screen/qml/main.qml createShellSurfaceItems
  *
- * WaylandQuickItem::setPrimary() is called at appropriate times to set the
- * primary view for the ShellSurface, which is used when the client asks to be
- * maximized or fullscreen.
+ * These items serve as views of the same client content. The client's surface itself will only be
+ * created once, and will be shared by the surface items.
+ *
+ * Top-level surface items are created as children of the background \l Rectangle in each of the
+ * outputs. These views are stored for later, and if the client spawns any child windows, these are
+ * parented to the top-level window's item.
+ *
+ * \snippet multi-screen/qml/main.qml parenting
+ *
+ * The client content will be visible only on one or two screens at a time. \l ShellSurfaceItem
+ * positions are synchronized so that when windows enter one screen, they are moved off of another
+ * at the same time. This gives the appearance of a single item which moves seamlessly between
+ * screens. The global position of the client is stored in a shared
+ * \l{ShellSurfaceItem::moveItem}{moveItem} and relative position of each screen's
+ * \l ShellSurfaceItem is calculated based on this. If the \c moveItem is currently outside the
+ * bounds of one screen, its coordinates will reflect this, and it will be not be visible on that
+ * screen.
+ *
+ * \snippet multi-screen/qml/Chrome.qml position sync
+ *
+ * Finally, \l{WaylandQuickItem::setPrimary()} is called at appropriate times to set the primary
+ * view for the \l ShellSurface, which is used when the client asks to be maximized or fullscreen.
+ * The primary \l ShellSurfaceItem is selected based on how much of it is currently visible.
  *
  * \note In order to support multiple Wayland outputs in the same compositor, the
  * \l Qt::AA_ShareOpenGLContexts attribute must be set before the \l QGuiApplication
- * object is constructed.
+ * object is constructed. In the example, we do this at the very beginning of the \c main()
+ * function.
+ *
+ * \snippet multi-screen/main.cpp share context
  */
diff --git a/examples/wayland/multi-screen/main.cpp b/examples/wayland/multi-screen/main.cpp
index 1edb18c34..fa09e59ca 100644
--- a/examples/wayland/multi-screen/main.cpp
+++ b/examples/wayland/multi-screen/main.cpp
@@ -58,7 +58,9 @@
 int main(int argc, char *argv[])
 {
     // AA_ShareOpenGLContexts is required for compositors with multiple outputs
+    // ![share context]
     QCoreApplication::setAttribute(Qt::AA_ShareOpenGLContexts, true);
+    // ![share context]
     QGuiApplication app(argc, argv);
 
     QQmlApplicationEngine appEngine(QUrl("qrc:///qml/main.qml"));
diff --git a/examples/wayland/multi-screen/qml/Chrome.qml b/examples/wayland/multi-screen/qml/Chrome.qml
index 6c36102b8..15e865398 100644
--- a/examples/wayland/multi-screen/qml/Chrome.qml
+++ b/examples/wayland/multi-screen/qml/Chrome.qml
@@ -58,8 +58,10 @@ Item {
     property alias surfaceItem: surfaceItem
     property alias moveItem: surfaceItem.moveItem
 
+    // ![position sync]
     x: surfaceItem.moveItem.x - surfaceItem.output.geometry.x
     y: surfaceItem.moveItem.y - surfaceItem.output.geometry.y
+    // ![position sync]
 
     ShellSurfaceItem {
         id: surfaceItem
diff --git a/examples/wayland/multi-screen/qml/main.qml b/examples/wayland/multi-screen/qml/main.qml
index ab6d796bb..539a06020 100644
--- a/examples/wayland/multi-screen/qml/main.qml
+++ b/examples/wayland/multi-screen/qml/main.qml
@@ -69,6 +69,7 @@ WaylandCompositor {
 
     property bool emulated: Qt.application.screens.length < 2
 
+    //! [screens]
     Instantiator {
         id: screens
         model: emulated ? emulatedScreens : Qt.application.screens
@@ -83,6 +84,7 @@ WaylandCompositor {
             windowed: emulated
         }
     }
+    //! [screens]
 
     Component {
         id: chromeComponent
@@ -107,8 +109,10 @@ WaylandCompositor {
     }
 
     function createShellSurfaceItem(shellSurface, moveItem, output) {
+        // ![parenting]
         var parentSurfaceItem = output.viewsBySurface[shellSurface.parentSurface];
         var parent = parentSurfaceItem || output.surfaceArea;
+        // ![parenting]
         var item = chromeComponent.createObject(parent, {
             "shellSurface": shellSurface,
             "moveItem": moveItem,
@@ -128,7 +132,9 @@ WaylandCompositor {
             "width": Qt.binding(function() { return shellSurface.surface.width; }),
             "height": Qt.binding(function() { return shellSurface.surface.height; })
         });
+        //! [createShellSurfaceItems]
         for (var i = 0; i < screens.count; ++i)
             createShellSurfaceItem(shellSurface, moveItem, screens.objectAt(i));
+        //! [createShellSurfaceItems]
     }
 }