From 7a7bef54508a6897bec42f4d3e52cc38c09085fa Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Tue, 11 May 2021 08:50:51 +0200 Subject: doc: Expand multi-output example documentation Add code snippets and an image, and explain some details in how the two different scenes are set up. Task-number: QTBUG-91674 Change-Id: If45b2ef78820d57f0ad3ec40c76a88a250ea749b Reviewed-by: Paul Olav Tvete Reviewed-by: Eskil Abrahamsen Blomfeldt --- .../multi-output/doc/images/multi-output.jpg | Bin 0 -> 62468 bytes .../wayland/multi-output/doc/src/multi-output.qdoc | 47 ++++++++++++++++++--- examples/wayland/multi-output/qml/main.qml | 12 +++--- 3 files changed, 47 insertions(+), 12 deletions(-) create mode 100644 examples/wayland/multi-output/doc/images/multi-output.jpg (limited to 'examples/wayland/multi-output') diff --git a/examples/wayland/multi-output/doc/images/multi-output.jpg b/examples/wayland/multi-output/doc/images/multi-output.jpg new file mode 100644 index 000000000..bf4dbfe53 Binary files /dev/null and b/examples/wayland/multi-output/doc/images/multi-output.jpg differ diff --git a/examples/wayland/multi-output/doc/src/multi-output.qdoc b/examples/wayland/multi-output/doc/src/multi-output.qdoc index e57ffd024..a48f541c9 100644 --- a/examples/wayland/multi-output/doc/src/multi-output.qdoc +++ b/examples/wayland/multi-output/doc/src/multi-output.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,15 +31,48 @@ \brief Multi Output is an example that demonstrates a compositor with multiple outputs. \ingroup qtwaylandcompositor-examples - Multi Output demonstrates how to display the same clients on different - \l{WaylandOutput}{WaylandOutputs} with different types of composition. + \section1 Introduction - The example opens two different windows, one for each output. When a client connects, its - WaylandSurface is displayed in a GridView on one of the outputs, while a ShellSurface - associated with the WaylandSurface is displayed with desktop-style composition on - the other output. + The Multi Output example demonstrates how to display the same clients on different + \l{WaylandOutput}{WaylandOutputs} with different types of composition. One output shows + the clients in a uniform grid, scaled to the same size. The other output is a normal + desktop-style interactive compositor window. + + \image multi-output.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 Multiple Outputs + + The example creates two different windows, one for each output. For the grid view, we connect to the + \l{WaylandCompositor::surfaceRequested}{surfaceRequested} signal. This signal is emitted for every + surface that the client creates. This allows the application to override the default response to the request + and create a custom \l{WaylandSurface}. + + \snippet multi-output/qml/main.qml onSurfaceRequested + + Upon receiving the signal, the example creates a \l WaylandQuickItem as a view of the surface. + This can be added to the Qt Quick scene like any other item. In the example, we add it to + a \l{GridView}. + + For the desktop-style window, we use the features of the \l XdgShell extension. + When the surface has been created, the \l XdgShell emits a + \l{XdgShell::toplevelCreated}{toplevelCreated} signal. + + \snippet multi-output/qml/main.qml xdgshell + + We create a \l ShellSurfaceItem to add the \l XdgToplevel to the second output. This enables + desktop-style interaction with the surface. + + When these steps are done, the client's contents are visible in both windows. The buffers + containing the client's contents are the same for both the outputs, but are visualized in two + different ways, and provide different ways for the user to interact with them. \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. + + \sa {Qt Wayland Compositor Examples - Multi Screen}, + {Qt Wayland Compositor Examples - Overview Compositor} */ diff --git a/examples/wayland/multi-output/qml/main.qml b/examples/wayland/multi-output/qml/main.qml index 7632eb9cf..5cde7411c 100644 --- a/examples/wayland/multi-output/qml/main.qml +++ b/examples/wayland/multi-output/qml/main.qml @@ -95,17 +95,19 @@ WaylandCompositor { XdgOutputManagerV1 {} - WlShell { - id: defaultShell - - onWlShellSurfaceCreated: { - var item = chromeComponent.createObject(defaultOutput.surfaceArea, { "shellSurface": shellSurface } ); + // ![xdgshell] + XdgShell { + onToplevelCreated: { + var item = chromeComponent.createObject(defaultOutput.surfaceArea, { "shellSurface": xdgSurface } ); item.surface.activated.connect(item.raise); } } + // ![xdgshell] + // ![onSurfaceRequested] onSurfaceRequested: { var surface = surfaceComponent.createObject(comp, { } ); surface.initialize(comp, client, id, version); } + // ![onSurfaceRequested] } -- cgit v1.2.3