<qqmlintegration.h>

Documentación de macros

QML_ADDED_IN_VERSION(MAJOR, MINOR)

Declara que el tipo o espacio de nombres que encierra fue añadido en la versión MAJOR.MINOR especificada. Se asume que la versión está en línea con cualquier revisión dada por las macros Q_REVISION() en métodos, ranuras o señales, y cualquier atributo REVISION() en propiedades declaradas con Q_PROPERTY().

QML_ADDED_IN_VERSION() sólo tiene efecto si el tipo o espacio de nombres está disponible en QML, por tener una macro QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, o QML_INTERFACE.

Si el módulo QML al que pertenece el tipo se importa con una versión inferior a la determinada de esta forma, el tipo QML es invisible.

Véase también QML_ELEMENT y QML_NAMED_ELEMENT.

QML_ANONYMOUS

Declara que el tipo adjunto está disponible, pero es anónimo en QML. El tipo no se puede crear ni utilizar para declarar propiedades en QML, pero cuando se pasa desde C++, se reconoce. En QML, puede utilizar propiedades de este tipo si están declaradas en C++.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), y QML_INTERFACE.

QML_ATTACHED(ATTACHED_TYPE)

Declara que el tipo envolvente adjunta ATTACHED_TYPE como propiedad adjunta a otros tipos. Esto tiene efecto si el tipo se expone a QML utilizando una macro QML_ELEMENT o QML_NAMED_ELEMENT().

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), y Proporcionar propiedades adjuntas.

[since 6.5] QML_CONSTRUCTIBLE_VALUE

Marca el tipo de valor circundante como construible. Es decir, cualquier constructor Q_INVOKABLE del tipo que tome exactamente un argumento puede utilizarse al asignar un valor JavaScript a una propiedad de este tipo.

Puede declarar un tipo de valor construible de la siguiente manera:

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_CONSTRUCTIBLE_VALUE
public:
    Q_INVOKABLE MyValueType(double d);

    // ...
};

Con el tipo anterior, el siguiente código QML producirá un valor MyValueType utilizando el constructor dado y lo asignará a la propiedad.

QtObject {
    property myValueType v: 5.4
}

También puedes construir listas de valores de esta forma:

QtObject {
    property list<myValueType> v: [5.4, 4.5, 3.3]
}

Desde Qt 6.8, si importa el módulo QML al que pertenece el tipo de valor en un espacio de nombres, puede utilizar el operador new de JavaScript para instanciarlo.

import MyModule as MM

QtObject {
    function process(d: real) {
        let v = new MM.myValueType(d);
        // v is a myValueType now
    }
}

Esta macro se introdujo en Qt 6.5.

Véase también QML_VALUE_TYPE.

QML_ELEMENT

Declara que el tipo o espacio de nombres que lo contiene está disponible en QML, utilizando su nombre de clase o espacio de nombres como nombre del elemento QML.

Por ejemplo, esto hace que la clase de C++ Slider esté disponible como un tipo QML denominado Slider. Se exponen todas sus propiedades, métodos invocables y enums.

class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
    // ...
public:
    enum Slippiness {
        Dry, Wet, Icy
    };
    Q_ENUM(Slippiness)

    Q_INVOKABLE void slide(Slippiness slippiness);

    // ...
}

Puede utilizar el sistema de compilación para registrar el tipo en el espacio de nombres de tipos com.mycompany.qmlcomponents con la versión principal 1. Para qmake, especifique lo siguiente en su archivo de proyecto:

CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1

Con CMake, pasa el URI y la versión a qt_add_qml_module

qt6_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)

Una vez registrado, el tipo puede utilizarse en QML importando el mismo namespace de tipo y número de versión:

import com.mycompany.qmlcomponents 1.0

Slider {
    value: 12
    Component.onCompleted: slide(Slider.Icy)

    // ...
}

También puede hacer que los espacios de nombres etiquetados con Q_NAMESPACE estén disponibles de esta forma, para exponer cualquier enum etiquetado con Q_ENUM_NS que contengan:

