<qqml.h> - Functions to register C++ types to QML

Header: #include <qqml.h>

Tipos

enum QQmlModuleImportSpecialVersions { QQmlModuleImportModuleAny, QQmlModuleImportLatest, QQmlModuleImportAuto }

Funciones

QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)
void qmlClearTypeRegistrations()
QObject *qmlExtendedObject(QObject *base)
bool qmlProtectModule(const char *uri, int majVersion)
int qmlRegisterAnonymousType(const char *uri, int versionMajor)
int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)
void qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback)
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
void qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

Macros

Descripción detallada

Esta cabecera proporciona una colección de funciones que permiten el registro de tipos C++ en QML.

Véase también Visión general - Integración de QML y C++, qqmlintegration.h, y qmltyperegistrar.

Documentación de tipos

enum QQmlModuleImportSpecialVersions

Define algunos valores especiales que pueden pasarse a los argumentos de versión de qmlRegisterModuleImport() y qmlUnregisterModuleImport().

ConstanteValorDescripción
QQmlModuleImportModuleAny-1Cuando se pasa como majorVersion del módulo base, significa que la importación debe aplicarse a cualquier versión del módulo.
QQmlModuleImportLatest-1Cuando se pasa como major o minor version del módulo importado, significa que se importará la última versión mayor, o la última versión menor de una versión mayor especificada.
QQmlModuleImportAuto-2Cuando se pasa como versión mayor del módulo importado, significa que se reenviará la versión del módulo base.

Documentación de funciones

template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)

La forma de esta función de plantilla es:

template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)

Devuelve la instancia de objeto adjunta que ha sido adjuntada al attachee especificado por el tipo de adjunto T.

Si attachee es nullptr, devuelve nullptr.

Si existe una instancia de objeto adjunto de tipo T, la devolverá. En caso contrario, devolverá una instancia recién creada si createIfMissing es true y T es un tipo de adjunto válido, o nullptr si no lo es.

Véase también QML_ATTACHED() y Proporcionar propiedades adjuntas.

void qmlClearTypeRegistrations()

Borra todos los registros de tipos almacenados, como los producidos con qmlRegisterType().

No llame a esta función mientras exista un QQmlEngine o el comportamiento será indefinido. Cualquier QQmlEngines existente debe ser borrado antes de llamar a esta función. Esta función sólo afecta a la caché global de la aplicación. Borre el QQmlEngine para borrar todos los datos en caché relacionados con ese motor.

QObject *qmlExtendedObject(QObject *base)

Esta función devuelve el objeto de extensión que pertenece a base, si existe. En caso contrario, devuelve nullptr.

Véase también QML_EXTENDED.

bool qmlProtectModule(const char *uri, int majVersion)

Esta función protege un módulo de modificaciones posteriores. Puede usarse para evitar que otros plugins inyecten tipos en tu módulo. También puede suponer una mejora del rendimiento, ya que permite al motor omitir la comprobación de la posibilidad de nuevos tipos o plugins cuando se alcanza esta importación.

Una vez que se ha llamado a qmlProtectModule, un motor QML ya no buscará un nuevo archivo qmldir para cargar el módulo. No obstante, reutilizará los archivos qmldir que haya cargado anteriormente. Por lo tanto, los tipos presentes en este punto seguirán funcionando. Tenga en cuenta que diferentes motores QML pueden cargar diferentes módulos. Sin embargo, la protección del módulo es global y afecta a todos los motores. La sobrecarga de localizar archivos qmldir y cargar plugins puede ser notable con sistemas de archivos lentos. Por lo tanto, proteger un módulo una vez que esté seguro de que no necesitará cargarlo más puede ser una buena optimización. Tenga en cuenta también que el bloqueo del módulo no sólo afecta a los plugins, sino también a cualquier otra directiva qmldir, como import o prefer, así como a cualquier tipo compuesto o script declarado en un archivo qmldir.

Además, después de llamar a esta función, cualquier intento de registrar tipos C++ en esta combinación de uri, versión principal provocará un error en tiempo de ejecución.

