En esta página

Cómo escribir extensiones de QML con C++

El Qt Qml módulo proporciona un conjunto de API para ampliar QML mediante extensiones en C++. Puedes crear extensiones para añadir tus propios tipos Qml, ampliar tipos Qt existentes o llamar a funciones C/C++ a las que no se puede acceder desde el código Qml habitual.

Este tutorial muestra cómo escribir una extensión de QML utilizando C++ que incluya características básicas de QML, como propiedades, señales y enlaces. También muestra cómo se pueden implementar las extensiones a través de complementos.

Muchos de los temas tratados en este tutorial se documentan con mayor detalle en «Descripción general: integración de QML y C++» y en sus subtemas de documentación. En particular, puede que te interesen los subtemas «Exponer atributos de clases de C++ a QML » y «Definir tipos de QML desde C++».

Cómo abrir los códigos fuente del tutorial

El código de este tutorial está disponible como parte de los fuentes de Qt. Si has instalado Qt con la opción « Qt Online Installer », encontrarás los fuentes en el directorio de instalación de Qt, en la ruta Examples/Qt-6.12.0/qml/tutorials/extending-qml/.

Creación de un proyecto desde cero

Como alternativa, puedes seguir el tutorial creando el código fuente desde cero: para cada capítulo, crea un nuevo proyecto utilizando la plantilla de aplicación «Qt Quick »:

A continuación, sigue los pasos adaptando y ampliando el código esqueleto generado.

Capítulo 1: Creación de un nuevo tipo

extending-qml/chapter1-basics

Una tarea habitual al ampliar QML es proporcionar un nuevo tipo QML que admita alguna funcionalidad personalizada más allá de la que ofrecen los tipos integrados Qt Quick types. Por ejemplo, esto podría hacerse para implementar modelos de datos concretos, proporcionar tipos con capacidades personalizadas de pintura y dibujo, o acceder a características del sistema —como la programación de red— a las que no se puede acceder a través de las funciones integradas de QML.

En este tutorial, mostraremos cómo utilizar las clases de C++ del módulo Qt Quick para ampliar QML. El resultado final será una sencilla visualización de un gráfico circular implementada mediante varios tipos QML personalizados conectados entre sí a través de características de QML como enlaces y señales, y que se pondrán a disposición del QML Runtime mediante un complemento.

Para empezar, creemos un nuevo tipo de QML llamado «PieChart» que tenga dos propiedades: un nombre y un color. Lo pondremos a disposición en un espacio de nombres de tipos importable llamado «Charts», con la versión 1.0.

Queremos que este tipo PieChart se pueda utilizar desde QML de la siguiente manera:

import Charts

PieChart {
    width: 100; height: 100
    name: "A simple pie chart"
    color: "red"
}

Nota: Es posibleque tengas que habilitar « QML Language Server » y su resaltado semántico (en Qt Creator o en Qt Extension for Visual Studio Code) para que Qt Creator resalte PieChart correctamente.

Para ello, necesitamos una clase de C++ que encapsule este tipo PieChart y sus propiedades. Dado que QML hace un uso extensivo del sistema de metaoobjetos de Qt, esta nueva clase debe:

Declaración de la clase

Esta es nuestra clase ` PieChart `, definida en ` piechart.h`:

#include <QtQuick/QQuickPaintedItem>
#include <QColor>

class PieChart : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName FINAL)
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieChart(QQuickItem *parent = nullptr);

    QString name() const;
    void setName(const QString &name);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QString m_name;
    QColor m_color;
};

La clase hereda de ` QQuickPaintedItem ` porque queremos sobrescribir ` QQuickPaintedItem::paint()` para realizar operaciones de dibujo con la API ` QPainter `. Si la clase solo representara algún tipo de datos y no fuera un elemento que realmente tuviera que mostrarse, podría simplemente heredar de ` QObject`. O bien, si queremos ampliar la funcionalidad de una clase existente basada en ` QObject`, podría heredar de esa clase en su lugar. Por otra parte, si queremos crear un elemento visual que no necesite realizar operaciones de dibujo con la API QPainter, basta con crear una subclase de QQuickItem.