namespace MyNamespace {
  Q_NAMESPACE
  QML_ELEMENT

  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

En QML, puede utilizar los enums:

Component.onCompleted: console.log(MyNamespace.Key2)

NOTA: Cuando las clases tienen el mismo nombre pero se encuentran en diferentes espacios de nombres, el uso de QML_ELEMENT en ambos causará un conflicto. Asegúrese de utilizar QML_NAMED_ELEMENT() para una de ellas.

Consulte también Elección del método de integración correcto entre C++ y QML, QML_NAMED_ELEMENT(), Q_REVISION() y QML_ADDED_IN_VERSION().

QML_EXTENDED(EXTENDED_TYPE)

Declara que el tipo adjunto utiliza EXTENDED_TYPE como extensión para proporcionar más propiedades, métodos y enumeraciones en QML. Esto tiene efecto si el tipo se expone a QML utilizando una macro QML_ELEMENT o QML_NAMED_ELEMENT().

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE() y Registro de objetos de extensión.

QML_EXTENDED_NAMESPACE(EXTENSION_NAMESPACE)

Declara que el tipo adjunto utiliza EXTENSION_NAMESPACE como extensión para proporcionar más enumeraciones en QML. Esto tiene efecto si el tipo se expone a QML utilizando una macro QML_ELEMENT o QML_NAMED_ELEMENT(). Para que esto funcione, las enumeraciones deben estar expuestas al sistema de metaobjetos.

Por ejemplo, con el siguiente código C

namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}

podemos acceder a la enumeración en QML:

QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}

Véase también QML_NAMESPACE_EXTENDED(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(), Registro de objetos de extensión, Q_ENUM, y Q_ENUM_NS.

QML_EXTRA_VERSION(MAJOR, MINOR)

Declare que el tipo también debe estar disponible en la versión MAJOR.MINOR. Esto puede ser útil si un tipo debe estar disponible en varias versiones principales.

Los tipos se registran automáticamente para

• La versión principal en la que se introdujeron, véase QML_ADDED_IN_VERSION.
• Cualquier versión principal en la que se hayan introducido sus miembros.
• La versión principal actual de su módulo, a menos que se hayan registrado antes en QML_REMOVED_IN_VERSION.

En particular, no se registran automáticamente en ninguna PAST_MAJOR_VERSIONS entre las anteriores. Puede utilizar QML_EXTRA_VERSION para registrar manualmente sus tipos en versiones mayores posteriores.

Véase también QML_ELEMENT y QML_ADDED_IN_VERSION.

QML_FOREIGN(FOREIGN_TYPE)

Declara que las macros QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_EXTENDED(), QML_EXTENDED_NAMESPACE(), o QML_NAMESPACE_EXTENDED() del tipo C++ adjunto no se aplican al tipo adjunto, sino a FOREIGN_TYPE. El tipo adjunto aún debe registrarse en el sistema de metaobjetos mediante una macro Q_GADGET o Q_OBJECT.

Esto es útil para registrar tipos que no pueden modificarse para añadir las macros, por ejemplo porque pertenecen a bibliotecas de terceros. Para registrar un espacio de nombres, consulte QML_FOREIGN_NAMESPACE().

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), y QML_FOREIGN_NAMESPACE().

QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

Declara que las macros QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), o QML_REMOVED_IN_MINOR_VERSION() del espacio de nombres C++ adjunto no se aplican al tipo adjunto, sino a FOREIGN_NAMESPACE. El espacio de nombres adjunto aún debe registrarse en el meta sistema de objetos mediante una macro Q_NAMESPACE.

Esto es útil para registrar espacios de nombres que no pueden modificarse para añadir las macros, por ejemplo porque pertenecen a bibliotecas de terceros.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), y QML_FOREIGN().

QML_IMPLEMENTS_INTERFACES(interfaces)

Esta macro indica a Qt qué QML interfaces implementa la clase. Esta macro sólo debe usarse para interactuar con clases que usen QML_INTERFACE, use Q_INTERFACES en caso contrario. Es necesaria para que el registro declarativo a través de QML_ELEMENT funcione correctamente.

Ver también QML_INTERFACE y Q_INTERFACES.

QML_INTERFACE

Esta macro registra el tipo C++ adjunto en el sistema QML como una interfaz.

Los tipos registrados como interfaz en QML también deben declararse como interfaz en el sistema de metaobjetos. Por ejemplo:

struct FooInterface
{
    QML_INTERFACE
public:
    virtual ~FooInterface();
    virtual void doSomething() = 0;
};

Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

Cuando se registran en QML de esta forma, pueden utilizarse como tipos de propiedad:

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

Cuando se asigna una subclase QObject a esta propiedad, el motor QML realiza automáticamente la conversión de la interfaz a FooInterface*.

