7 files changed, 91 insertions, 248 deletions
diff --git a/examples/wayland/multi-screen/CMakeLists.txt b/examples/wayland/multi-screen/CMakeLists.txt
index d9c59f3fd..2d5ac21cb 100644
--- a/examples/wayland/multi-screen/CMakeLists.txt
+++ b/examples/wayland/multi-screen/CMakeLists.txt
@@ -1,38 +1,34 @@
-# Generated from multi-screen.pro.
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
-cmake_minimum_required(VERSION 3.14)
+cmake_minimum_required(VERSION 3.16)
 project(multi-screen LANGUAGES CXX)
 
-set(CMAKE_INCLUDE_CURRENT_DIR ON)
-
 set(CMAKE_AUTOMOC ON)
-set(CMAKE_AUTORCC ON)
-set(CMAKE_AUTOUIC ON)
 
 if(NOT DEFINED INSTALL_EXAMPLESDIR)
-  set(INSTALL_EXAMPLESDIR "examples")
+    set(INSTALL_EXAMPLESDIR "examples")
 endif()
 
 set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/wayland/multi-screen")
 
-find_package(Qt6 COMPONENTS Core)
-find_package(Qt6 COMPONENTS Gui)
-find_package(Qt6 COMPONENTS Qml)
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml)
 
 qt_add_executable(multi-screen
     main.cpp
 )
+
 set_target_properties(multi-screen PROPERTIES
     WIN32_EXECUTABLE TRUE
     MACOSX_BUNDLE TRUE
 )
+
 target_link_libraries(multi-screen PUBLIC
     Qt::Core
     Qt::Gui
     Qt::Qml
 )
 
-
 # Resources:
 set(multi-screen_resource_files
     "qml/Chrome.qml"
diff --git a/examples/wayland/multi-screen/doc/images/multi-screen.jpg b/examples/wayland/multi-screen/doc/images/multi-screen.jpg
new file mode 100644
index 000000000..f43aca07c
--- /dev/null
+++ b/examples/wayland/multi-screen/doc/images/multi-screen.jpg
diff --git a/examples/wayland/multi-screen/doc/src/multi-screen.qdoc b/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
index cd60213b5..b8113e02f 100644
--- a/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
+++ b/examples/wayland/multi-screen/doc/src/multi-screen.qdoc
@@ -1,45 +1,68 @@
-/****************************************************************************
-**
-** 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 - Multi Screen
+ * \title Multi Screen
  * \example multi-screen
+ * \examplecategory {Embedded}
  * \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.
+ * \image multi-screen.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 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
+ *
+ * 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 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. In the example, we do this at the very beginning of the \c main()
+ * function.
+ *
+ * \snippet multi-screen/main.cpp share context
  *
- * 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.
+ * \sa {Multi Output}
  */
diff --git a/examples/wayland/multi-screen/main.cpp b/examples/wayland/multi-screen/main.cpp
index 304b13c4a..438206dfb 100644
--- a/examples/wayland/multi-screen/main.cpp
+++ b/examples/wayland/multi-screen/main.cpp
@@ -1,52 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** 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.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 #include <QtCore/QUrl>
 #include <QtCore/QDebug>
@@ -57,6 +10,10 @@
 
 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..d3485e81f 100644
--- a/examples/wayland/multi-screen/qml/Chrome.qml
+++ b/examples/wayland/multi-screen/qml/Chrome.qml
@@ -1,53 +1,6 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Copyright (C) 2017 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** 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.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// Copyright (C) 2017 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 import QtQuick
 import QtWayland.Compositor
@@ -57,9 +10,12 @@ Item {
     property alias shellSurface: surfaceItem.shellSurface
     property alias surfaceItem: surfaceItem
     property alias moveItem: surfaceItem.moveItem
+    property alias output: surfaceItem.output
 
+    //! [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/CompositorScreen.qml b/examples/wayland/multi-screen/qml/CompositorScreen.qml
index 9e4d5b681..e449d6fa8 100644
--- a/examples/wayland/multi-screen/qml/CompositorScreen.qml
+++ b/examples/wayland/multi-screen/qml/CompositorScreen.qml
@@ -1,52 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** 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.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 import QtQuick
 import QtWayland.Compositor
@@ -93,7 +46,7 @@ WaylandOutput {
                 x: mouseTracker.mouseX
                 y: mouseTracker.mouseY
                 seat: comp.defaultSeat
-                visible: surface !== null && mouseTracker.containsMouse
+                visible: surface != null && mouseTracker.containsMouse
             }
         }
         Shortcut {
diff --git a/examples/wayland/multi-screen/qml/main.qml b/examples/wayland/multi-screen/qml/main.qml
index ab6d796bb..1180d30b4 100644
--- a/examples/wayland/multi-screen/qml/main.qml
+++ b/examples/wayland/multi-screen/qml/main.qml
@@ -1,57 +1,9 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Copyright (C) 2017 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** 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.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// Copyright (C) 2017 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
 import QtQml
 import QtQuick
-import QtQuick.Window as Window
 import QtWayland.Compositor
 import QtWayland.Compositor.XdgShell
 import QtWayland.Compositor.WlShell
@@ -69,6 +21,7 @@ WaylandCompositor {
 
     property bool emulated: Qt.application.screens.length < 2
 
+    //! [screens]
     Instantiator {
         id: screens
         model: emulated ? emulatedScreens : Qt.application.screens
@@ -77,12 +30,13 @@ WaylandCompositor {
             surfaceArea.color: "lightsteelblue"
             text: name
             compositor: comp
-            screen: modelData
+            screen: emulated ? Qt.application.screens[0] : modelData
             Component.onCompleted: if (!comp.defaultOutput) comp.defaultOutput = this
             position: Qt.point(virtualX, virtualY)
             windowed: emulated
         }
     }
+    //! [screens]
 
     Component {
         id: chromeComponent
@@ -99,16 +53,18 @@ WaylandCompositor {
     }
 
     WlShell {
-        onWlShellSurfaceCreated: handleShellSurfaceCreated(shellSurface)
+        onWlShellSurfaceCreated: (shellSurface) => handleShellSurfaceCreated(shellSurface)
     }
 
     XdgShell {
-        onToplevelCreated: handleShellSurfaceCreated(xdgSurface)
+        onToplevelCreated: (toplevel, xdgSurface) => handleShellSurfaceCreated(xdgSurface)
     }
 
     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 +84,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]
     }
 }