La clase « PieChart » define las dos propiedades « name » y « color » mediante la macro « Q_PROPERTY », y sobrescribe « QQuickPaintedItem::paint()». La clase « PieChart » se registra mediante la macro « QML_ELEMENT », para permitir su uso desde QML. Si no se registra la clase, « App.qml » no podrá crear un « PieChart ».

Configuración de qmake

Para que el registro surta efecto, se añade la opción « qmltypes » a « CONFIG » en el archivo del proyecto y se especifican « QML_IMPORT_NAME » y « QML_IMPORT_MAJOR_VERSION »:

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

Además, es necesario añadir manualmente un archivo qmldir para crear un módulo QML.

module Charts
typeinfo chapter1-basics.qmltypes
depends QtQuick
prefer :/qt/qml/Charts/
App 254.0 App.qml

Configuración de CMake

Para que el registro surta efecto al utilizar CMake, utiliza el comando ` qt_add_qml_module() `:

qt_add_qml_module(chapter1-basics
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)

La API qt_add_qml_module() genera automáticamente un archivo « qmldir » para el módulo QML.

Implementación de la clase

La implementación de la clase en piechart.cpp simplemente establece y devuelve los valores de m_name y m_color según corresponda, e implementa paint() para dibujar un sencillo gráfico circular:

PieChart::PieChart(QQuickItem *parent)
    : QQuickPaintedItem(parent)
{
}
...
void PieChart::paint(QPainter *painter)
{
    QPen pen(m_color, 2);
    painter->setPen(pen);
    painter->setRenderHints(QPainter::Antialiasing, true);
    painter->drawPie(boundingRect().adjusted(1, 1, -1, -1), 90 * 16, 290 * 16);
}

Uso en QML

Ahora que hemos definido el tipo ` PieChart `, lo utilizaremos desde QML. El archivo ` App.qml ` crea un elemento ` PieChart ` y muestra los detalles del gráfico circular utilizando un elemento estándar de QML ` Text `:

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: aPieChart
        anchors.centerIn: parent
        width: 100; height: 100
        name: "A simple pie chart"
        color: "red"
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: aPieChart.name
    }
}

Obsérvese que, aunque el color se especifica como una cadena en QML, se convierte automáticamente en un objeto QColor para la propiedad color del PieChart. Se proporcionan conversiones automáticas para otros muchos tipos de valores. Por ejemplo, una cadena como «640x480» puede convertirse automáticamente en un valor QSize.

También crearemos una aplicación en C++ que utilice un QQuickView para ejecutar y mostrar App.qml.

Aquí está la aplicación main.cpp:

#include "piechart.h"
#include <QtQuick/QQuickView>
#include <QGuiApplication>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.loadFromModule("Charts", "App");
    view.show();
    return QGuiApplication::exec();
}

Compilación del proyecto

Para compilar el proyecto, incluimos los archivos, vinculamos las bibliotecas y definimos un espacio de nombres de tipos llamado «Charts» con la versión 1.0 para cualquier tipo expuesto a QML.

Uso de qmake:

QT += qml quick

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

HEADERS += piechart.h
SOURCES += piechart.cpp \
           main.cpp

RESOURCES += chapter1-basics.qrc

DESTPATH = $$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter1-basics
target.path = $$DESTPATH
INSTALLS += target

Con CMake:

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

cmake_minimum_required(VERSION 3.16)
project(chapter1-basics LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)

qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(chapter1-basics
    main.cpp
    piechart.cpp piechart.h
)

set_target_properties(chapter1-basics PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

target_link_libraries(chapter1-basics PUBLIC
    Qt6::Core
    Qt6::Gui
    Qt6::Qml
    Qt6::Quick
)
qt_add_qml_module(chapter1-basics
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)
install(TARGETS chapter1-basics
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

qt_generate_deploy_qml_app_script(
    TARGET chapter1-basics
    OUTPUT_SCRIPT deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})

Ahora ya podemos compilar y ejecutar la aplicación:

La aplicación crea el gráfico circular con las propiedades definidas por el tipo de gráfico circular.

Nota: Es posible que aparezca una advertencia : «Expresión... depende de propiedades no enlazables: PieChart::name». Esto ocurre porque añadimos un enlace a la propiedad escribible name, pero aún no hemos definido una señal de notificación para ella. Por lo tanto, el motor de QML no puede actualizar el enlace si cambia el valor de name. Esto se aborda en los siguientes capítulos.

Capítulo 2: Conexión a métodos y señales de C++

extending-qml/chapter2-methods

Supongamos que queremos que ` PieChart ` tenga un método «clearChart()» que borre el gráfico y, a continuación, emita una señal «chartCleared». Nuestra clase ` App.qml ` podría llamar a ` clearChart() ` y recibir señales ` chartCleared() ` de la siguiente manera:

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: aPieChart
        anchors.centerIn: parent
        width: 100; height: 100
        color: "red"

        onChartCleared: console.log("The chart has been cleared")
    }

    MouseArea {
        anchors.fill: parent
        onClicked: aPieChart.clearChart()
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: "Click anywhere to clear the chart"
    }
}

