En esta página

Extensión personalizada

La extensión personalizada muestra cómo implementar una extensión personalizada de Wayland.

Es fácil escribir nuevas extensiones para Wayland. Se definen utilizando un formato basado en XML y la herramienta wayland-scanner las convierte en código de enlace en C. Qt amplía esta funcionalidad con qtwaylandscanner, que genera código de enlace adicional en Qt y C++.

Compositor personalizado con dos ventanas de cliente denominadas «QML Client» y «C++ Client», con paneles de colores para las solicitudes de giro y rebote

El ejemplo «Extensión personalizada» muestra cómo utilizar estas herramientas para ampliar el protocolo Wayland y enviar solicitudes y eventos personalizados entre un cliente y un servidor de Wayland.

El ejemplo consta de cuatro elementos:

  • La definición del propio protocolo.
  • Un compositor que admite la extensión.
  • Un cliente basado en C++ que admite la extensión.
  • Un cliente basado en QML que admite la extensión.

La definición del protocolo

El archivo XML custom.xml define el protocolo. El nombre base del archivo debe coincidir con el atributo name de su elemento raíz (protocol). Contiene una interfaz denominada «qt_example_extension». Este es el nombre que se difundirá desde el servidor y al que se conectará el cliente para enviar solicitudes y recibir eventos. Este nombre debe ser único, por lo que es recomendable utilizar un prefijo que lo distinga de las interfaces oficiales.

Una interfaz suele constar de dos tipos de llamadas a procedimientos remotos: solicitudes y eventos. Las «solicitudes» son llamadas que el cliente realiza en el lado del servidor, y los «eventos» son llamadas que el servidor realiza en el lado del cliente.

La extensión de ejemplo contiene un conjunto de solicitudes que indican al servidor que aplique determinadas transformaciones a la ventana del cliente. Por ejemplo, si el cliente envía una solicitud de «rebote», el servidor debería responder haciendo que la ventana rebote en la pantalla.

Del mismo modo, cuenta con un conjunto de eventos que el servidor puede utilizar para proporcionar instrucciones al cliente. Por ejemplo, el evento «set_font_size» es una instrucción para que el cliente establezca su tamaño de fuente predeterminado en un tamaño específico.

El protocolo define la existencia de solicitudes y eventos, así como los argumentos que admiten. Cuando se ejecuta « qtwaylandscanner » sobre él, genera el código necesario para organizar la llamada a la función y sus argumentos, y para transmitirlos a través de la conexión. En el otro extremo, esto se convierte en una llamada a una función virtual que puede implementarse para proporcionar la respuesta real.

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 lo mismo.)

La implementación del compositor

La propia aplicación Compositor se implementa utilizando QML y Qt Quick, pero la extensión está implementada en C++.

El primer paso consiste en crear una subclase del código de enlace generado por qtwaylandscanner para poder acceder a su funcionalidad. Añadimos la macro QML_ELEMENT a la clase para que sea accesible desde QML.