Devuelve true si el módulo con uri como identificador de módulo y majVersion como número de versión mayor fue encontrado y bloqueado, en caso contrario devuelve false. El módulo debe contener tipos exportados para ser encontrado.

template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)

Esta función de plantilla registra el tipo C++ en el sistema QML como un tipo anónimo. El tipo QML resultante no tiene nombre. Por lo tanto, no se pueden crear instancias de este tipo desde el sistema QML. Sin embargo, se puede acceder a instancias del tipo cuando se exponen como propiedades de otros tipos.

Utilice esta función cuando no se vaya a hacer referencia al tipo por su nombre, en concreto para los tipos C++ que se utilizan en la parte izquierda de un enlace de propiedades. Para indicar a qué módulo pertenece el tipo utilice uri y versionMajor.

Por ejemplo, considere las dos clases siguientes:

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

public:
    Bar() {}

    QString baz() const { return mBaz; }

    void setBaz(const QString &baz)
    {
        if (baz == mBaz)
            return;

        mBaz = baz;
        emit bazChanged();
    }

signals:
    void bazChanged();

private:
    QString mBaz;
};

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

public:
    Foo() {}

    Bar *bar() { return &mBar; }

private:
    Bar mBar;
};

En QML, asignamos una cadena a la propiedad baz de bar:

Foo {
    bar.baz: "abc"
    Component.onCompleted: print(bar.baz)
}

Para que el motor QML sepa que el tipo Bar tiene una propiedad baz, tenemos que dar a conocer Bar:

qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterAnonymousType<Bar>("App", 1);

Como el tipo Foo es instanciado en QML, debe ser registrado con la versión de qmlRegisterType() que toma un nombre de elemento.

Devuelve el id del tipo QML.

Véase también QML_ANONYMOUS y Elección del método de integración correcto entre C++ y QML.

template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Esta función de plantilla registra el tipo C++ y su objeto de extensión en el sistema QML con el nombre qmlName en la biblioteca importada de uri con número de versión compuesto de versionMajor y versionMinor. Las propiedades no disponibles en el tipo principal se buscarán en el objeto de extensión.

Devuelve el id del tipo QML.

Véase también QML_EXTENDED(), qmlRegisterType(), y Registro de objetos de extensión.

template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

Esta función de plantilla registra el tipo C++ y su extensión en el sistema QML con el nombre qmlName en la biblioteca importada de uri con número de versión compuesto de versionMajor y versionMinor.

Mientras el tipo tenga un nombre y un tipo, no podrá ser creado. Se imprime un mensaje de error con el reason dado si el usuario intenta crear una instancia de este tipo.

Esto es útil cuando el tipo sólo está destinado a proporcionar propiedades adjuntas, valores enum o una clase base abstracta con su extensión.

Devuelve el id del tipo QML.

Véase también QML_EXTENDED(), QML_UNCREATABLE(), y qmlRegisterUncreatableType().

void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

Esta función registra un módulo en un determinado uri con una versión especificada en versionMajor y versionMinor.

Esto se puede utilizar para hacer que una determinada versión del módulo esté disponible, incluso si no hay tipos registrados para esa versión. Esto es particularmente útil para mantener sincronizadas las versiones de módulos relacionados.

void qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

Registra un qmldir-import para el módulo uri de la versión mayor moduleMajor.

Esto tiene el mismo efecto que una declaración import en un archivo qmldir: Siempre que se importa uri de la versión moduleMajor, import de la versión importMajor. importMinor también se importa automáticamente. Si importMajor es QQmlModuleImportLatest se importa la última versión disponible de ese módulo, y importMinor no importa. Si importMinor es QQmlModuleImportLatest se elige la última versión menor de importMajor. Si importMajor es QQmlModuleImportAuto se importa la versión de import es la versión de uri, y importMinor no importa. Si moduleMajor es QQmlModuleImportModuleAny la importación del módulo se aplica para cualquier versión mayor de uri. Por ejemplo, puede especificar que siempre que se importe cualquier versión de MiMódulo, se importe la última versión de MiOtroMódulo. Entonces, la siguiente llamada sería apropiada:

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportLatest);

O bien, puede especificar que siempre que se importe la versión mayor 5 de "MiMódulo", se importe la versión 3.14 de "MiOtroMódulo":

qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);

Por último, si desea que siempre que se importe "MiOtroMódulo" se importe la misma versión de "MiOtroMódulo", especifique lo siguiente:

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportAuto);

Véase también qmlUnregisterModuleImport().

template <typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

Esta función de plantilla registra la revisión especificada de un tipo C++ en el sistema QML con la biblioteca importada de uri que tiene el número de versión compuesto de versionMajor y versionMinor.

Devuelve el id del tipo QML.

template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

Esta función se utiliza normalmente para registrar la revisión de una clase base que se utilizará para la versión especificada del tipo (consulte Revisiones y versiones de tipos).

int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)

Esta función se utiliza para registrar un objeto singleton cppObject, con un particular uri y typeName. Su versión es una combinación de versionMajor y versionMinor.

La instalación de un tipo singleton en un URI permite proporcionar funcionalidad arbitraria (métodos y propiedades) al código QML sin necesidad de que el cliente instancie instancias individuales del tipo.

Utilice esta función para registrar un objeto del tipo T dado como tipo singleton.

Un tipo singleton de QObject puede referenciarse mediante el nombre de tipo con el que se registró; a su vez, este nombre de tipo puede utilizarse como destino en un tipo Connections, o como cualquier otro identificador de tipo. Sin embargo, hay una excepción: una propiedad de tipo singleton QObject no se puede aliasear porque el nombre de tipo singleton no identifica un objeto dentro del mismo componente que cualquier otro elemento.

Nota: cppObject debe sobrevivir al motor QML en el que se utilice. Además, cppObject debe tener la misma afinidad de subprocesos que el motor. Si desea instancias singleton separadas para varios motores, debe utilizar qmlRegisterSingletonType. Ver Threads y QObjects para más información sobre seguridad de hilos.

NOTA: qmlRegisterSingleton sólo puede utilizarse cuando todos los tipos de ese módulo están registrados procedimentalmente.

Uso:

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE int doSomething()
    {
        setSomeProperty(5);
        return m_someProperty;
    }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) {
        if (m_someProperty != val) {
            m_someProperty = val;
            emit somePropertyChanged(val);
        }
    }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty = 0;
};
// Second, create an instance of the object

// allocate example before the engine to ensure that it outlives it
QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
QQmlEngine engine;

// Third, register the singleton type provider with QML by calling this
// function in an initialization function.
qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());

Para utilizar el tipo singleton registrado en QML, debe importar el URI con la versión correspondiente.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        console.log(MyApi.doSomething())
    }
}

Véase también QML_SINGLETON y qmlRegisterSingletonType.

int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Esta función puede utilizarse para registrar un tipo singleton con el nombre qmlName, en la biblioteca importada de uri que tenga el número de versión compuesto de versionMajor y versionMinor. El tipo se define en el archivo QML ubicado en url. La url debe ser una URL absoluta, es decir, url.isRelative() == false.

Además, el archivo QML del tipo debe contener la sentencia pragma Singleton entre sus sentencias import.

Se puede hacer referencia a un tipo singleton a través del nombre de tipo con el que se registró, y este nombre de tipo se puede utilizar como destino en un tipo Connections o utilizarse de otro modo como lo haría cualquier otro id de tipo. Una excepción a esto es que una propiedad de tipo singleton no puede tener alias (porque el nombre de tipo singleton no identifica un objeto dentro del mismo componente que cualquier otro elemento).

Utilización:

// First, define your QML singleton type which provides the functionality.
pragma Singleton
import QtQuick 2.0
Item {
    property int testProp1: 125
}
// Second, register the QML singleton type by calling this function in an initialization function.
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");

Para utilizar el tipo singleton registrado en QML, debe importar el tipo singleton.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: RegisteredSingleton.testProp1
}

También es posible registrar tipos QML singleton sin utilizar la función qmlRegisterSingletonType. Esto puede hacerse añadiendo una declaración pragma Singleton entre las importaciones del archivo QML del tipo. Además, el tipo debe definirse en un archivo qmldir con una palabra clave singleton y el qmldir debe ser importado por los archivos QML que utilicen el singleton.