El usuario puede hacer clic en cualquier lugar de la ventana de la aplicación para borrar el gráfico. Al hacerlo, se invoca el método «Clear Chart».

Para ello, añadimos un método « clearChart() » y una señal « chartCleared() » a nuestra clase de C++:

class PieChart : public QQuickPaintedItem
{
    ...
public:
    ...
    Q_INVOKABLE void clearChart();

signals:
    void chartCleared();
    ...
};

El uso de ` Q_INVOKABLE ` hace que el método ` clearChart() ` esté disponible para el sistema de metaoobjetos de Qt y, a su vez, para QML.

Nota: Tambiénpuedes declarar el método como una ranura (slot) de Qt en lugar de utilizar ` Q_INVOKABLE`, ya que las ranuras públicas y protegidas también se pueden invocar desde QML (no se pueden invocar las ranuras privadas).

El método ` clearChart() ` cambia el color a ` Qt::transparent`, vuelve a dibujar el gráfico y, a continuación, emite la señal ` chartCleared() `:

void PieChart::clearChart()
{
    setColor(QColor(Qt::transparent));
    update();

    emit chartCleared();
}

Ahora, cuando ejecutamos la aplicación y hacemos clic en la ventana, el gráfico circular desaparece y la aplicación muestra:

qml: The chart has been cleared

Capítulo 3: Añadir enlaces de propiedades

extending-qml/chapter3-bindings

El enlace de propiedades es una potente característica de QML que permite sincronizar automáticamente valores de diferentes tipos. Utiliza señales para notificar y actualizar los valores de otros tipos cuando se modifican los valores de las propiedades.

Hablemos de habilitar los enlaces de propiedades para la propiedad « color ». Esto significa que, si tenemos un código como este:

import Charts
import QtQuick

Item {
    width: 300; height: 200

    Row {
        anchors.centerIn: parent
        spacing: 20

        PieChart {
            id: chartA
            width: 100; height: 100
            color: "red"
        }

        PieChart {
            id: chartB
            width: 100; height: 100
            color: chartA.color
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: { chartA.color = "blue" }
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: "Click anywhere to change the chart color"
    }
}

La propiedad de color del gráfico circular B está vinculada a la propiedad de color del gráfico circular A.

La instrucción «color: chartA.color» vincula el valor de « color » de chartB con el de « color » de chartA. Cada vez que cambia el valor de « color » de chartA, el valor de « color » de chartB se actualiza con el mismo valor. Al hacer clic en la ventana, el controlador « onClicked » de MouseArea cambia el color de chartA, con lo que ambos gráficos pasan a ser de color azul.

Es fácil habilitar el enlace de propiedades para la propiedad color. Añadimos la función NOTIFY a su declaración Q_PROPERTY() para indicar que se emite una señal «colorChanged» cada vez que cambia el valor.

class PieChart : public QQuickPaintedItem
{
    ...
    Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged FINAL)
public:
    ...
signals:
    void colorChanged();
    ...
};

A continuación, emitimos esta señal en ` setColor()`:

void PieChart::setColor(const QColor &color)
{
    if (color != m_color) {
        m_color = color;
        update();   // repaint with the new color
        emit colorChanged();
    }
}

Es importante que « setColor() » compruebe que el valor del color haya cambiado realmente antes de emitir « colorChanged() ». Esto garantiza que la señal no se emita innecesariamente y también evita bucles cuando otros elementos respondan al cambio de valor.

