diff options
author | Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io> | 2021-05-18 09:46:06 +0200 |
---|---|---|
committer | Paul Olav Tvete <paul.tvete@qt.io> | 2021-08-13 14:34:53 +0200 |
commit | 089068e5c63f5cd80f6e59447df6a4d4facb9758 (patch) | |
tree | 1aea7db507bee26d9f3b9984facb5207b28b576b /examples/wayland | |
parent | 7a7bef54508a6897bec42f4d3e52cc38c09085fa (diff) | |
download | qtwayland-089068e5c63f5cd80f6e59447df6a4d4facb9758.tar.gz |
doc: Expand documentation for spanning-screens example
Add code snippets, screenshot and justification.
Task-number: QTBUG-91674
Change-Id: I96bf981db2121b0b8135fb83fb9ae16fda60c8c3
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>
Diffstat (limited to 'examples/wayland')
-rw-r--r-- | examples/wayland/spanning-screens/doc/images/spanning-screens.jpg | bin | 0 -> 77163 bytes | |||
-rw-r--r-- | examples/wayland/spanning-screens/doc/src/spanning-screens.qdoc | 50 | ||||
-rw-r--r-- | examples/wayland/spanning-screens/main.qml | 6 |
3 files changed, 53 insertions, 3 deletions
diff --git a/examples/wayland/spanning-screens/doc/images/spanning-screens.jpg b/examples/wayland/spanning-screens/doc/images/spanning-screens.jpg Binary files differnew file mode 100644 index 00000000..4f348393 --- /dev/null +++ b/examples/wayland/spanning-screens/doc/images/spanning-screens.jpg diff --git a/examples/wayland/spanning-screens/doc/src/spanning-screens.qdoc b/examples/wayland/spanning-screens/doc/src/spanning-screens.qdoc index 2594a54c..a7672b7f 100644 --- a/examples/wayland/spanning-screens/doc/src/spanning-screens.qdoc +++ b/examples/wayland/spanning-screens/doc/src/spanning-screens.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,8 +31,52 @@ * \brief Spanning Screens is an example that demonstrates how to let Wayland clients span multiple screens. * \ingroup qtwaylandcompositor-examples * - * Spanning screens is a Wayland compositor example that maximizes clients - * across a top and a bottom screen. + * \section1 Introduction + * + * Spanning screens is a Wayland compositor example that maximizes clients across a top and a bottom + * screen. + * + * \image spanning-screens.jpg + * + * 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 + * + * In \l{Qt Wayland Compositor} a screen is represented by a \l{WaylandOutput}, and a \l Window is + * used to contain the \l{Qt Quick} scene representing both clients and the compositor's UI. + * + * In this example, a multi-screen setup is emulated by creating two windows on the primary screen, + * but the code can easily be modified to target multiple physical screens. + * + * \snippet spanning-screens/main.qml enable screens + * + * Since each \l Window represents an isolated \l{Qt Quick} scene, this means we need a trick to + * have the same client content display inside both windows. The way to do this in + * \l{Qt Wayland Compositor} is to create two views of the same client content: One for the "top" + * window and one for the "bottom". The views share a reference to the same underlying graphics buffer. + * This allows us to copy different areas of the client's surface onto each of the windows. + * + * \snippet spanning-screens/main.qml create items + * + * When the client connects to the \l{Shell Extensions - Qt Wayland Compositor}{shell extension} + * \l{XdgShell}, we create two references to the surface. One of them is added to the "top" output, + * and the second to the "bottom". The item on the bottom output also gets an offset corresponding + * to the height of the top output. This ensures that the part of the client surface showing on + * the bottom output starts where the top output ends. + * + * \snippet spanning-screens/main.qml size + * + * In addition, we tell the client to resize its surface so that it fills both the top and bottom + * window. The end result is a client that spans two windows, or "screens". + * + * Referencing the same client surface from multiple items is a tool which can be used for many + * things. For a demonstration of a desktop-style compositor where windows can be moved from screen + * to screen, take a look at the + * \l{Qt Wayland Compositor Examples - Multi Screen}{Multi Screen example}. + * + * The \l{Qt Wayland Compositor Examples - Multi Output}{Multi Output example} shows how client + * surfaces can be displayed on multiple outputs with different sizes and other properties. * * \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 diff --git a/examples/wayland/spanning-screens/main.qml b/examples/wayland/spanning-screens/main.qml index 7fcb4ef9..011d91d6 100644 --- a/examples/wayland/spanning-screens/main.qml +++ b/examples/wayland/spanning-screens/main.qml @@ -69,10 +69,12 @@ WaylandCompositor { Text { text: "Top screen" } + // ![enable screens] // Enable the following to make the output target an actual screen, // for example when running on eglfs in a multi-display embedded system. // screen: Qt.application.screens[0] + // ![enable screens] } } @@ -113,6 +115,7 @@ WaylandCompositor { onToplevelCreated: { const shellSurface = xdgSurface; + // ![create items] const topItem = chromeComponent.createObject(topSurfaceArea, { shellSurface }); @@ -121,11 +124,14 @@ WaylandCompositor { shellSurface, y: Qt.binding(function() { return -topSurfaceArea.height;}) }); + // ![create items] + // ![size] const height = topSurfaceArea.pixelHeight + bottomSurfaceArea.pixelHeight; const width = Math.max(bottomSurfaceArea.pixelWidth, topSurfaceArea.pixelWidth); const size = Qt.size(width, height); toplevel.sendFullscreen(size); + // ![size] } } } |