Véase también QML_SINGLETON.

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback)

Esta función se puede utilizar para registrar un proveedor de tipo singleton callback en un determinado uri y typeName con una versión especificada en versionMajor y versionMinor.

Instalar un tipo singleton permite a los desarrolladores proporcionar funcionalidad arbitraria (métodos y propiedades) a un cliente sin requerir que instancias individuales del tipo sean instanciadas por el cliente.

Un tipo singleton puede ser un QObject o un QJSValue. Esta función debe utilizarse para registrar una función de proveedor de tipo singleton que devuelva un QJSValue como tipo singleton.

NOTA: Las propiedades de tipo singleton de QJSValue no provocarán la reevaluación del enlace si se modifican.

Utilización:

// First, define the singleton type provider function (callback).
static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
}

// Second, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);

Como alternativa, puede utilizar una lambda C++11:

qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
});

Para utilizar el tipo singleton registrado en QML, debe importar el tipo singleton.

import QtQuick 2.0
import Qt.example.qjsvalueApi 1.0 as ExampleApi
Item {
    id: root
    property int someValue: ExampleApi.MyApi.someProperty
}

Véase también QML_SINGLETON y Elección del método de integración correcto entre C++ y QML.

template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)

Esta función se puede utilizar para registrar un proveedor de tipo singleton callback en un determinado uri y typeName con una versión especificada en versionMajor y versionMinor.

Instalar un tipo singleton en una uri permite a los desarrolladores proporcionar funcionalidad arbitraria (métodos y propiedades) a los clientes sin requerir que instancias individuales del tipo sean instanciadas por el cliente.

Un tipo singleton puede ser un QObject o un QJSValue. Esta función debe utilizarse para registrar una función de proveedor de tipo singleton que devuelva un QObject del tipo dado T como tipo singleton.

Un tipo singleton QObject puede ser referenciado a través del nombre de tipo con el que fue registrado, y este nombre de tipo puede ser utilizado como destino en un tipo Connections o de otro modo utilizado como lo haría cualquier otro id de tipo. Una excepción a esto es que una propiedad de tipo singleton QObject no puede ser aliased.

NOTA: Una instancia de tipo singleton QObject devuelta por un proveedor de tipos singleton es propiedad del motor QML a menos que el objeto tenga establecido explícitamente el indicador QQmlEngine::CppOwnership.

Utilización:

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    SingletonTypeExample(QObject *parent = nullptr)
        : QObject(parent), m_someProperty(0)
    {
    }

    ~SingletonTypeExample() {}

    Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty;
};

// Second, define the singleton type provider function (callback).
static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
}

// Third, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);

Como alternativa, puede utilizar una lambda C++11:

qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
});

Para utilizar el tipo singleton registrado en QML, debe importar el tipo singleton.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        someValue = MyApi.doSomething()
    }
}

Véase también QML_SINGLETON y Elección del método de integración correcto entre C++ y QML.

template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Esta función de plantilla registra el tipo C++ en el sistema QML con el nombre qmlName, en la biblioteca importada de uri teniendo el número de versión compuesto de versionMajor y versionMinor.

Devuelve el id del tipo QML.

Existen dos formas de esta función de plantilla:

template<typename T>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

La primera es la forma estándar que registra el tipo T como un nuevo tipo. La segunda permite registrar una revisión concreta de una clase en una versión especificada (véase Revisiones y versiones de tipos).

Por ejemplo, esto registra una clase C++ MySliderItem como un tipo QML llamado Slider para la versión 1.0 de un espacio de nombres de tipos llamado "com.mycompany.qmlcomponents":

qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

Una vez registrado, el tipo puede utilizarse en QML importando el espacio de nombres de tipos y el número de versión especificados:

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

Nótese que es perfectamente razonable que una librería registre tipos a versiones anteriores a la versión real de la librería. De hecho, es normal que la nueva biblioteca permita que QML escrito con versiones anteriores siga funcionando, aunque existan versiones más avanzadas de algunos de sus tipos.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT(), y Elección del método de integración correcto entre C++ y QML.

