Carcasa personalizada
«Shell personalizado» explica cómo implementar una extensión de shell personalizada.
Las extensiones del shell para Wayland son protocolos que gestionan el estado, la posición y el tamaño de las ventanas. La mayoría de los compositores admiten una o varias de las extensiones integradas, pero en algunas circunstancias puede resultar útil poder escribir una personalizada que contenga exactamente las características que necesitan tus aplicaciones.

Para ello, es necesario implementar la extensión del shell tanto en el lado del servidor como en el del cliente de la conexión Wayland, por lo que resulta especialmente útil cuando se está desarrollando una plataforma y se tiene control tanto sobre el compositor como sobre sus aplicaciones cliente.
El ejemplo «Custom Shell» muestra la implementación de una extensión de shell sencilla. Se divide en tres partes:
- Una descripción del protocolo para una interfaz de shell personalizada.
- Un complemento para conectarse a la interfaz en una aplicación cliente.
- Un compositor de ejemplo con una implementación de la interfaz en el lado del servidor.
La descripción del protocolo sigue el formato XML estándar que lee wayland-scanner. No se tratará en detalle aquí, pero incluye las siguientes características:
- Una interfaz para crear superficies de shell para un
wl_surface. Esto permite que el protocolo añada funcionalidad sobre las API existentes dewl_surface. - Una solicitud para establecer el título de una ventana en la superficie del shell.
- Una solicitud para minimizar o maximizar la superficie del shell.
- Un evento que informa al cliente del estado actual de minimización de la superficie del shell.
Para que qtwaylandscanner se ejecute automáticamente como parte de la compilación, utilizamos las funciones de CMake qt_generate_wayland_protocol_server_sources() y qt_generate_wayland_protocol_client_sources() para generar el código de enlace del lado del servidor y del lado del cliente, respectivamente. (Al utilizar qmake, las variables WAYLANDSERVERSOURCES y WAYLANDCLIENTSOURCES consiguen el mismo resultado).
El complemento de cliente
Para que un cliente Qt pueda detectar la integración con el shell, debemos reimplementar el QWaylandShellIntegrationPlugin.
class QWaylandExampleShellIntegrationPlugin : public QWaylandShellIntegrationPlugin
{
Q_OBJECT
Q_PLUGIN_METADATA(IID QWaylandShellIntegrationFactoryInterface_iid FILE "example-shell.json")
public:
QWaylandShellIntegration *create(const QString &key, const QStringList ¶mList) override;
};
QWaylandShellIntegration *QWaylandExampleShellIntegrationPlugin::create(const QString &key, const QStringList ¶mList)
{
Q_UNUSED(key);
Q_UNUSED(paramList);
return new ExampleShellIntegration();
}Esto asocia la clave «example-shell» a la integración del shell y permite que se instancie la clase ExampleShellIntegration cuando un cliente se conecte a la interfaz.
Las API para crear extensiones de shell están disponibles en el archivo de cabecera qwaylandclientshellapi_p.h.
#include <QtWaylandClient/private/qwaylandclientshellapi_p.h>Este encabezado requiere la inclusión de una API privada porque, a diferencia de las API públicas de Qt, no ofrece garantías de compatibilidad binaria. No obstante, las API se consideran estables y seguirán siendo compatibles a nivel de código fuente, y en este sentido son similares a otras API de complementos de Qt.
La clase ` ExampleShellIntegration ` es el punto de entrada del lado del cliente para crear superficies de shell, tal y como se ha descrito anteriormente. Extiende la clase `QWaylandShellIntegrationTemplate`, utilizando el patrón de plantillas curiosamente recurrentes (Curiously Recurring Template Pattern).
class Q_WAYLANDCLIENT_EXPORT ExampleShellIntegration
: public QWaylandShellIntegrationTemplate<ExampleShellIntegration>
, public QtWayland::qt_example_shell
{
public:
ExampleShellIntegration();
QWaylandShellSurface *createShellSurface(QWaylandWindow *window) override;
};También hereda de la clase ` QtWayland::qt_example_shell `, que es generada por qtwaylandscanner a partir de la descripción XML del protocolo.
El constructor especifica la versión del protocolo que admitimos:
ExampleShellIntegration::ExampleShellIntegration()
: QWaylandShellIntegrationTemplate(/* Supported protocol version */ 1)
{
}El protocolo example_shell se encuentra actualmente en la versión uno, por lo que pasamos un 1 a la clase padre. Esto se utiliza en la negociación del protocolo y garantiza que los clientes más antiguos sigan funcionando si el compositor utiliza una versión más reciente del protocolo.
Cuando se inicializa el ` ExampleShellIntegration `, la aplicación se conecta al servidor y ha recibido la difusión de las interfaces globales que admite el compositor. Si se realiza correctamente, puede enviar solicitudes para la interfaz. En este caso, solo hay una solicitud que gestionar: la creación de una superficie de shell. Utiliza la función integrada ` wlSurfaceForWindow() ` para convertir la `QWaylandWindow` en una ` wl_surface` y, a continuación, envía la solicitud. A continuación, amplía la superficie devuelta con un objeto ` ExampleShellSurface `, que se encargará de gestionar las solicitudes y los eventos de la interfaz ` qt_example_shell_surface `.
QWaylandShellSurface *ExampleShellIntegration::createShellSurface(QWaylandWindow *window)
{
if (!isActive())
return nullptr;
auto *surface = surface_create(wlSurfaceForWindow(window));
return new ExampleShellSurface(surface, window);
}La clase ` ExampleShellSurface ` hereda de dos clases.
class ExampleShellSurface : public QWaylandShellSurface
, public QtWayland::qt_example_shell_surfaceLa primera es la clase « QtWayland::qt_example_shell_surface », que se genera a partir de la descripción XML del protocolo. Esta proporciona funciones virtuales para los eventos y funciones de miembro ordinarias para las solicitudes del protocolo.
La clase « QtWayland::qt_example_shell_surface » solo tiene un único evento.
void example_shell_surface_minimize(uint32_t minimized) override;La clase ` ExampleShellSurface ` reimplementa esta función para actualizar el estado interno de la ventana. Cuando cambia el estado de la ventana, almacena el estado pendiente para más adelante y llama a ` applyConfigureWhenPossible() ` en ` QWaylandShellSurface`. Los cambios de estado, tamaño y posición deben organizarse de esta manera. De este modo, nos aseguramos de que los cambios no interfieran con el renderizado en la superficie, y de que varios cambios relacionados puedan aplicarse fácilmente como uno solo.
Cuando es seguro reconfigurar la superficie, se llama a la función virtual applyConfigure().
void ExampleShellSurface::applyConfigure()
{
if (m_stateChanged)
QWindowSystemInterface::handleWindowStateChanged(platformWindow()->window(), m_pendingStates);
m_stateChanged = false;
}Es aquí donde, efectivamente, aplicamos el nuevo estado (minimizado o desminimizado) a la ventana.
La segunda superclase es QWaylandShellSurface. Se trata de la interfaz que utilizan el complemento QPA de Wayland y QWaylandWindow para comunicarse con el shell. La clase ExampleShellSurface también reimplementa algunas funciones virtuales de esta interfaz.
bool wantsDecorations() const override;
void setTitle(const QString &) override;
void requestWindowStates(Qt::WindowStates states) override;
void applyConfigure() override;Por ejemplo, cuando una aplicación Qt establece el título de una ventana, esto se traduce en una llamada a la función virtual ` setTitle() `.
void ExampleShellSurface::setTitle(const QString &windowTitle)
{
set_window_title(windowTitle);
}En « ExampleShellSurface », esto se traduce a su vez en una solicitud en nuestra interfaz de superficie de shell personalizada.
El compositor
La parte final del ejemplo es el propio compositor. Tiene la misma estructura general que los demás ejemplos de compositores. Consulta el ejemplo «Minimal QML» para obtener más detalles sobre los componentes básicos de un Qt Wayland Compositor.
Una diferencia notable en el compositor «Custom Shell» es la instanciación de la extensión del shell. Mientras que el ejemplo «Minimal QML» instancia las extensiones del shell IviApplication, XdgShell y WlShell, el ejemplo «Custom Shell» solo crea una instancia de la extensión ExampleShell.
ExampleShell {
id: shell
onShellSurfaceCreated: (shellSurface) => {
shellSurfaces.append({shellSurface: shellSurface});
}
}Creamos la instancia de la extensión del shell como un elemento hijo directo de WaylandCompositor para que quede registrada como una interfaz global. Esto se difundirá a los clientes a medida que se conecten, y estos podrán vincularse a la interfaz tal y como se ha descrito en la sección anterior.
ExampleShell es una subclase de la interfaz generada QtWaylandServer::qt_example_shell, que contiene la API definida en el XML del protocolo. También es una subclase de QWaylandCompositorExtensionTemplate, lo que garantiza que los objetos sean reconocidos por QWaylandCompositor como extensiones.
class ExampleShell
: public QWaylandCompositorExtensionTemplate<ExampleShell>
, QtWaylandServer::qt_example_shellEsta herencia dual es un patrón típico en Qt Wayland Compositor a la hora de crear extensiones. La clase QWaylandCompositorExtensionTemplate establece la conexión entre QWaylandCompositorExtension y la clase qt_example_shell generada por qtwaylandscanner.
De forma equivalente, la clase ExampleShellSurface hereda de la clase QtWaylandServer::qt_example_shell_surface generada, así como de QWaylandShellSurfaceTemplate, lo que la convierte en una subclase de la clase ShellSurface y establece la conexión entre Qt Wayland Compositor y el código de protocolo generado.
Para que el tipo esté disponible en Qt Quick, utilizamos la macro del preprocesador Q_COMPOSITOR_DECLARE_QUICK_EXTENSION_CLASS por comodidad. Entre otras cosas, esto se encarga de inicializar automáticamente la extensión cuando se ha añadido al grafo de Qt Quick.
void ExampleShell::initialize()
{
QWaylandCompositorExtensionTemplate::initialize();
QWaylandCompositor*compositor = static_cast<QWaylandCompositor*>(extensionContainer());
if (!compositor) {
qWarning() << "Failed to find QWaylandCompositor when initializing ExampleShell";
return;
}
init(compositor->display(), 1);
}La implementación por defecto de la función ` initialize() ` registra la extensión en el compositor. Además, inicializamos la propia extensión del protocolo. Para ello, llamamos a la función generada ` init() ` en la clase ` QtWaylandServer::qt_example_shell_surface `.
También reimplementamos la función virtual generada para la solicitud « surface_create ».
void ExampleShell::example_shell_surface_create(Resource *resource, wl_resource *surfaceResource, uint32_t id)
{
QWaylandSurface *surface = QWaylandSurface::fromResource(surfaceResource);
if (!surface->setRole(ExampleShellSurface::role(), resource->handle, QT_EXAMPLE_SHELL_ERROR_ROLE))
return;
QWaylandResource shellSurfaceResource(wl_resource_create(resource->client(), &::qt_example_shell_surface_interface,
wl_resource_get_version(resource->handle), id));
auto *shellSurface = new ExampleShellSurface(this, surface, shellSurfaceResource);
emit shellSurfaceCreated(shellSurface);
}Esta función virtual se invoca cada vez que un cliente envía la solicitud a través de la conexión.
Nuestra extensión de shell solo admite un único QWaylandSurfaceRole, pero sigue siendo importante que se lo asignemos a QWaylandSurface al crear una superficie de shell para él. La razón principal es que asignar roles conflictivos a la misma superficie se considera un error de protocolo, y es responsabilidad del compositor generar este error si se produce. Establecer un rol en la superficie al adoptarla garantiza que se generará el error de protocolo si la superficie se reutiliza posteriormente con un rol diferente.
Utilizamos funciones integradas para convertir entre tipos de Wayland y Qt, y creamos un objeto ` ExampleShellSurface `. Cuando todo está preparado, emitimos la señal ` shellSurfaceCreated() `, que a su vez es interceptada en el código QML y añadida a la lista de superficies de shell.
ExampleShell {
id: shell
onShellSurfaceCreated: (shellSurface) => {
shellSurfaces.append({shellSurface: shellSurface});
}
}En ` ExampleShellSurface`, habilitamos de forma equivalente la parte de la superficie de shell de la extensión del protocolo.
Ejecución del ejemplo
Para que un cliente se conecte correctamente a la nueva extensión de shell, hay que tener en cuenta un par de detalles de configuración.
En primer lugar, el cliente debe poder encontrar el complemento de la extensión de shell. Una forma sencilla de hacerlo es configurar la variable de entorno « QT_PLUGIN_PATH » para que apunte al directorio de instalación del complemento. Dado que Qt busca los complementos por categoría, la ruta del complemento debe apuntar al directorio principal que contiene el directorio correspondiente a la categoría « wayland-shell-integration ». Así pues, si el archivo instalado es « /path/to/build/plugins/wayland-shell-integration/libexampleshellplugin.so », debes configurar « QT_PLUGIN_PATH » de la siguiente manera:
export QT_PLUGIN_PATH=/path/to/build/pluginsPara conocer otras formas de configurar el directorio del complemento, consulta la documentación del complemento.
El último paso es asegurarse de que el cliente se conecte realmente a la extensión de shell correcta. Los clientes de Qt intentarán conectarse automáticamente a las extensiones de shell integradas, pero esto se puede anular configurando la variable de entorno QT_WAYLAND_SHELL_INTEGRATION con el nombre de la extensión que se desea cargar.
export QT_WAYLAND_SHELL_INTEGRATION=example-shellY eso es todo. El ejemplo «Custom Shell» es una extensión de shell limitada con muy pocas funciones, pero puede utilizarse como punto de partida para crear extensiones especializadas.
© 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.