Los tipos de interfaz son implícitamente anónimos e increíbles en QML.

NOTA: Al heredar de tipos que utilicen QML_INTERFACE, utilice QML_IMPLEMENTS_INTERFACES en lugar de Q_INTERFACES.

Véase también QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), y QML_ANONYMOUS.

QML_NAMED_ELEMENT(name)

Declara que el tipo o espacio de nombres que lo contiene está disponible en QML, utilizando name como nombre del elemento. De lo contrario, se comporta igual que QML_ELEMENT.

class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};

Véase también Elegir el método de integración correcto entre C++ y QML y QML_ELEMENT.

QML_REMOVED_IN_VERSION(MAJOR, MINOR)

Declara que el tipo o espacio de nombres que lo encierra ha sido eliminado en la versión MAJOR.MINOR especificada. Esto es útil principalmente cuando se sustituye la implementación de un tipo QML. Si un QML_ADDED_IN_VERSION() correspondiente está presente en un tipo o espacio de nombres diferente del mismo nombre QML, entonces el tipo eliminado se utiliza cuando se importan versiones del módulo inferiores a MAJOR.MINOR, y el tipo añadido se utiliza cuando se importan versiones del módulo mayores o iguales a MAJOR.MINOR.

QML_REMOVED_IN_VERSION() sólo tiene efecto si el tipo o espacio de nombres está disponible en QML, por tener una macro QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, o QML_INTERFACE.

Véase también QML_ELEMENT y QML_NAMED_ELEMENT.

QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)

Esta macro declara el tipo adjunto o referenciado como un contenedor secuencial que gestiona una secuencia de elementos VALUE_TYPE. VALUE_TYPE puede ser un tipo de valor real o un puntero a un tipo de objeto. Rara vez podrá añadir esta macro a la declaración del contenedor real, ya que los contenedores suelen ser plantillas. Debería utilizar QML_FOREIGN para adjuntar el registro de tipo a una instanciación de plantilla. Usando esta técnica puedes, por ejemplo, declarar contenedores secuenciales como este:

class IntDequeRegistration
{
  Q_GADGET
  QML_FOREIGN(std::deque<int>)
  QML_ANONYMOUS
  QML_SEQUENTIAL_CONTAINER(int)
};

Después de esto, puede utilizar el contenedor como un array JavaScript en QML.

class Maze
{
  Q_OBJECT
  Q_ELEMENT
  // 0: North, 1: East, 2: South, 3: West
  Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
  [...]
}

Item {
  Maze {
    id: maze
  }

  function showSolution() {
      maze.solution.forEach([...])
  }
}

Véase también QML_ANONYMOUS y QML_FOREIGN().

QML_SINGLETON

Declara que el tipo adjunto es un singleton en QML. Esto sólo tiene efecto si el tipo es un Q_OBJECT y está disponible en QML (por tener una macro QML_ELEMENT o QML_NAMED_ELEMENT()). Por defecto, cada QQmlEngine intentará crear una instancia singleton utilizando el constructor predeterminado del tipo o una función de fábrica estática de la firma T *create(QQmlEngine *, QJSEngine *) cuando se accede al tipo por primera vez. Si ambos existen y son accesibles, se prefiere el constructor por defecto. Si no hay constructor por defecto ni función de fábrica, el singleton es inaccesible. El motor QML generalmente asume la propiedad del singleton y lo borrará cuando el propio motor se destruya. Puede evitarlo llamando a QJSEngine::setObjectOwnership() en el singleton.

Para declarar una clase construible por defecto como singleton, basta con añadir QML_SINGLETON:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};

Si la clase singleton no es construible por defecto, pero puedes modificarla, puedes añadirle una función de fábrica para hacerla accesible:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};

Si no puedes modificar la clase y no tiene un constructor por defecto o una función de fábrica adecuada, puedes proporcionar una envoltura QML_FOREIGN para definir la función de fábrica:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};

Por último, si quieres proporcionar un objeto singleton específico, cuya creación no puedes controlar, puedes devolverlo desde una función de fábrica. Esto sustituye a la función qmlRegisterSingletonInstance. Si llamara a

qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);

