En esta página

QML mínimo

Minimal QML es un ejemplo sencillo que muestra cómo escribir un compositor de Wayland en QML.

QML mínimo es un ejemplo de compositor de Wayland de estilo escritorio que implementa un « Qt Wayland Compositor » completo con el menor código posible. El compositor está implementado con « Qt Quick » y QML.

Compositor QML mínimo con ventana de cliente

El objeto WaylandCompositor

El elemento de nivel superior del compositor es un ` WaylandCompositor`. Este representa el propio servidor de Wayland y gestiona las conexiones de los clientes a medida que se establecen.

Por defecto, el servidor admite el protocolo básico de Wayland para comunicarse con los clientes. Sin embargo, normalmente también querrás admitir una o más extensiones del protocolo. Esto proporciona al cliente más herramientas para influir en su papel dentro del sistema de ventanas.

Qt admite varias extensiones estándar y comunes. Además, es fácil crear y admitir extensiones personalizadas, siempre que se pueda añadir la compatibilidad tanto en el código del cliente como en el del servidor.

Extensiones de shell

Normalmente, un compositor admitirá al menos una extensión de shell. Las extensiones se añaden al compositor instanciándolas como hijos directos del objeto WaylandCompositor. Se añadirán automáticamente a su propiedad extensions y se transmitirán a los clientes cuando estos se conecten.

WlShell {
    onWlShellSurfaceCreated: (shellSurface) => shellSurfaces.append({shellSurface: shellSurface});
}
XdgShell {
    onToplevelCreated: (toplevel, xdgSurface) => shellSurfaces.append({shellSurface: xdgSurface});
}
IviApplication {
    onIviSurfaceCreated: (iviSurface) => shellSurfaces.append({shellSurface: iviSurface});
}

El ejemplo «Minimal QML » admite tres shells diferentes: WlShell, XdgShell y IviApplication.

Un cliente puede conectarse a cualquiera de ellas y esta se utilizará como canal para la comunicación entre el cliente y el compositor sobre determinados aspectos, como la creación de nuevas ventanas, la negociación del tamaño, etc.

Cuando un cliente crea una nueva superficie, su extensión activa recibirá una señal al respecto. La señal contiene un argumento ShellSurface. Dependiendo de qué extensión haya recibido la señal, este argumento será una subclase de ShellSurface: WlShellSurface, XdgSurface o IviSurface, respectivamente.

El objeto ` ShellSurface ` se puede utilizar para acceder a las funciones de la extensión del shell para esa superficie concreta. En el ejemplo mínimo de QML, simplemente queremos añadir el cliente a nuestra escena. Para registrar la existencia de la nueva ventana, la añadimos a un sencillo ` ListModel ` para guardarla de forma segura.

ListModel { id: shellSurfaces }

Creación de la escena

La mayor parte del código necesario para el compositor ya está listo. El último paso es asegurarnos de que las aplicaciones sean realmente visibles en la pantalla.

Para todos los compositores, debemos definir al menos una salida. Esto se hace instanciando un objeto ` WaylandOutput ` como hijo directo del ` WaylandCompositor`. Si solo hay una salida, esta representará la pantalla principal del sistema. (También puedes crear varios objetos ` WaylandOutput ` para gestionar varias pantallas, si están disponibles. Consulta el ejemplo «Multi Screen» para obtener más detalles al respecto).

WaylandOutput {
    sizeFollowsWindow: true
    window: Window {
        width: 1024
        height: 768
        visible: true

Dentro de ` WaylandOutput`, creamos una ventana (`Window`) que sirve de contenedor para nuestra escena. En el ejemplo, le asignamos un tamaño. Este tamaño se utiliza si el compositor se ejecuta como una aplicación dentro de otro sistema de ventanas que admita ventanas de tamaño personalizado. En un caso de uso típico en un dispositivo integrado, donde el compositor es el único servidor de pantalla en ejecución, probablemente se ejecutará en un complemento de plataforma a pantalla completa (como eglfs) y el tamaño establecido aquí no tendrá importancia.

El último paso consiste en crear elementos para cada uno de los objetos ` ShellSurface ` que se han creado. Para ello, podemos utilizar la clase ` ShellSurfaceItem `.

Repeater {
    model: shellSurfaces
    // ShellSurfaceItem handles displaying a shell surface.
    // It has implementations for things like interactive
    // resize/move, and forwarding of mouse and keyboard
    // events to the client process.
    ShellSurfaceItem {
        shellSurface: modelData
        onSurfaceDestroyed: shellSurfaces.remove(index)
    }
}

Creamos un ` ShellSurfaceItem ` para cada una de las superficies de la carcasa de nuestro modelo y las asignamos a la propiedad ` shellSurface `. Además, nos aseguramos de que el modelo se actualice cuando se destruya la superficie de la carcasa. Esto puede ocurrir cuando un cliente cierra manualmente una ventana, o si el programa se cierra o se bloquea.

Y este es todo el código necesario para crear un compositor Wayland funcional utilizando Qt Quick y QML. Para ver otro ejemplo de compositor escrito en QML pero con algunas funciones más, echa un vistazo al ejemplo Fancy Compositor.

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.