7 files changed, 168 insertions, 138 deletions
diff --git a/examples/wayland/ivi-compositor/CMakeLists.txt b/examples/wayland/ivi-compositor/CMakeLists.txt
new file mode 100644
index 000000000..abab05231
--- /dev/null
+++ b/examples/wayland/ivi-compositor/CMakeLists.txt
@@ -0,0 +1,48 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.16)
+project(ivi-compositor LANGUAGES CXX)
+
+set(CMAKE_AUTOMOC ON)
+
+if(NOT DEFINED INSTALL_EXAMPLESDIR)
+    set(INSTALL_EXAMPLESDIR "examples")
+endif()
+
+set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/wayland/ivi-compositor")
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml)
+
+qt_add_executable(ivi-compositor
+    main.cpp
+)
+
+set_target_properties(ivi-compositor PROPERTIES
+    WIN32_EXECUTABLE TRUE
+    MACOSX_BUNDLE TRUE
+)
+
+target_link_libraries(ivi-compositor PUBLIC
+    Qt::Core
+    Qt::Gui
+    Qt::Qml
+)
+
+# Resources:
+set(ivi-compositor_resource_files
+    "main.qml"
+)
+
+qt6_add_resources(ivi-compositor "ivi-compositor"
+    PREFIX
+        "/"
+    FILES
+        ${ivi-compositor_resource_files}
+)
+
+install(TARGETS ivi-compositor
+    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
+    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
+    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
+)
diff --git a/examples/wayland/ivi-compositor/doc/images/ivi-compositor-1.png b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-1.png
new file mode 100644
index 000000000..8ab6b0c99
--- /dev/null
+++ b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-1.png
diff --git a/examples/wayland/ivi-compositor/doc/images/ivi-compositor-2.png b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-2.png
new file mode 100644
index 000000000..02e1a2c9f
--- /dev/null
+++ b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-2.png
diff --git a/examples/wayland/ivi-compositor/doc/images/ivi-compositor-3.png b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-3.png
new file mode 100644
index 000000000..5bde2c74d
--- /dev/null
+++ b/examples/wayland/ivi-compositor/doc/images/ivi-compositor-3.png
diff --git a/examples/wayland/ivi-compositor/doc/src/ivi-compositor.qdoc b/examples/wayland/ivi-compositor/doc/src/ivi-compositor.qdoc
index f25eb8559..9412cca7b 100644
--- a/examples/wayland/ivi-compositor/doc/src/ivi-compositor.qdoc
+++ b/examples/wayland/ivi-compositor/doc/src/ivi-compositor.qdoc
@@ -1,44 +1,112 @@
-/****************************************************************************
-**
-** 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 - IVI Compositor
+ * \title IVI Compositor
  * \example ivi-compositor
+ * \examplecategory {Embedded}
  * \brief IVI Compositor is an example that demonstrates how to use the IviApplication extension.
  * \ingroup qtwaylandcompositor-examples
  *
- * IVI Compositor is a Wayland compositor example demonstrating how to create a
- * compositor supporting the \c ivi-application protocol.
+ * \section1 Introduction
  *
- * IVI application windows with the id 1337 will be resized to cover one half
- * of the screen, while all other windows will be resized to cover the other
- * half.
+ * This example demonstrates using the \l IviApplication shell extension in a Wayland display
+ * server (also known as a Wayland compositor).
  *
- * To start a Qt application using the \c ivi-application protocol with the
- * right id, you need to set QT_WAYLAND_SHELL_INTEGRATION to ivi-shell and
- * QT_IVI_SURFACE_ID to 1337.
+ * 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 The Protocol
+ *
+ * \l IviApplication is a \l{Shell Extensions - Qt Wayland Compositor}{shell extension} that was
+ * designed specifically for making In-vehice Infotainment systems.
+ *
+ * It is a minimalistic protocol, and only provides the following functionality:
+ *
+ * \list 1
+ *   \li The client can identify itself with an \e{IVI-id}.
+ *   \li The server can request that the client resizes itself.
+ * \endlist
+ *
+ * \section2 The Identification Numbers
+ *
+ * In a typical \l IviApplication setup, you will have a predefined set of applications that can
+ * connect to the server. Since these applications are already known when the system is designed,
+ * they can be assigned hardcoded numbers that identify them. Given that the client and server
+ * agree on these numbers ahead of time, semantics can be built into the ID numbers.
+ *
+ * For instance, if a client identifies itself as the navigation application, the server can
+ * recognize this and allocate a large, centered part of the screen for its window. An application
+ * identifying itself as a clock, on the other hand, might be delegated to a smaller area in the
+ * margins of the screen.
+ *
+ * By default, Qt applications will advertise their system PIDs ("process IDs") as the \e{IVI-id}.
+ * The client can override this by setting \c{QT_IVI_SURFACE_ID} in its environment before
+ * connecting to the server.
+ *
+ * \section1 The Example
+ *
+ * A Qt Wayland Compositor may support multiple shell extensions at once, but the
+ * \e{IVICompositor example} only supports the \l IviApplication protocol. This means that the
+ * clients have to also support this shell extension in order to connect to the server.
+ *
+ * The compositor window in the example is split into two horizontally: A left area which is
+ * designated for a specialized application with the id "1337", and a right area which is for all
+ * other applications.
+ *
+ * \image ivi-compositor-1.png
+ *
+ * \section2 Creating the Layout
+ *
+ * The layout of the window is created inside a \l WaylandOutput. This typically corresponds to
+ * a physical screen available to the compositor. If a single \l WaylandOutput is created, as in
+ * the \e{IVICompositor example}, it will usually correspond to the primary screen.
+ *
+ * \snippet ivi-compositor/main.qml wayland output
+ *
+ * The code creates a \l WaylandOutput for the screen and creates a \l Window on this as the top
+ * level container of all compositor contents. Inside this window, it creates two rectangles that
+ * will serve as containers for applications as they connect.
+ *
+ * \section2 Connecting Clients
+ *
+ * If no additional configuration has been done, a Qt application will connect with an \e{IVI-id}
+ * equal to its process ID. For instance, if we run another Qt example application with
+ * \c{-platform wayland}, it will be delegated to the right-hand side of the layout, granted that
+ * its ID is different from "1337".
+ *
+ * \image ivi-compositor-2.png
+ *
+ * However, if we set the \c{QT_IVI_SURFACE_ID} environment variable to "1337" before starting
+ * the example, it will be delegated to the left-hand side of the layout.
+ *
+ * \image ivi-compositor-3.png
+ *
+ * When a client connects to the \c IVIApplication interface, it will emit the \c{iviSurfaceCreated}
+ * signal. This is where the positioning of the application's surface is handled.
+ *
+ * \snippet ivi-compositor/main.qml connecting
+ *
+ * The \c{iviSurfaceCreated} signal receives an \l IviSurface argument which can be used to access
+ * the client's ID. The compositor then creates a \l ShellSurfaceItem for the surface (as defined by
+ * the \c chromeComponent). \c ShellSurfaceItem is the class used for placing shell surfaces into
+ * the Qt Quick scene, and you will see this same pattern in all the Qt Wayland Compositor examples.
+ *
+ * What makes the \e{IVICompositor example} special is that it checks the \c iviId property of the
+ * incoming shell surface and decides on a parent for the \l ShellSurfaceItem depending on what
+ * this is. If the ID is equal to "1337" it will be parented to the \c leftArea, and if not it will
+ * be in the \c rightArea.
+ *
+ * The implementation of the \l ShellSurfaceItem handles resizing by informing the client whenever
+ * the size changes (which can happen if the compositor is running inside a desktop-style windowing
+ * system and its window is resized).
+ *
+ * \snippet ivi-compositor/main.qml resizing
+ *
+ * The \c{sendConfigure()} method is defined in \l IviSurface and will send an event to the client.
+ * The client will receive a resize event with the new size, so it can relayout its contents.
+ *
+ * If multiple applications connect to the same area in the layout, they will simply be stacked
+ * according to normal Qt Quick ordering rules. There are no built-in mechanisms for closing
+ * applications or managing state, but this can easily be added as ordinary Qt Quick code.
  */
