En esta página

IVI Compositor

IVI Compositor es un ejemplo que muestra cómo utilizar la extensión « IviApplication ».

Introducción

Este ejemplo muestra cómo utilizar la extensión de shell IviApplication en un servidor de pantalla Wayland (también conocido como compositor Wayland).

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

El protocolo

IviApplication es una extensión de shell diseñada específicamente para crear sistemas de infoentretenimiento a bordo de vehículos.

Se trata de un protocolo minimalista que solo ofrece las siguientes funcionalidades:

  1. El cliente puede identificarse mediante un IVI-id.
  2. El servidor puede solicitar que el cliente cambie su tamaño.
Los números de identificación

En una configuración típica de « IviApplication », se dispone de un conjunto predefinido de aplicaciones que pueden conectarse al servidor. Dado que estas aplicaciones ya se conocen en el momento del diseño del sistema, se les pueden asignar números fijos que las identifiquen. Puesto que el cliente y el servidor acuerdan estos números de antemano, se puede incorporar semántica a los números de identificación.

Por ejemplo, si un cliente se identifica como la aplicación de navegación, el servidor puede reconocerlo y asignarle una parte grande y centrada de la pantalla para su ventana. Por otro lado, a una aplicación que se identifique como un reloj se le podría asignar un área más pequeña en los márgenes de la pantalla.

Por defecto, las aplicaciones Qt anuncian sus PID del sistema («ID de proceso») como IVI-id. El cliente puede anular esto configurando QT_IVI_SURFACE_ID en su entorno antes de conectarse al servidor.

El ejemplo

Un « Qt Wayland Compositor » puede admitir varias extensiones de shell a la vez, pero el ejemplo IVICompositor solo admite el protocolo IviApplication. Esto significa que los clientes también deben admitir esta extensión de shell para poder conectarse al servidor.

La ventana del compositor del ejemplo está dividida horizontalmente en dos partes: un área izquierda destinada a una aplicación especializada con el identificador «1337» y un área derecha para el resto de aplicaciones.

Ventana del compositor dividida horizontalmente, con el área de la izquierda para la aplicación con ID «1337» y la de la derecha para otras aplicaciones

Creación del diseño

El diseño de la ventana se crea dentro de un objeto ` WaylandOutput`. Esto suele corresponder a una pantalla física disponible para el compositor. Si se crea un único objeto ` WaylandOutput `, como en el ejemplo de IVICompositor, normalmente se corresponderá con la pantalla principal.

WaylandOutput {
    sizeFollowsWindow: true
    window: Window {
        width: 1024
        height: 768
        visible: true
        Rectangle {
            id: leftArea
            width: parent.width / 2
            height: parent.height
            anchors.left: parent.left
            color: "cornflowerblue"
            Text {
                anchors.centerIn: parent
                text: "Ivi surface with id 1337"
            }
        }
        Rectangle {
            id: rightArea
            width: parent.width / 2
            height: parent.height
            anchors.right: parent.right
            color: "burlywood"
            Text {
                anchors.centerIn: parent
                text: "Other surfaces"
            }
        }
    }
}

El código crea un ` WaylandOutput ` para la pantalla y crea una ventana en él como contenedor de nivel superior de todo el contenido del compositor. Dentro de esta ventana, crea dos rectángulos que servirán como contenedores para las aplicaciones a medida que se conecten.

Conexión de clientes

Si no se ha realizado ninguna configuración adicional, una aplicación Qt se conectará con un IVI-id igual a su ID de proceso. Por ejemplo, si ejecutamos otra aplicación de ejemplo de Qt con -platform wayland, se le asignará el lado derecho del diseño, siempre que su ID sea diferente de «1337».

Ventana del compositor con una etiqueta y un campo de texto en la parte derecha

Sin embargo, si establecemos la variable de entorno QT_IVI_SURFACE_ID en «1337» antes de iniciar el ejemplo, se asignará al lado izquierdo del diseño.

Ventana del compositor con una etiqueta y un campo de texto en el lado izquierdo

Cuando un cliente se conecta a la interfaz ` IVIApplication `, emitirá la señal ` iviSurfaceCreated `. Es aquí donde se gestiona el posicionamiento de la superficie de la aplicación.

IviApplication {
    onIviSurfaceCreated: (iviSurface) =>  {
        var surfaceArea = iviSurface.iviId === 1337 ? leftArea : rightArea;
        var item = chromeComponent.createObject(surfaceArea, { "shellSurface": iviSurface } );
        item.handleResized();
    }
}

La señal ` iviSurfaceCreated ` recibe un argumento ` IviSurface ` que puede utilizarse para acceder al ID del cliente. A continuación, el compositor crea un ` ShellSurfaceItem ` para la superficie (tal y como se define en ` chromeComponent`). ` ShellSurfaceItem ` es la clase que se utiliza para colocar superficies de shell en la escena ` Qt Quick `, y verás este mismo patrón en todos los ejemplos de ` Qt Wayland Compositor `.

Lo que hace especial al ejemplo IVICompositor es que comprueba la propiedad iviId de la superficie de shell entrante y decide cuál será el elemento padre del ShellSurfaceItem en función de cuál sea este valor. Si el ID es igual a «1337», se vinculará al leftArea; de lo contrario, se colocará en el rightArea.

La implementación de ` ShellSurfaceItem ` gestiona el cambio de tamaño informando al cliente cada vez que este varía (lo cual puede ocurrir si el compositor se ejecuta dentro de un sistema de ventanas tipo escritorio y se modifica el tamaño de su ventana).

onWidthChanged: handleResized()
onHeightChanged: handleResized()
function handleResized() {
    if (width > 0 && height > 0)
        shellSurface.sendConfigure(Qt.size(width, height));
}

El método ` sendConfigure() ` se define en ` IviSurface ` y envía un evento al cliente. El cliente recibirá un evento de cambio de tamaño con el nuevo tamaño, de modo que pueda reorganizar su contenido.

Si varias aplicaciones se conectan a la misma zona del diseño, simplemente se apilarán según las reglas habituales de ordenación de « Qt Quick ». No hay mecanismos integrados para cerrar aplicaciones o gestionar el estado, pero esto se puede añadir fácilmente como código normal de « Qt Quick ».

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.