El uso de enlaces es esencial en QML. Siempre debes añadir señales NOTIFY a las propiedades si es posible implementarlas, de modo que tus propiedades puedan utilizarse en enlaces. Las propiedades que no se pueden vincular no se actualizan automáticamente y no se pueden utilizar con la misma flexibilidad en QML. Además, dado que los enlaces se invocan con tanta frecuencia y son fundamentales en el uso de QML, los usuarios de tus tipos QML personalizados podrían observar un comportamiento inesperado si no se implementan dichos enlaces.

Capítulo 4: Uso de tipos de propiedad personalizados

extending-qml/chapter4-customPropertyTypes

El tipo ` PieChart ` cuenta actualmente con una propiedad de tipo cadena y otra de tipo color. Podría tener muchos otros tipos de propiedades. Por ejemplo, podría tener una propiedad de tipo entero para almacenar un identificador para cada gráfico:

// C++
class PieChart : public QQuickPaintedItem
{
    Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged)
    ...

public:
    void setChartId(int chartId);
    int chartId() const;
    ...

signals:
    void chartIdChanged();
};

// QML
PieChart {
    ...
    chartId: 100
}

Aparte de ` int`, podríamos utilizar otros tipos de propiedades. Muchos de los tipos de datos de Qt, como ` QColor`, ` QSize ` y ` QRect `, son compatibles automáticamente con QML. (Consulte la documentación «Conversión de tipos de datos entre QML y C++» para obtener una lista completa).

Si queremos crear una propiedad cuyo tipo no sea compatible de forma predeterminada con QML, debemos registrar el tipo en el motor de QML.

Por ejemplo, sustituyamos el uso de « property » por un tipo llamado «PieSlice» que tenga una propiedad « color ». En lugar de asignarle un color, le asignamos un valor « PieSlice », que a su vez contiene un « color »:

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: chart
        anchors.centerIn: parent
        width: 100; height: 100

        pieSlice: PieSlice {
            anchors.fill: parent
            color: "red"
        }
    }

    Component.onCompleted: console.log("The pie is colored " + chart.pieSlice.color)
}

Al igual que PieChart, este nuevo tipo PieSlice hereda de QQuickPaintedItem y declara sus propiedades mediante Q_PROPERTY():

class PieSlice : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieSlice(QQuickItem *parent = nullptr);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QColor m_color;
};

Para utilizarlo en PieChart, modificamos la declaración de la propiedad color y las firmas de los métodos asociados:

class PieChart : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY(PieSlice* pieSlice READ pieSlice WRITE setPieSlice FINAL)
    ...
public:
    ...
    PieSlice *pieSlice() const;
    void setPieSlice(PieSlice *pieSlice);
    ...
};

Hay un aspecto que hay que tener en cuenta al implementar setPieSlice(). El PieSlice es un elemento visual, por lo que debe establecerse como hijo de PieChart mediante QQuickItem::setParentItem(), de modo que PieChart sepa que debe dibujar este elemento hijo cuando se dibuje su contenido:

void PieChart::setPieSlice(PieSlice *pieSlice)
{
    m_pieSlice = pieSlice;
    pieSlice->setParentItem(this);
}

Al igual que el tipo PieChart, el tipo PieSlice debe exponerse a QML mediante QML_ELEMENT.

class PieSlice : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieSlice(QQuickItem *parent = nullptr);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QColor m_color;
};
    ...

Al igual que con PieChart, añadimos el espacio de nombres de tipo «Charts», versión 1.0, a nuestro archivo de compilación:

Usando qmake:

QT += qml quick

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

HEADERS += piechart.h \
           pieslice.h
SOURCES += piechart.cpp \
           pieslice.cpp \
           main.cpp

RESOURCES += chapter4-customPropertyTypes.qrc

DESTPATH = $$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter4-customPropertyTypes
target.path = $$DESTPATH
INSTALLS += target

Con CMake:

    ...
qt_add_executable(chapter4-customPropertyTypes
    main.cpp
    piechart.cpp piechart.h
    pieslice.cpp pieslice.h
)
qt_add_qml_module(chapter4-customPropertyTypes
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)
    ...

Capítulo 5: Uso de tipos de propiedad de lista

extending-qml/chapter5-listproperties

En este momento, un « PieChart » solo puede tener un « PieSlice ». Lo ideal sería que un gráfico tuviera varias porciones, con diferentes colores y tamaños. Para ello, podríamos tener una propiedad « slices » que aceptara una lista de elementos « PieSlice »:

