QtShell Compositor
QtShell El Compositor muestra cómo utilizar la extensión de shell « QtShell ».
QtShell Compositor es un ejemplo de compositor Wayland de estilo escritorio que implementa un « Qt Wayland Compositor » completo y que utiliza el protocolo especializado de extensión de shell denominado « QtShell ».

El compositor está implementado con Qt Quick y QML.
Establecimiento de la conexión
El ejemplo enumera QtShell como la única extensión del objeto WaylandCompositor. Esto significa que cualquier cliente que se conecte al servidor también debe ser compatible con esta extensión, por lo que deben ser aplicaciones Qt que se ejecuten con la misma versión de Qt que el compositor.
QtShell {
onQtShellSurfaceCreated: (qtShellSurface) => screen.handleShellSurface(qtShellSurface)
}Cuando un cliente se conecta a la interfaz ` QtShell `, crea un ` QtShellSurface`. El compositor recibe una notificación de ello mediante la emisión de la señal ` qtShellSurfaceCreated `. A continuación, el ejemplo añade la superficie del shell a un ` ListModel ` para facilitar el acceso posterior.
property ListModel shellSurfaces: ListModel {}
function handleShellSurface(shellSurface) {
shellSurfaces.append({shellSurface: shellSurface});
}El ` ListModel ` se utiliza como modelo para un ` Repeater `, que crea los elementos ` Qt Quick ` necesarios para mostrar el contenido del cliente en pantalla.
Repeater {
id: chromeRepeater
model: output.shellSurfaces
// Chrome displays a shell surface on the screen (See Chrome.qml)
Chrome {
shellSurface: modelData
onShellSurfaceChanged: {
if (!shellSurface)
output.shellSurfaces.remove(index)
}
}
}Utiliza el tipo local « Chrome », que gestiona los estados y las decoraciones de la ventana.
Chrome
El « Chrome » es el tipo que garantiza que el contenido del cliente sea visible y que, además, gestiona el estado, la posición y el tamaño de la ventana, entre otros aspectos. Utiliza como base el « QtShellChrome » integrado, que gestiona automáticamente el estado de la ventana (maximizada, minimizada, a pantalla completa) y su activación (asegurándose de que solo haya una ventana activa en cada momento).
Su comportamiento se puede personalizar hasta cierto punto, pero también es posible escribir la funcionalidad del « Chrome » desde cero, partiendo de un tipo básico de « Item ». « QtShellChrome » es una clase de conveniencia que proporciona el comportamiento típico de un compositor y nos ahorra el tiempo de implementar esta lógica en el ejemplo.
Independientemente de cómo se escriba el « Chrome », debe tener un « ShellSurfaceItem » para albergar el contenido del cliente.
ShellSurfaceItem {
id: shellSurfaceItemId
anchors.top: titleBar.bottom
anchors.bottom: bottomResizeHandle.top
anchors.left: leftResizeHandle.right
anchors.right: rightResizeHandle.left
moveItem: chrome
staysOnBottom: shellSurface.windowFlags & Qt.WindowStaysOnBottomHint
staysOnTop: !staysOnBottom && shellSurface.windowFlags & Qt.WindowStaysOnTopHint
}
shellSurfaceItem: shellSurfaceItemIdEl « ShellSurfaceItem » es la representación visual del contenido del cliente en la escena « Qt Quick ». Su tamaño suele coincidir con el del búfer del cliente; de lo contrario, podría verse estirado o comprimido. « QtShellChrome » se ajustará automáticamente al « windowGeometry » del « QtShellSurface », que es el tamaño del búfer del cliente más el tamaño de los márgenes del marco. Los márgenes del marco son áreas reservadas a los lados del Chrome que pueden utilizarse para contener las decoraciones de la ventana.
Por lo tanto, el ` ShellSurfaceItem ` se ancla a las decoraciones de la ventana para ocupar el área reservada al búfer del cliente.
Decoraciones de ventana
La decoración de la ventana suele ser un marco alrededor del contenido del cliente que añade información (como el título de la ventana) y la posibilidad de interacción por parte del usuario (como cambiar el tamaño, cerrar o mover la ventana, etc.).
Con « QtShell », las decoraciones de ventana siempre las dibuja el compositor y no el cliente. Para que los tamaños y las posiciones se comuniquen correctamente, « QtShell » también necesita saber qué parte de la ventana está reservada para estas decoraciones. Esto se puede gestionar automáticamente mediante « QtShellChrome », o manualmente, configurando « frameMarginLeft », « frameMarginRight », « frameMarginTop » y « frameMarginBottom ».
En los casos habituales, en los que hay controles de redimensionamiento alrededor de la ventana y una barra de título en la parte superior, resulta más cómodo utilizar los márgenes predeterminados del marco. El ejemplo « QtShell » de Compositor lo hace así.
En primer lugar, creamos elementos « Qt Quick » para representar las diferentes partes de la decoración de la ventana. En el lado izquierdo, por ejemplo, debería haber un controlador de redimensionamiento que el usuario pueda agarrar y arrastrar para cambiar el tamaño de la ventana.
Rectangle {
id: leftResizeHandle
color: "gray"
width: visible ? 5 : 0
anchors.topMargin: 5
anchors.bottomMargin: 5
anchors.left: parent.left
anchors.top: parent.top
anchors.bottom: parent.bottom
}En el ejemplo, simplemente lo definimos como un rectángulo de cinco píxeles de ancho, anclado a la parte superior, inferior e izquierda del ` Chrome`.
Del mismo modo, añadimos elementos « Qt Quick » que representan los controladores de redimensionamiento de la derecha, la parte superior, la parte inferior, la esquina superior izquierda, la esquina superior derecha, la esquina inferior izquierda y la esquina inferior derecha. También añadimos una barra de título. Una vez creadas las decoraciones y ancladas correctamente a los lados de « Chrome », configuramos las propiedades correspondientes en « QtShellChrome ».
leftResizeHandle: leftResizeHandle
rightResizeHandle: rightResizeHandle
topResizeHandle: topResizeHandle
bottomResizeHandle: bottomResizeHandle
bottomLeftResizeHandle: bottomLeftResizeHandle
bottomRightResizeHandle: bottomRightResizeHandle
topLeftResizeHandle: topLeftResizeHandle
topRightResizeHandle: topRightResizeHandle
titleBar: titleBarUna vez configuradas las propiedades de las decoraciones, se añadirá automáticamente el comportamiento predeterminado de redimensionamiento y reposicionamiento. El usuario podrá interactuar con los controladores de redimensionamiento para cambiar el tamaño de la ventana y arrastrar la barra de título para reposicionarla. Los márgenes del marco de QtShellSurface también se establecerán automáticamente para tener en cuenta el tamaño de las decoraciones (siempre que no se haya establecido explícitamente ninguna de las propiedades de los márgenes del marco).
La visibilidad de las decoraciones será gestionada automáticamente por el ` QtShellChrome ` en función de los indicadores de ventana del ` QtShellSurface`.
Gestión de ventanas
Como parte de los elementos decorativos, es habitual incluir botones de herramientas que gestionan el estado y el ciclo de vida de la ventana. En el ejemplo, estos se añaden a la barra de título.
RowLayout {
id: rowLayout
anchors.right: parent.right
anchors.rightMargin: 5
ToolButton {
text: "-"
Layout.margins: 5
visible: (chrome.windowFlags & Qt.WindowMinimizeButtonHint) != 0
onClicked: {
chrome.toggleMinimized()
}
}
ToolButton {
text: "+"
Layout.margins: 5
visible: (chrome.windowFlags & Qt.WindowMaximizeButtonHint) != 0
onClicked: {
chrome.toggleMaximized()
}
}
ToolButton {
id: xButton
text: "X"
Layout.margins: 5
visible: (chrome.windowFlags & Qt.WindowCloseButtonHint) != 0
onClicked: shellSurface.sendClose()
}
}La visibilidad de cada botón depende del indicador de ventana asociado a ese botón, y al hacer clic en cada uno de ellos, simplemente se llama al método correspondiente en ` QtShellChrome`. La excepción es el botón «cerrar», que llama al método ` sendClose()` en ` QtShellSurface`. Esto indica al cliente que se cierre y garantiza un apagado ordenado de la aplicación.
Row {
id: taskbar
height: 40
anchors.left: parent.left
anchors.right: parent.right
anchors.bottom: parent.bottom
Repeater {
anchors.fill: parent
model: output.shellSurfaces
ToolButton {
anchors.verticalCenter: parent.verticalCenter
text: modelData.windowTitle
onClicked: {
var item = chromeRepeater.itemAt(index)
if ((item.windowState & Qt.WindowMinimized) != 0)
item.toggleMinimized()
chromeRepeater.itemAt(index).activate()
}
}
}
}Como herramienta adicional de gestión de ventanas, el ejemplo cuenta con una «barra de tareas». Se trata simplemente de una fila de botones de herramientas situada en la parte inferior, junto a los títulos de las ventanas. Al hacer clic en los botones, se pueden maximizar las aplicaciones y traerlas al primer plano si están ocultas por otras ventanas. De forma similar a Chrome, utilizamos Repeater para crear los botones de herramientas y tomamos como modelo la lista de superficies del shell. Para simplificar, el ejemplo no gestiona el desbordamiento (cuando hay demasiadas aplicaciones para la barra de tareas), pero en un compositor adecuado, esto también es algo que debería tenerse en cuenta.
Por último, para evitar que las aplicaciones maximizadas se expandan hasta ocupar el área cubierta por la barra de tareas, creamos un elemento especial para gestionar las partes del espacio de la « WaylandOutput » que están disponibles para las ventanas de los clientes.
Item {
id: usableArea
anchors.top: parent.top
anchors.left: parent.left
anchors.right: parent.right
anchors.bottom: taskbar.top
}Simplemente se ancla a los lados del WaylandOutput, pero su anclaje inferior se encuentra en la parte superior de la barra de tareas.
En el Chrome, utilizamos esta área para definir el maximizedRect de la ventana.
maximizedRect: Qt.rect(usableArea.x,
usableArea.y,
usableArea.width,
usableArea.height)Por defecto, esta propiedad coincidirá con todo el WaylandOutput. En nuestro caso, sin embargo, no queremos incluir la barra de tareas en el área disponible, por lo que sobrescribimos el valor por defecto.
© 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.