From fb9fbb2647b723693a0c8135b3475adc794aaeaf Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Mon, 10 May 2021 12:17:41 +0200 Subject: 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 --- .../wayland/multi-screen/doc/src/multi-screen.qdoc | 56 ++++++++++++++++++---- examples/wayland/multi-screen/main.cpp | 2 + examples/wayland/multi-screen/qml/Chrome.qml | 2 + examples/wayland/multi-screen/qml/main.qml | 6 +++ 4 files changed, 57 insertions(+), 9 deletions(-) (limited to 'examples/wayland/multi-screen') 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] } } -- cgit v1.2.3