pragma ComponentBehavior: Bound
import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: chart
        anchors.centerIn: parent
        width: 100; height: 100

        component Slice: PieSlice {
            parent: chart
            anchors.fill: parent
        }

        slices: [
            Slice {
                color: "red"
                fromAngle: 0
                angleSpan: 110
            },
            Slice {
                color: "black"
                fromAngle: 110
                angleSpan: 50
            },
            Slice {
                color: "blue"
                fromAngle: 160
                angleSpan: 100
            }
        ]
    }
}

La propiedad «slices» admite una lista de elementos de «pieslice». El elemento «pieslice» establece el ángulo y el color de cada porción del gráfico circular.

Para ello, sustituimos la propiedad « pieSlice » de « PieChart » por una propiedad « slices », declarada como tipo « QQmlListProperty ». La clase « QQmlListProperty » permite crear propiedades de lista en los tipos expuestos a QML. Sustituimos la función « pieSlice() » por una función « slices() » que devuelve una lista de porciones. También utilizamos un « QList » para almacenar la lista interna de porciones como « m_slices »:

class PieChart : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<PieSlice> slices READ slices FINAL)
    ...
public:
    ...
    QQmlListProperty<PieSlice> slices();

private:
    QString m_name;
    QList<PieSlice *> m_slices;
};

Aunque la propiedad slices no tiene una función WRITE asociada, sigue siendo modificable debido al funcionamiento de QQmlListProperty. En la implementación de PieChart, implementamos PieChart::slices() para que devuelva un valor de QQmlListProperty:

QQmlListProperty<PieSlice> PieChart::slices()
{
    return QQmlListProperty<PieSlice>(this, &m_slices);
}

Esto sintetiza las funciones necesarias para interactuar con la lista desde QML. La QQmlListProperty resultante es una vista de la lista. Como alternativa, puedes proporcionar manualmente las funciones de acceso individuales para la lista. Esto es necesario si tu lista no es un QList o si deseas restringir o personalizar de algún modo el acceso de QML a tu lista. Sin embargo, en la mayoría de los casos, el constructor que toma un puntero a QList es la opción más segura y sencilla.

La clase ` PieSlice ` también se ha modificado para incluir las propiedades ` fromAngle ` y ` angleSpan `, y para dibujar el segmento según estos valores. Se trata de una modificación sencilla si has leído las páginas anteriores de este tutorial, por lo que no se muestra el código aquí.

Capítulo 6: Creación de un complemento de extensión

extending-qml/chapter6-plugins

Actualmente, los tipos « PieChart » y « PieSlice » son utilizados por « App.qml », que se muestra mediante un « QQuickView » en una aplicación en C++. Una forma alternativa de utilizar nuestra extensión QML es crear una biblioteca de complementos para que esté disponible para el motor QML como un nuevo módulo de importación de QML. Esto permite que los tipos ` PieChart ` y ` PieSlice ` se registren en un espacio de nombres de tipos que pueda ser importado por cualquier aplicación QML, en lugar de restringir el uso de estos tipos a una sola aplicación.

Los pasos para crear un complemento se describen en «Creación de complementos C++ para QML». Para empezar, creamos una clase de complemento denominada ChartsPlugin. Esta clase es una subclase de QQmlEngineExtensionPlugin y utiliza la macro Q_PLUGIN_METADATA() para registrar el complemento en el sistema de metobjetos de Qt.

A continuación se muestra la definición de ` ChartsPlugin ` en ` chartsplugin.h`:

#include <QQmlEngineExtensionPlugin>

class ChartsPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
};

A continuación, configuramos el archivo de compilación para definir el proyecto como una biblioteca de complementos.

Con qmake:

TEMPLATE = lib
CONFIG += plugin qmltypes
QT += qml quick

QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

TARGET = $$qtLibraryTarget(chartsplugin)

HEADERS += piechart.h \
           pieslice.h \
           chartsplugin.h

SOURCES += piechart.cpp \
           pieslice.cpp

DESTPATH=$$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter6-plugins/$$QML_IMPORT_NAME

target.path=$$DESTPATH
qmldir.files=$$PWD/qmldir
qmldir.path=$$DESTPATH
INSTALLS += target qmldir