diff --git a/examples/wayland/ivi-compositor/main.cpp b/examples/wayland/ivi-compositor/main.cpp
index 435b4e3f1..50f48df7a 100644
--- a/examples/wayland/ivi-compositor/main.cpp
+++ b/examples/wayland/ivi-compositor/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>
diff --git a/examples/wayland/ivi-compositor/main.qml b/examples/wayland/ivi-compositor/main.qml
index 1ea965e15..555f6467c 100644
--- a/examples/wayland/ivi-compositor/main.qml
+++ b/examples/wayland/ivi-compositor/main.qml
@@ -1,58 +1,13 @@
-/****************************************************************************
-**
-** 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 2.0
-import QtWayland.Compositor 1.0
-import QtQuick.Window 2.2
+import QtQuick
+import QtWayland.Compositor
+import QtWayland.Compositor.IviApplication
+import QtQuick.Window
 
 WaylandCompositor {
+    //! [wayland output]
     WaylandOutput {
         sizeFollowsWindow: true
         window: Window {
@@ -83,23 +38,29 @@ WaylandCompositor {
             }
         }
     }
+    //! [wayland output]
     Component {
         id: chromeComponent
         ShellSurfaceItem {
             anchors.fill: parent
             onSurfaceDestroyed: destroy()
+            //! [resizing]
             onWidthChanged: handleResized()
             onHeightChanged: handleResized()
             function handleResized() {
-                shellSurface.sendConfigure(Qt.size(width, height));
+                if (width > 0 && height > 0)
+                    shellSurface.sendConfigure(Qt.size(width, height));
             }
+            //! [resizing]
         }
     }
+    //! [connecting]
     IviApplication {
-        onIviSurfaceCreated: {
+        onIviSurfaceCreated: (iviSurface) =>  {
             var surfaceArea = iviSurface.iviId === 1337 ? leftArea : rightArea;
             var item = chromeComponent.createObject(surfaceArea, { "shellSurface": iviSurface } );
             item.handleResized();
         }
     }
+    //! [connecting]
 }