siendo miObjeto del tipo MySingleton *, puedes hacer lo siguiente en su lugar:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    // Initialize this using myObject where you would previously
    // call qmlRegisterSingletonInstance().
    inline static MySingleton *s_singletonInstance = nullptr;

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        // The instance has to exist before it is used. We cannot replace it.
        Q_ASSERT(s_singletonInstance);

        // The engine has to have the same thread affinity as the singleton.
        Q_ASSERT(engine->thread() == s_singletonInstance->thread());

        // There can only be one engine accessing the singleton.
        if (s_engine)
            Q_ASSERT(engine == s_engine);
        else
            s_engine = engine;

        // Explicitly specify C++ ownership so that the engine doesn't delete
        // the instance.
        QJSEngine::setObjectOwnership(s_singletonInstance,
                                      QJSEngine::CppOwnership);
        return s_singletonInstance;
    }

private:
    inline static QJSEngine *s_engine = nullptr;
};

De esta forma, la clase preexistente MySingleton se declara como un singleton QML, llamado MySingleton. Puede especificar una instancia para ella en cualquier momento antes de que se utilice configurando el miembro s_singletonInstance. Nada de esto requiere la modificación del propio MySingleton.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), y Singletons in QML.

[since 6.5] QML_STRUCTURED_VALUE

Marca el tipo de valor circundante como estructurado. Los tipos de valor estructurados pueden y serán preferiblemente construidos propiedad por propiedad a partir de un objeto JavaScript. Un tipo de valor estructurado, sin embargo, es siempre QML_CONSTRUCTIBLE_VALUE, también. Esto significa que aún puede proporcionar constructores Q_INVOKABLE para manejar la construcción desde tipos primitivos.

Puedes declarar un tipo de valor estructurado de la siguiente manera:

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_STRUCTURED_VALUE
    Q_PROPERTY(double d READ d WRITE setD)
    Q_PROPERTY(string e READ e WRITE setE)

    // ...
};

A continuación, puede rellenar una propiedad de este tipo de la siguiente manera:

QtObject {
    property myValueType v: ({d: 4.4, e: "a string"})
}

Los paréntesis adicionales son necesarios para desambiguar el objeto JavaScript de lo que podría interpretarse como un bloque de código JavaScript.

También puede construir listas de valores de esta manera:

QtObject {
    property list<myValueType> v: [
        {d: 4.4, e: "a string"},
        {d: 7.1, e: "another string"}
    ]
}

Esta macro se introdujo en Qt 6.5.

Véase también QML_VALUE_TYPE y QML_CONSTRUCTIBLE_VALUE.

QML_UNAVAILABLE

Esta macro declara que el tipo adjunto no está disponible en QML. Registra un tipo interno ficticio llamado QQmlTypeNotAvailable como tipo QML_FOREIGN(), utilizando cualquier otra macro QML que especifique.

Normalmente, los tipos exportados por un módulo deberían ser fijos. Sin embargo, si un tipo C++ no está disponible, debería al menos "reservar" el nombre del tipo QML, y dar al usuario del tipo no disponible un mensaje de error significativo.

Ejemplo:

#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif

Esto hará que cualquier QML que intente utilizar el tipo "Game" produzca un mensaje de error:

fun.qml: Get back to work, slacker!
   Game {
   ^

Utilizando esta técnica, sólo necesita una estructura Q_GADGET para personalizar el mensaje de error, no una QObject completa. Sin QML_UNCREATABLE(), QML_UNAVAILABLE aún produce un mensaje de error más específico que el habitual "is not a type" para tipos completamente desconocidos.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), y QML_FOREIGN().

QML_UNCREATABLE(reason)

Declara que el tipo adjunto no se puede crear desde QML. Esto tiene efecto si el tipo está disponible en QML, por tener una macro QML_ELEMENT o QML_NAMED_ELEMENT(). reason se emitirá como mensaje de error si se detecta un intento de crear el tipo desde QML.

Algunos tipos QML son implícitamente no creables, en particular los tipos expuestos con QML_ANONYMOUS o los espacios de nombres expuestos con QML_ELEMENT o QML_NAMED_ELEMENT().

Desde Qt 6.0 puedes usar "" en lugar de una razón para usar un mensaje estándar en su lugar.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), y QML_ANONYMOUS.

QML_VALUE_TYPE(name)

Declara el tipo o espacio de nombres que lo contiene para que esté disponible en QML, utilizando name como nombre. El tipo debe ser un tipo de valor y el nombre debe estar en minúsculas.

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)

    // ...
};

Véase también Elegir el método de integración correcto entre C++ y QML y QML_NAMED_ELEMENT.