diff options
Diffstat (limited to 'examples/wayland/fancy-compositor/doc/src/fancy-compositor.qdoc')
-rw-r--r-- | examples/wayland/fancy-compositor/doc/src/fancy-compositor.qdoc | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/examples/wayland/fancy-compositor/doc/src/fancy-compositor.qdoc b/examples/wayland/fancy-compositor/doc/src/fancy-compositor.qdoc new file mode 100644 index 000000000..4d256d2af --- /dev/null +++ b/examples/wayland/fancy-compositor/doc/src/fancy-compositor.qdoc @@ -0,0 +1,104 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \title Fancy Compositor + \example fancy-compositor + \examplecategory {Embedded} + \brief Fancy Compositor is an example that demonstrates how to write a fancy Wayland compositor in pure QML. + \ingroup qtwaylandcompositor-examples + + \section1 Introduction + + Fancy Compositor is a small desktop-style Wayland compositor example that demonstrates the power and + ease of the \l{Qt Wayland Compositor} QML APIs. + + The Fancy Compositor example is similar to the \l{Minimal QML}{Minimal QML example}, in that it is a + full-blown Wayland compositor, implemented only using QML code. + + \section1 Initializing the Compositor + + Like the \l{Minimal QML}{Minimal QML example}, Fancy Compositor supports the main + \l{Shell Extensions - Qt Wayland Compositor}{shell extensions} that are supported by Qt. + + \snippet fancy-compositor/qml/main.qml shell extensions + + These are instantiated as children of the \l{WaylandCompositor} which automatically adds + them to the list of supported interfaces which is broadcasted to clients from the server. + + When a connected client creates a surface and binds it to one of the shell extensions, the + corresponding signal is emitted. This then calls a method inside our custom \l WaylandOutput + class, which appends the \l ShellSurface to a \l{ListModel}. + + \snippet fancy-compositor/qml/CompositorScreen.qml handleShellSurface + + This model is used as the source for a \l Repeater which creates + \l{ShellSurfaceItem}{ShellSurfaceItems} inside the compositor's \l WaylandOutput. This adds a + view of the surface in the Qt Quick scene. Since it is a \l{ShellSurfaceItem}, it also has + certain interaction options for the user of the compositor, depending on which shell extension + is in use. + + \snippet fancy-compositor/qml/CompositorScreen.qml repeater + + \section1 Keyboard + + In addition to the basic windowing system functions, the Fancy Compositor also supports an + optional on-screen keyboard running in-process. This uses the \l{Qt Virtual Keyboard} module, + and will be enabled if the module is available. + + \snippet fancy-compositor/qml/Keyboard.qml keyboard + + The code is simple. We instantiate an \l InputPanel in the bottom of the output, and make sure + it is visible if and only if it is currently active. + + \snippet fancy-compositor/qml/CompositorScreen.qml keyboard + + The keyboard is then added to the \l WaylandOutput using a \l Loader element. The \l Loader is + used here to avoid having a hard dependency on the \l{Qt Virtual Keyboard} module. If loading + fails, then the compositor will continue operating normally, but without support for an + on-screen keyboard. + + Finally, we need a way for the compositor to communicate the text input to its clients. This + is done via a \c{text-input} extension. The Fancy Compositor example supports both the + \c{text_input_unstable_v2} protocol as well as Qt's \c{qt_text_input_method_unstable_v1} + protocol. + + \snippet fancy-compositor/qml/main.qml text input + + The \c{qt_text_input_method_unstable_v1} extension is added to the compositor by instantiating + the \l QtTextInputMethodManager as a child of the \l{WaylandCompositor}, and + \l{TextInputManager} adds \c{text_input_unstable_v2}. + + Newer Qt applications will pick \c{qt_text_input_method_unstable_v1} when it is available, + while other clients can use \c{text_input_unstable_v2}. + + \section1 Transitions + + In addition to the basic functionality, the Fancy Compositor example also demonstrates animated + transitions between states. + + The first of these is the \e{activation} transition. This is only supported on the \l{XdgShell}, + since this is the only shell extension which has an \l{XdgToplevel::}{activated} state. + + \snippet fancy-compositor/qml/Chrome.qml activation + + When a client window becomes activated under the \l XdgShell protocol, we trigger an animation + which makes the window "pop out" for 200 ms. + + The Fancy Compositor also supports a \e{destruction} animation. This triggers whenever the + window closes and surface is destroyed, whether this was because the client gracefully closed + its window, or even if it crashes. + + \snippet fancy-compositor/qml/Chrome.qml destruction + + To ensure that the content exists for the duration of the animation, we start by locking the + buffer. This means the final frame rendered by the client will remain in memory until we are + done with it. + + Again, we trigger an animation on the scale of the item. The animation in question imitates + turning off the power on a CRT screen, giving a visual clue to the user that the window is + closing, and didn't just vanish into thin air. + + Any sort of animated effect may be used for state changes such as these, with the full range + of Qt Quick at your disposal. +*/ |