En esta página

Compositor de decoración del lado del servidor

El Compositor de decoración del lado del servidor es un ejemplo sencillo que muestra las decoraciones de ventanas del lado del servidor en xdg-shell.

Ventana del compositor con fondo en degradado azul-cian y cliente decorado desde el servidor

Introducción

El compositor de decoración del lado del servidor es un ejemplo de compositor de Wayland de estilo escritorio que implementa decoraciones de ventanas del lado del servidor.

Para una introducción a los principios básicos de la creación de un Qt Wayland Compositor con Qt, consulta el ejemplo «Qml mínimo».

Decoraciones

El término «decoraciones de ventana» hace referencia a la interfaz de usuario adicional que acompaña a la mayoría de las ventanas en el sistema de ventanas. Algunos ejemplos son:

  • El marco gráfico que rodea la superficie de la ventana, sobre el que el usuario puede hacer clic y arrastrar para cambiar el tamaño de la ventana.
  • La barra de título de la ventana, que puede utilizarse para moverla.
  • Los botones de herramientas del sistema para maximizar, minimizar y cerrar una ventana.

Tradicionalmente, en Wayland, la tarea de renderizar estas decoraciones ha recaído en el cliente. Al mismo tiempo, la posición, el tamaño y el estado de la ventana son competencia del compositor. Algunas extensiones del shell admiten, de forma opcional, decoraciones del lado del servidor. Esto permite que el compositor comunique a los clientes que no deben dibujar sus propias decoraciones de ventana. En su lugar, el compositor se encarga de dibujar las decoraciones de las ventanas. Esto se corresponde con la forma en que se gestionan las decoraciones en otros sistemas de ventanas, como macOS, Windows y X11. Cabe señalar que es posible que algunos clientes no sean compatibles con esto en absoluto. Si se prevé que el sistema ejecute este tipo de aplicaciones, también se debe tener esto en cuenta.

Ventajas de las decoraciones del lado del servidor:

  • Los clientes no tienen que reservar espacio para la interfaz de usuario del sistema en sus búferes de Wayland.
  • Qt Quick Además, los clientes basados en OpenGL no tienen que renderizar en un FBO independiente ni copiar el contenido en sus búferes de Wayland.
  • Las ventanas de los clientes tendrán un aspecto coherente, independientemente del kit de herramientas de interfaz de usuario que se utilice.
  • Las funciones del sistema, como cambiar el tamaño, cerrar y modificar el estado de las ventanas, se centralizan en el servidor en lugar de compartirse entre el servidor y el cliente.

El código

El compositor de ejemplo solo admite la extensión « XdgShell ». Inicializa la extensión de la forma habitual y añade superficies a un « ListModel » para poder acceder a ellas más adelante.

XdgShell {
    onToplevelCreated: (toplevel, xdgSurface) => shellSurfaces.append({shellSurface: xdgSurface});
}
XdgDecorationManagerV1 {
    preferredMode: XdgToplevel.ServerSideDecoration
}

Además, el ejemplo inicializa la extensión XdgDecorationManagerV1. Esto le permite comunicar al cliente que prefiere las decoraciones del lado del servidor.

Dado que la interfaz es opcional, podría darse el caso de que el cliente no la admita y siempre dibuje sus propias decoraciones. Por lo tanto, el modo es solo «preferido» y debemos comprobar el modo real de la ventana de nivel superior antes de decorarla.

Column {
    id: chrome
    width: shellSurfaceItem.implicitWidth
    Rectangle {
        visible: modelData.toplevel.decorationMode === XdgToplevel.ServerSideDecoration
        width: parent.width
        height: 30
        gradient: "HeavyRain";
        Text {
            text: modelData.toplevel.title
            anchors.centerIn: parent
        }
        Item {
            anchors.right: parent.right
            width: 30
            height: 30
            Text { text: "X"; anchors.centerIn: parent }
            TapHandler {
                onTapped: modelData.toplevel.sendClose()
            }
        }
        DragHandler {
            target: chrome
        }
    }
    ShellSurfaceItem {
        id: shellSurfaceItem
        moveItem: parent
        shellSurface: modelData
        onSurfaceDestroyed: shellSurfaces.remove(index)
    }
}

Para cada ventana, creamos una sencilla barra de título encima de ella. La barra de título tiene un degradado, algo de texto, un « DragHandler » que gestiona su posición y un botón de cierre.

La imagen muestra un cliente que admite las extensiones del gestor de decoraciones en la parte superior izquierda, y el mismo cliente con decoraciones del lado del cliente en la parte inferior derecha.

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.