En esta página

Fancy Compositor

Fancy Compositor es un ejemplo que muestra cómo escribir un compositor Wayland sofisticado en QML puro.

Introducción

Fancy Compositor es un pequeño ejemplo de compositor de Wayland de estilo escritorio que muestra la potencia y la facilidad de uso de las Qt Wayland Compositor API de QML.

El ejemplo Fancy Compositor es similar al ejemplo Minimal QML, ya que se trata de un compositor de Wayland completo, implementado únicamente con código QML.

Inicialización del compositor

Al igual que el ejemplo «Minimal Qml», «Fancy Compositor» admite las principales extensiones de shell compatibles con Qt.

// Shell surface extension. Needed to provide a window concept for Wayland clients.
// I.e. requests and events for maximization, minimization, resizing, closing etc.
XdgShell {
    onToplevelCreated: (toplevel, xdgSurface) => screen.handleShellSurface(xdgSurface)
}

// Minimalistic shell extension. Mainly used for embedded applications.
IviApplication {
    onIviSurfaceCreated: (iviSurface) => screen.handleShellSurface(iviSurface)
}

// Deprecated shell extension, still used by some clients
WlShell {
    onWlShellSurfaceCreated: (shellSurface) => screen.handleShellSurface(shellSurface)
}

Estas se instancian como elementos secundarios de la clase ` WaylandCompositor `, que las añade automáticamente a la lista de interfaces compatibles que el servidor difunde a los clientes.

Cuando un cliente conectado crea una superficie y la vincula a una de las extensiones del shell, se emite la señal correspondiente. A continuación, esto llama a un método dentro de nuestra clase personalizada ` WaylandOutput `, que añade la ` ShellSurface ` a un ` ListModel`.

function handleShellSurface(shellSurface) {
    shellSurfaces.append({shellSurface: shellSurface});
}

Este modelo se utiliza como fuente para una « Repeater », que crea un « ShellSurfaceItems » dentro del « WaylandOutput » del compositor. Esto añade una vista de la superficie en la escena « Qt Quick ». Al tratarse de un « ShellSurfaceItem », también ofrece ciertas opciones de interacción para el usuario del compositor, dependiendo de la extensión de shell que se esté utilizando.

Repeater {
    model: output.shellSurfaces
    // Chrome displays a shell surface on the screen (See Chrome.qml)
    Chrome {
        shellSurface: modelData
        onDestroyAnimationFinished: output.shellSurfaces.remove(index)
    }
}

Teclado

Además de las funciones básicas del sistema de ventanas, el Fancy Compositor también admite un teclado en pantalla opcional que se ejecuta en el mismo proceso. Este utiliza el Qt Virtual Keyboard módulo y se activará si dicho módulo está disponible.

import QtQuick
import QtQuick.VirtualKeyboard

InputPanel {
    visible: active
    y: active ? parent.height - height : parent.height
    anchors.left: parent.left
    anchors.right: parent.right
}

El código es sencillo. Instanciamos un InputPanel en la parte inferior de la salida y nos aseguramos de que sea visible solo si está activo en ese momento.

Loader {
    anchors.fill: parent
    source: "Keyboard.qml"
}

A continuación, el teclado se añade al ` WaylandOutput ` mediante un elemento ` Loader `. El ` Loader ` se utiliza aquí para evitar una dependencia directa del Qt Virtual Keyboard módulo. Si la carga falla, el compositor seguirá funcionando con normalidad, pero sin soporte para el teclado en pantalla.

Por último, necesitamos una forma de que el compositor comunique la entrada de texto a sus clientes. Esto se hace a través de una extensión de « text-input ». El ejemplo de Fancy Compositor admite tanto el protocolo « text_input_unstable_v2 » como el protocolo « qt_text_input_method_unstable_v1 » de Qt.

La extensión qt_text_input_method_unstable_v1 se añade al compositor instanciando QtTextInputMethodManager como hijo de WaylandCompositor, y TextInputManager añade text_input_unstable_v2.

Las aplicaciones Qt más recientes elegirán qt_text_input_method_unstable_v1 cuando esté disponible, mientras que otros clientes pueden utilizar text_input_unstable_v2.

Transiciones

Además de la funcionalidad básica, el ejemplo Fancy Compositor también muestra transiciones animadas entre estados.

La primera de ellas es la transición de activación. Esto solo es compatible con XdgShell, ya que es la única extensión de shell que tiene un estado activated.

Connections {
    target: shellSurface.toplevel !== undefined ? shellSurface.toplevel : null

    // some signals are not available on wl_shell, so let's ignore them
    ignoreUnknownSignals: true

    function onActivatedChanged() { // xdg_shell only
        if (shellSurface.toplevel.activated) {
            receivedFocusAnimation.start();
        }
    }
}

SequentialAnimation {
    id: receivedFocusAnimation

    ParallelAnimation {
        NumberAnimation { target: scaleTransform; property: "yScale"; to: 1.02; duration: 100; easing.type: Easing.OutQuad }
        NumberAnimation { target: scaleTransform; property: "xScale"; to: 1.02; duration: 100; easing.type: Easing.OutQuad }
    }
    ParallelAnimation {
        NumberAnimation { target: scaleTransform; property: "yScale"; to: 1; duration: 100; easing.type: Easing.InOutQuad }
        NumberAnimation { target: scaleTransform; property: "xScale"; to: 1; duration: 100; easing.type: Easing.InOutQuad }
    }
}

Cuando una ventana de cliente se activa bajo el protocolo « XdgShell », activamos una animación que hace que la ventana «salga a primer plano» durante 200 ms.

Fancy Compositor también admite una animación de destrucción. Esta se activa cada vez que la ventana se cierra y la superficie se destruye, ya sea porque el cliente ha cerrado la ventana de forma correcta o incluso si se produce un fallo.

onSurfaceDestroyed: {
    bufferLocked = true;
    destroyAnimation.start();
}

SequentialAnimation {
    id: destroyAnimation

    ParallelAnimation {
        NumberAnimation { target: scaleTransform; property: "yScale"; to: 2/height; duration: 150 }
        NumberAnimation { target: scaleTransform; property: "xScale"; to: 0.4; duration: 150 }
        NumberAnimation { target: chrome; property: "opacity"; to: chrome.isChild ? 0 : 1; duration: 150 }
    }
    NumberAnimation { target: scaleTransform; property: "xScale"; to: 0; duration: 150 }
    ScriptAction { script: destroyAnimationFinished() }
}

Para garantizar que el contenido permanezca durante toda la animación, empezamos bloqueando el búfer. Esto significa que el fotograma final renderizado por el cliente permanecerá en memoria hasta que hayamos terminado con él.

De nuevo, activamos una animación a escala del elemento. La animación en cuestión imita el apagado de una pantalla CRT, lo que da una pista visual al usuario de que la ventana se está cerrando y no se ha desvanecido sin más.

Se puede utilizar cualquier tipo de efecto animado para cambios de estado como estos, con toda la gama de Qt Quick a tu disposición.

Proyecto de ejemplo en code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.