int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Esta función registra un tipo en el sistema QML con el nombre qmlName, en la biblioteca importada de uri que tiene el número de versión compuesto de versionMajor y versionMinor. El tipo se define en el archivo QML ubicado en url. La url debe ser una URL absoluta, es decir, url.isRelative() == false.

Normalmente, los archivos QML pueden cargarse como tipos directamente desde otros archivos QML, o utilizando un archivo qmldir. Esta función permite el registro de archivos a tipos desde código C++, como cuando el mapeo de tipos necesita ser determinado procedimentalmente al inicio.

Devuelve -1 si el registro no se ha realizado correctamente.

int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

Esta función registra un tipo en el sistema QML con el nombre qmlName, en el espacio de nombres de tipos importado de uri teniendo el número de versión compuesto de versionMajor y versionMinor, pero cualquier intento de instanciar el tipo producirá el error dado message.

Normalmente, los tipos exportados por un plugin 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.

Devuelve el id del tipo QML.

Ejemplo:

#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif

Esto hará que cualquier QML que importe el espacio de nombres de tipo "MinehuntCore" e intente utilizar el tipo produzca un mensaje de error:

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

Sin esto, se daría un mensaje genérico "Game is not a type".

Ver también QML_UNAVAILABLE, qmlRegisterUncreatableType(), y Elegir el método de integración correcto entre C++ y QML.

int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

Esta función registra el staticMetaObject y su extensión en el sistema QML con el nombre qmlName en la biblioteca importada de uri con número de versión compuesto de versionMajor y versionMinor.

No se puede crear una instancia del metaobjeto. Se imprime un mensaje de error con el reason dado si el usuario intenta crearlo.

Esta función es útil para registrar espacios de nombres Q_NAMESPACE.

Devuelve el id de tipo QML.

Por ejemplo:

namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

En el lado QML, ahora puede utilizar los enums registrados:

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

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

template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

Esta función de plantilla registra el tipo C++ en el sistema QML con el nombre qmlName, en la biblioteca importada de uri teniendo el número de versión compuesto de versionMajor y versionMinor.

Aunque el tipo tiene un nombre y un tipo, no puede ser creado, y el error dado message resultará si se intenta la creación.

Esto es útil cuando el tipo sólo está destinado a proporcionar propiedades adjuntas o valores enum.

Devuelve el id del tipo QML.

Véase también QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), y Elección del método de integración correcto entre C++ y QML.

int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Devuelve el id de tipo QML de un tipo que se registró con el nombre qmlName en un uri concreto y una versión especificada en versionMajor y versionMinor.

Esta función devuelve el mismo valor que las funciones de registro de tipos QML como qmlRegisterType() y qmlRegisterSingletonType().

Si qmlName, uri y versionMajor coinciden con un tipo registrado, pero la versión menor especificada en versionMinor es mayor, entonces se devuelve el id del tipo con la versión menor más cercana.

Devuelve -1 si no se ha encontrado ningún tipo coincidente o uno de los parámetros dados no es válido.

Nota : : qmlTypeId intenta que los módulos estén disponibles, incluso si ningún motor ha accedido a ellos todavía. Esto puede introducir sobrecarga la primera vez que se accede a un módulo. Intentar encontrar tipos de un módulo que no existe siempre introduce esta sobrecarga.

Véase también QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), y qmlRegisterSingletonType().

void qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

Elimina una importación de módulo previamente registrada con qmlRegisterModuleImport()

Llamando a esta función se asegura de que import de la versión importMajor.importMinor no se importa automáticamente más cuando uri de la versión moduleMajor es. La resolución de versiones funciona igual que con qmlRegisterModuleImport().

Véase también qmlRegisterModuleImport().

Documentación de macros

QML_DECLARE_TYPE()

Equivalente a Q_DECLARE_METATYPE(TYPE *) y Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)

QML_DECLARE_TYPEINFO(Type, Flags)

Declara propiedades adicionales del Type dado según lo descrito por el Flags especificado.

Actualmente, la única información de tipo admitida es QML_HAS_ATTACHED_PROPERTIES, que declara que Type admite propiedades adjuntas. QML_DECLARE_TYPEINFO() no es necesaria si Type contiene la macro QML_ATTACHED.

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