<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
| QML_DECLARE_TYPE() | |
| QML_DECLARE_TYPEINFO(Type, Flags) |
Descripción detallada
Este encabezado proporciona un conjunto de funciones que permiten registrar tipos de C++ en QML.
Véase también «Descripción general: integración de QML y C++», « qqmlintegration.h » y «qmltyperegistrar».
Documentación de tipos
enum QQmlModuleImportSpecialVersions
Define algunos valores especiales que se pueden pasar a los argumentos de versión de las funciones ` qmlRegisterModuleImport()` y ` qmlUnregisterModuleImport()`.
| Constante | Valor | Descripción |
|---|---|---|
QQmlModuleImportModuleAny | -1 | Cuando se pasa como «majorVersion» del módulo base, significa que la importación se aplicará a cualquier versión del módulo. |
QQmlModuleImportLatest | -1 | Cuando se pasa como versión principal o secundaria del módulo importado, significa que se importará la última versión global o la última versión secundaria de una versión principal especificada. |
QQmlModuleImportAuto | -2 | Cuando se pasa como versión principal del módulo importado, significa que se debe utilizar la versión del módulo base. |
Documentación de la función
template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)
La sintaxis de esta función de plantilla es:
template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)Devuelve la instancia del objeto adjunto que se ha adjuntado a la « attachee » especificada mediante el tipo de adjunto T.
Si attachee es nullptr, devuelve nullptr.
Si existe una instancia de objeto adjunta del tipo T, la devolverá. De lo contrario, devolverá una instancia recién creada si ` createIfMissing ` es ` true ` y `T` es un tipo de adjunción 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 generados con ` qmlRegisterType()`.
Advertencia: No llames a esta función mientras exista un ` QQmlEngine `, ya que el comportamiento será indefinido. Cualquier `QQmlEngine` existente debe eliminarse antes de llamar a esta función.
Esta función solo afecta a la caché global de la aplicación. Elimina el ` QQmlEngine ` para borrar todos los datos almacenados en caché relacionados con ese motor.
QObject *qmlExtendedObject(QObject *base)
Esta función devuelve el objeto de extensión asociado a base, si existe alguno. De lo contrario, devuelve nullptr.
Véase también QML_EXTENDED.
bool qmlProtectModule(const char *uri, int majVersion)
Esta función protege un módulo frente a modificaciones posteriores. Se puede utilizar para evitar que otros complementos 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 posible existencia de nuevos tipos o complementos cuando se llega a esta importación.
Una vez que se ha llamado a `qmlProtectModule`, el motor QML ya no buscará un nuevo archivo ` qmldir ` para cargar el módulo. No obstante, reutilizará cualquier archivo ` qmldir ` que haya cargado anteriormente. Por lo tanto, los tipos presentes en este momento siguen funcionando. Ten en cuenta que diferentes motores QML pueden cargar módulos distintos. La protección del módulo, sin embargo, es global y afecta a todos los motores. La sobrecarga que supone localizar los archivos qmldir y cargar complementos puede ser notable en sistemas de archivos lentos. Por lo tanto, proteger un módulo una vez que estés seguro de que ya no necesitarás cargarlo puede ser una buena optimización. Ten en cuenta también que el bloqueo del módulo no solo afecta a los complementos, 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, una vez llamada esta función, cualquier intento de registrar tipos de C++ en esta combinación de URI y versión principal provocará un error en tiempo de ejecución.
Devuelve «true» si se ha encontrado y bloqueado el módulo con uri como identificador de módulo y majVersion como número de versión principal; en caso contrario, devuelve «false». Para que el módulo pueda encontrarse, debe contener tipos exportados.
template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)
Esta función de plantilla registra el tipo de 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, sí se puede acceder a las instancias de este tipo cuando se exponen como propiedades de otros tipos.
Utiliza esta función cuando no se vaya a hacer referencia al tipo por su nombre, concretamente para los tipos de C++ que se utilizan en el lado izquierdo de un enlace de propiedad. Para indicar a qué módulo pertenece el tipo, utiliza uri y versionMajor.
Por ejemplo, consideremos 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 de QML sepa que el tipo « Bar » tiene una propiedad « baz », debemos hacer que « Bar » sea reconocible:
qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterAnonymousType<Bar>("App", 1);Dado que el tipo ` Foo ` se instancia en QML, debe registrarse con la versión de ` qmlRegisterType()` que toma un nombre de elemento.
Devuelve el identificador 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 de C++ y su objeto de extensión en el sistema QML con el nombre qmlName en la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor. Las propiedades que no estén disponibles en el tipo principal se buscarán en el objeto de extensión.
Devuelve el identificador 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 de C++ y su extensión en el sistema QML con el nombre qmlName en la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor.
Aunque el tipo tiene un nombre y un tipo, no se puede crear. Si el usuario intenta crear una instancia de este tipo, se muestra un mensaje de error con el valor de « reason » indicado.
Esto resulta útil cuando el tipo solo está destinado a proporcionar propiedades adjuntas, valores de enumeración o una clase base abstracta con su extensión.
Devuelve el identificador 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 repositorio concreto uri con una versión especificada en versionMajor y versionMinor.
Esto puede utilizarse para que una determinada versión de un módulo esté disponible, incluso si no hay ningún tipo registrado para esa versión. Resulta especialmente ú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 una importación «qmldir-import» para el módulo uri de la versión principal moduleMajor.
Esto tiene el mismo efecto que una instrucción « import » en un archivo «qmldir»: cada vez que se importa « uri » de la versión « moduleMajor », también se importan automáticamente « import » de la versión « importMajor » y « importMinor ». Si « importMajor » es « QQmlModuleImportLatest », se importa la última versión disponible de ese módulo, y « importMinor » no tiene importancia. Si « importMinor » es « QQmlModuleImportLatest », se elige la última versión secundaria de « importMajor ». Si « importMajor » es « QQmlModuleImportAuto », la versión de « import » es la versión de « uri » que se está importando, y « importMinor » no tiene importancia. Si moduleMajor es QQmlModuleImportModuleAny, la importación del módulo se aplica a cualquier versión principal de uri. Por ejemplo, puedes especificar que, siempre que se importe cualquier versión de MyModule, se importe la última versión de MyOtherModule. En ese caso, la siguiente llamada sería la adecuada:
qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
"MyOtherModule", QQmlModuleImportLatest);O bien, puedes especificar que, cada vez que se importe la versión principal 5 de «MyModule», se importe la versión 3.14 de «MyOtherModule»:
qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);Por último, si siempre quieres que se importe la misma versión de «MyOtherModule» cada vez que se importe «MyModule», especifica 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 el tipo de C++ T en la revisión especificada metaObjectRevision en el sistema QML, con la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor.
Devuelve el identificador 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 (véase 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 uri y un typeName concretos. 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 de dicho tipo.
Utiliza esta función para registrar un objeto del tipo T dado como tipo singleton.
Se puede hacer referencia a un tipo singleton QObject 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 puede tener un alias, ya que el nombre del tipo singleton no identifica a un objeto dentro del mismo componente que cualquier otro elemento.
Nota: ` cppObject ` debe sobrevivir al motor QML en el que se utiliza. Además, ` cppObject ` debe tener la misma afinidad de hilo que el motor. Si deseas instancias singleton independientes para varios motores, debes utilizar ` qmlRegisterSingletonType`. Consulta «Hilos y QObjects» para obtener más información sobre la seguridad de hilos.
NOTA: qmlRegisterSingleton solo se puede utilizar cuando todos los tipos de ese módulo se registran de forma procedimental.
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, debes 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 se puede utilizar para registrar un tipo singleton con el nombre qmlName, en la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor. El tipo se define mediante el archivo QML ubicado en url. La URL debe ser absoluta, es decir, url.isRelative() == false.
Además, el archivo QML del tipo debe incluir la instrucción pragma Singleton entre sus instrucciones de importación.
Se puede hacer referencia a un tipo singleton mediante el nombre de tipo con el que se registró, y este nombre de tipo puede utilizarse como destino en un tipo « Connections » o emplearse de cualquier otra forma, al igual que cualquier otro identificador de tipo. Una excepción a esto es que una propiedad de tipo singleton no puede tener un alias (ya que el nombre del tipo singleton no identifica a un objeto dentro del mismo componente que cualquier otro elemento).
Uso:
// 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, debes importar dicho tipo.
import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
id: root
property int someValue: RegisteredSingleton.testProp1
}También es posible registrar tipos singleton de QML sin utilizar la función `qmlRegisterSingletonType`. Para ello, basta con añadir una instrucción `pragma Singleton` entre las importaciones del archivo QML del tipo. Además, el tipo debe definirse en un archivo qmldir con la palabra clave «singleton», y los archivos QML que utilicen el singleton deben importar dicho qmldir.
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 uri y un typeName concretos, con una versión especificada en versionMajor y versionMinor.
La instalación de un tipo singleton permite a los desarrolladores proporcionar funcionalidad arbitraria (métodos y propiedades) a un cliente sin necesidad de que este tenga que instanciar instancias individuales del tipo.
Un tipo singleton puede ser un « QObject » o un « QJSValue ». Esta función debe utilizarse para registrar una función proveedora de tipos singleton que devuelva un « QJSValue » como tipo singleton.
NOTA: Las propiedades de los tipos singleton de tipo « QJSValue » no provocarán una reevaluación del enlace si se modifican.
Uso:
// 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, puedes utilizar una lambda de 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, debes importar dicho tipo.
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 puede utilizarse para registrar un proveedor de tipo singleton callback en un uri y un typeName concretos, con una versión especificada en versionMajor y versionMinor.
La instalación de un tipo singleton en un URI permite a los desarrolladores proporcionar funcionalidad arbitraria (métodos y propiedades) a los clientes sin necesidad de que estos instancien instancias individuales del tipo.
Un tipo singleton puede ser un « QObject » o un « QJSValue ». Esta función debe utilizarse para registrar una función proveedora de tipos singleton que devuelva un « QObject » del tipo T dado como tipo singleton.
Se puede hacer referencia a un tipo singleton de tipo « QObject » mediante el nombre de tipo con el que se registró, y este nombre de tipo puede utilizarse como destino en un tipo « Connections » o bien utilizarse como se haría con cualquier otro identificador de tipo. Una excepción a esto es que una propiedad de tipo singleton de tipo « QObject » no puede tener un alias.
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 establecida explícitamente la bandera QQmlEngine::CppOwnership.
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:
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, puedes utilizar una lambda de 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, debes importar dicho tipo.
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 de C++ en el sistema QML con el nombre « qmlName », en la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor.
Devuelve el identificador 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 de C++ MySliderItem como un tipo QML denominado 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 se puede utilizar en QML importando el espacio de nombres de tipos y el número de versión especificados:
import com.mycompany.qmlcomponents 1.0
Slider {
// ...
}Ten en cuenta que es perfectamente razonable que una biblioteca registre tipos para versiones anteriores a la versión actual de la biblioteca. De hecho, es normal que la nueva biblioteca permita que el código QML escrito para versiones anteriores siga funcionando, incluso si hay disponibles versiones más avanzadas de algunos de sus tipos.
Véase también « QML_ELEMENT» , « QML_NAMED_ELEMENT()» y «Choosing the Correct Integration Method Between C++ and 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 desde uri, cuyo número de versión se compone de versionMajor y versionMinor. El tipo se define mediante el archivo QML ubicado en url. La URL debe ser absoluta, es decir, url.isRelative() == false.
Normalmente, los archivos QML se pueden cargar como tipos directamente desde otros archivos QML o mediante un archivo qmldir. Esta función permite registrar archivos como tipos desde código C++, por ejemplo, cuando es necesario determinar la asignación de tipos de forma procedimental 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 desde uri, con un número de versión compuesto por versionMajor y versionMinor; sin embargo, cualquier intento de instanciar el tipo generará el error indicado message.
Normalmente, los tipos exportados por un complemento deberían ser fijos. Sin embargo, si un tipo de C++ no está disponible, deberías al menos «reservar» el nombre del tipo QML y proporcionar al usuario del tipo no disponible un mensaje de error significativo.
Devuelve el identificador 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");
#endifEsto hará que cualquier código QML que importe el espacio de nombres de tipos «MinehuntCore» e intente utilizar el tipo genere un mensaje de error:
fun.qml: Get back to work, slacker!
Game {
^Sin esto, se mostraría un mensaje genérico del tipo «Game no es un tipo».
Véase también QML_UNAVAILABLE, qmlRegisterUncreatableType() y «Cómo 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 objeto « staticMetaObject » y su extensión en el sistema QML con el nombre « qmlName » en la biblioteca importada desde uri, cuyo número de versión se compone de versionMajor y versionMinor.
No se puede crear una instancia del metaobjeto. Si el usuario intenta crearla, se muestra un mensaje de error con el reason indicado.
Esta función resulta útil para registrar espacios de nombres Q_NAMESPACE.
Devuelve el identificador 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 de QML, ahora puedes utilizar las enumeraciones registradas:
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 de C++ en el sistema QML con el nombre « qmlName », en la biblioteca importada desde « uri », cuyo número de versión se compone de « versionMajor » y « versionMinor ».
Aunque el tipo tiene un nombre y un tipo, no se puede crear, y si se intenta crearlo se producirá el error indicado: « message ».
Esto resulta útil cuando el tipo solo está destinado a proporcionar propiedades asociadas o valores de enumeración.
Devuelve el identificador del tipo QML.
Véase también QML_UNCREATABLE(), qmlRegisterTypeNotAvailable() y «Elegir el método de integración correcto entre C++ y QML».
int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
Devuelve el identificador de tipo QML de un tipo que se registró con el nombre qmlName en una uri concreta y con una versión especificada en versionMajor y versionMinor.
Esta función devuelve el mismo valor que las funciones de registro de tipos de QML, como qmlRegisterType() y qmlRegisterSingletonType().
Si qmlName, uri y versionMajor coinciden con un tipo registrado, pero la versión menor especificada en versionMinor es superior, se devuelve el identificador del tipo con la versión menor más cercana.
Devuelve -1 si no se ha encontrado ningún tipo que coincida o si alguno de los parámetros proporcionados 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 suponer una sobrecarga la primera vez que se accede a un módulo. Intentar buscar tipos en un módulo que no existe siempre supone 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 registrada previamente con qmlRegisterModuleImport()
Al llamar a esta función, se garantiza que import de la versión importMajor.importMinor ya no se importe automáticamente cuando se importe uri de la versión moduleMajor. La resolución de la versión funciona de la misma manera 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, tal y como se describe en el ` Flags` especificado.
Actualmente, la única información de tipo compatible es QML_HAS_ATTACHED_PROPERTIES, que declara que Type admite propiedades asociadas. No es necesario utilizar QML_DECLARE_TYPEINFO() 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.