class CustomExtension  : public QWaylandCompositorExtensionTemplate<CustomExtension>
        , public QtWaylandServer::qt_example_extension
{
    Q_OBJECT
    QML_ELEMENT

Además de heredar de la clase generada, también heredamos de la clase QWaylandCompositorExtensionTemplate, que ofrece algunas ventajas adicionales a la hora de trabajar con extensiones, utilizando el patrón de plantillas curiosamente recurrentes.

Ten en cuenta que QWaylandCompositorExtensionTemplate debe ser la primera en la lista de herencia, ya que es una clase basada en QObject.

La subclase contiene reimplementaciones de las funciones virtuales de la clase base generada, donde podemos gestionar las solicitudes enviadas por un cliente.

protected:
    void example_extension_bounce(Resource *resource, wl_resource *surface, uint32_t duration) override;

En estas reimplementaciones, simplemente traducimos la solicitud a una emisión de señal, de modo que podamos gestionarla en el código QML real del compositor.

void CustomExtension::example_extension_bounce(QtWaylandServer::qt_example_extension::Resource *resource, wl_resource *wl_surface, uint32_t duration)
{
    Q_UNUSED(resource);
    auto surface = QWaylandSurface::fromResource(wl_surface);
    qDebug() << "server received bounce" << surface << duration;
   emit bounce(superficie, duración);
}

Además, la subclase define ranuras para cada uno de los eventos, de modo que estas puedan llamarse desde QML o conectarse a señales. Las ranuras simplemente llaman a las funciones generadas que envían los eventos al cliente.

void CustomExtension::setFontSize(QWaylandSurface*superficie, uint pixelSize)
{
    if (surface) {
        Resource *target = resourceMap().value(surface->waylandClient());
        if (target) {
            qDebug() << "Server-side extension sending setFontSize:" << pixelSize;
            send_set_font_size(target->handle, surface->resource(), pixelSize);
        }
    }
}

Dado que hemos añadido la macro QML_ELEMENT a la definición de la clase (y hemos añadido los pasos de compilación correspondientes a los archivos del sistema de compilación), se puede instanciar en QML.

La convertimos en un elemento hijo directo del objeto ` WaylandCompositor ` para que el compositor la registre como una extensión.

    CustomExtension {
        id: custom

        onSurfaceAdded: (surface) => {
            const item = comp.itemForSurface(surface)
            item.isCustom = true
        }

        onBounce: (surface, ms) => {
            const item = comp.itemForSurface(surface)
            item.doBounce(ms)
        }

        onSpin: (surface, ms) => {
            const item = comp.itemForSurface(surface)
            item.doSpin(ms)
        }

        onCustomObjectCreated: (obj) => {
            const item = customObjectComponent.createObject(output.surfaceArea, { "obj": obj } )
        }
    }

    function setDecorations(shown) {
        for (const elem of itemList) {
            if (elem.isCustom)
                custom.showDecorations(elem.surface.client, shown)
        }
    }

El objeto cuenta con controladores de señales para las solicitudes que pueda recibir del cliente y reacciona ante ellas en consecuencia. Además, podemos llamar a sus ranuras para enviar eventos.

            onFontSizeChanged: {
                custom.setFontSize(surface, fontSize)
            }

La implementación del cliente en C++

Ambos clientes comparten la implementación en C++ de la interfaz. Al igual que en el compositor, creamos una subclase del código generado que también hereda de una clase de plantilla. En este caso, heredamos de QWaylandClientExtensionTemplate.

class CustomExtension : public QWaylandClientExtensionTemplate<CustomExtension>
        , public QtWayland::qt_example_extension

El enfoque es muy similar al del compositor, salvo que está invertido: las solicitudes se implementan como ranuras que llaman a las funciones generadas, y los eventos como funciones virtuales que reimplementamos para emitir señales.

void CustomExtension::sendBounce(QWindow *window, uint ms)
{
    QtWayland::qt_example_extension::bounce(getWlSurface(window), ms);
}

El código del cliente en sí es muy sencillo y solo pretende mostrar cómo activar el comportamiento. En un evento de dibujo personalizado, dibuja un conjunto de rectángulos y etiquetas. Cuando se hace clic en cualquiera de ellos, envía solicitudes al servidor.

    void mousePressEvent(QMouseEvent *ev) override
    {
        if (rect1.contains(ev->position()))
            doSpin();
        else if (rect2.contains(ev->position()))
            doBounce();
        else if (rect3.contains(ev->position()))
            newWindow();
        else if (rect4.contains(ev->position()))
            newObject();
    }

Para actualizar el tamaño de la fuente al recibir el evento « set_font_size », la señal de nuestra clase de extensión se conecta a una ranura.

        connect(m_extension, &CustomExtension::fontSize, this, &TestWindow::handleSetFontSize);

El slot actualizará el tamaño de la fuente y volverá a dibujar la ventana.

La implementación del cliente QML

El cliente QML es similar al cliente C++. Se basa en la misma implementación de la extensión personalizada que el cliente C++ y la instancia en QML para habilitarla.

    CustomExtension {
        id: customExtension
        onActiveChanged: {
            registerWindow(topLevelWindow)
        }
        onFontSize: (window, pixelSize) => {
            topLevelWindow.fontSize = pixelSize
        }
    }

La interfaz de usuario consta de varios rectángulos en los que se puede hacer clic y utiliza TapHandler para enviar las solicitudes correspondientes cuando se hace clic en un rectángulo.

            TapHandler {
                onTapped: {
                    if (customExtension.active)
                        customExtension.sendBounce(topLevelWindow, 1000)
                }
            }

Para simplificar, el ejemplo se ha limitado a mostrar únicamente las solicitudes bounce y spin, así como el evento set_font_size. La incorporación de las funciones adicionales se deja como ejercicio para el lector.

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.