CONFIG += install_ok  # Do not cargo-cult this!

OTHER_FILES += qmldir

# Copy the qmldir file to the same folder as the plugin binary
cpqmldir.files = qmldir
cpqmldir.path = .
COPIES += cpqmldir

Con CMake:

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

qt6_policy(SET QTP0001 NEW)
qt6_add_qml_module(chartsplugin
    URI "Charts"
    PLUGIN_TARGET chartsplugin
    DEPENDENCIES QtQuick
)

target_sources(chartsplugin PRIVATE
    piechart.cpp piechart.h
    pieslice.cpp pieslice.h
)

target_link_libraries(chartsplugin PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Qml
    Qt6::Quick
)

install(TARGETS chartsplugin
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
    LIBRARY DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qmldir
    DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
)

Al compilar este ejemplo en Windows o Linux, el directorio ` Charts ` se ubicará en el mismo nivel que la aplicación que utiliza nuestro nuevo módulo de importación. De esta forma, el motor QML encontrará nuestro módulo, ya que la ruta de búsqueda predeterminada para las importaciones QML incluye el directorio del ejecutable de la aplicación. En macOS, el binario del complemento se copia en ` Contents/PlugIns ` dentro del paquete de la aplicación. Con qmake, esta ruta se establece en ` chapter6-plugins/app.pro`:

macos:!qtConfig(static) {
    charts.files = $$OUT_PWD/Charts
    charts.path = Contents/PlugIns
    QMAKE_BUNDLE_DATA += charts
}

Para tenerlo en cuenta, también debemos añadir esta ubicación como ruta de importación de QML en main.cpp:

    QQuickView view;
    ...

Definir rutas de importación personalizadas también resulta útil cuando hay varias aplicaciones que utilizan las mismas importaciones QML.

El archivo .pro también contiene una función adicional para garantizar que el archivo qmldir de definición del módulo se copie siempre en la misma ubicación que el binario del complemento.

El archivo qmldir declara el nombre del módulo y el complemento que este pone a disposición:

module Charts
optional plugin chartsplugin
typeinfo plugins.qmltypes
depends QtQuick
prefer :/qt/qml/Charts/

Ahora disponemos de un módulo QML que puede importarse a cualquier aplicación, siempre que el motor QML sepa dónde encontrarlo. El ejemplo contiene un ejecutable que carga App.qml, el cual utiliza la instrucción import Charts 1.0. Como alternativa, puedes cargar el archivo QML utilizando la herramienta qml, configurando la ruta de importación en el directorio actual para que encuentre el archivo qmldir:

qml -I . App.qml

El motor QML cargará el módulo «Charts», y los tipos que proporciona dicho módulo estarán disponibles para su uso en cualquier documento QML que lo importe.

Capítulo 7: Resumen

En este tutorial, hemos mostrado los pasos básicos para crear una extensión QML:

  • Definir nuevos tipos QML heredando de ` QObject ` y registrándolos con ` QML_ELEMENT ` o ` QML_NAMED_ELEMENT()`
  • Añadir métodos invocables utilizando Q_INVOKABLE o las ranuras (slots) de Qt, y conectarlos a las señales de Qt con la sintaxis onSignal
  • Añade enlaces de propiedades definiendo señales NOTIFY
  • Define tipos de propiedad personalizados si los tipos integrados no son suficientes
  • Define tipos de propiedad de lista utilizando QQmlListProperty
  • Crea una biblioteca de complementos definiendo un complemento de Qt y escribiendo un archivo `qmldir `

La documentación general sobre la integración de QML y C++ muestra otras características útiles que se pueden añadir a las extensiones de QML. Por ejemplo, podríamos utilizar propiedades por defecto para permitir añadir segmentos sin utilizar la propiedad ` slices `:

PieChart {
    PieSlice { ... }
    PieSlice { ... }
    PieSlice { ... }
}

O añadir y eliminar segmentos de forma aleatoria de vez en cuando utilizando fuentes de valores de propiedad:

PieChart {
    PieSliceRandomizer on slices {}
}

Nota: Para seguir aprendiendo sobre las extensiones QML y sus características, sigue el tutorial «Escritura de extensiones QML avanzadas con C++ ».

© 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.