QQmlEngine Class

Documentación de las funciones miembro

[explicit] QQmlEngine::QQmlEngine(QObject *parent = nullptr)

Crea un nuevo QQmlEngine con la dirección parent.

[override virtual noexcept] QQmlEngine::~QQmlEngine()

Destruye el objeto QQmlEngine.

Cualquier QQmlContext's creado en este motor será invalidado, pero no destruido (a menos que estén emparentados con el objeto QQmlEngine ).

Véase ~QJSEngine() para más detalles sobre la limpieza del motor JS.

void QQmlEngine::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)

Establece el provider a utilizar para las imágenes solicitadas a través del esquema image: url, con el host providerId. QQmlEngine se apropia de provider.

Los proveedores de imágenes admiten solicitudes de imágenes de mapa de píxeles y enhebradas. Consulte la documentación de QQuickImageProvider para obtener más información sobre la implementación y el uso de proveedores de imágenes.

Todos los proveedores de imágenes necesarios deben añadirse al motor antes de cargar los archivos fuente QML.

Véase también removeImageProvider(), QQuickImageProvider, y QQmlImageProviderBase.

void QQmlEngine::addImportPath(const QString &path)

Añade path como directorio donde el motor busca los módulos instalados en una estructura de directorios basada en URL.

path puede ser un directorio del sistema de archivos local, una ruta de recursos Qt (:/imports), una url de recursos Qt (qrc:/imports) o una URL.

path se convertirá en forma canónica antes de añadirse a la lista de rutas de importación.

La nueva path añadida será la primera en la importPathList().

Véase también setImportPathList(), Módulos QML y Ruta de importación QML.

void QQmlEngine::addPluginPath(const QString &path)

Añade path como directorio en el que el motor busca plugins nativos para módulos importados (referenciados en el archivo qmldir ).

Por defecto, la lista sólo contiene ., es decir, el motor busca en el directorio del propio archivo qmldir.

El nuevo path añadido será el primero en la lista pluginPathList().

Véase también setPluginPathList().

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Añade un urlInterceptor que se utilizará al resolver URL en QML. Esto también se aplica a las URL utilizadas para cargar archivos de script y tipos QML. Los interceptores de URL no deben ser modificados mientras el motor está cargando archivos, o la selección de URL puede ser inconsistente. Múltiples interceptores de URL, cuando se dan, serán llamados en el orden en que fueron añadidos para cada URL.

QQmlEngine no toma posesión del interceptor y no lo borrará.

QUrl QQmlEngine::baseUrl() const

Devuelve la URL base de este motor. La URL base sólo se utiliza para resolver componentes cuando se pasa una URL relativa al constructor QQmlComponent.

Si no se ha establecido explícitamente una URL base, este método devuelve el directorio de trabajo actual de la aplicación.

Véase también setBaseUrl().

void QQmlEngine::clearComponentCache()

Borra la caché interna de componentes del motor.

Esta función hace que se destruyan los metadatos de propiedades de la mayoría de los componentes previamente cargados por el motor. Lo hace eliminando los componentes no referenciados de la caché de componentes del motor. No elimina los componentes a los que todavía se hace referencia, ya que esto provocaría, casi con toda seguridad, fallos más adelante.

Si no hay componentes referenciados, esta función devuelve el motor a un estado en el que no contiene ningún dato de componente cargado. Esto puede ser útil para recargar un subconjunto más pequeño del conjunto de componentes anterior, o para cargar una nueva versión de un componente previamente cargado.

Una vez borrada la caché de componentes, éstos deben cargarse antes de poder crear nuevos objetos.

Como regla general, asegúrese de que ningún objeto creado a partir de componentes QML esté vivo cuando borre la caché de componentes.

Véase también trimComponentCache() y clearSingletons().

void QQmlEngine::clearSingletons()

Borra todos los singletons que posee el motor.

Esta función elimina todas las instancias singleton, borrando cualquier QObjects propiedad del motor entre ellos. Esto es útil para asegurarse de que no quedan objetos creados con QML antes de llamar a clearComponentCache().

Las propiedades QML que contienen instancias singleton basadas en QObject se vuelven nulas si el motor posee el singleton o conservan su valor si el motor no lo posee. Los singletons no se vuelven a crear automáticamente al acceder a objetos QML creados existentes. Sólo se vuelven a crear cuando se instancian nuevos componentes.

Véase también clearComponentCache().

[static] QQmlContext *QQmlEngine::contextForObject(const QObject *object)

Devuelve el QQmlContext para el object, o nullptr si no se ha establecido ningún contexto.

Cuando QQmlEngine instancia un QObject, se le asigna automáticamente un contexto interno. Estos contextos internos son de sólo lectura. No se pueden establecer propiedades de contexto en ellos.

Véase también setContextForObject(), qmlContext(), qmlEngine() y QQmlContext::setContextProperty().

[override virtual protected] bool QQmlEngine::event(QEvent *e)

Reimplementa: QObject::event(QEvent *e).

[signal] void QQmlEngine::exit(int retCode)

Esta señal se emite cuando el QML cargado por el motor desea salir del bucle de eventos con el código de retorno especificado retCode.

Véase también quit().

QQmlImageProviderBase *QQmlEngine::imageProvider(const QString &providerId) const

Devuelve el proveedor de imágenes establecido para providerId si se encuentra; en caso contrario, devuelve nullptr.

Véase también QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

Devuelve la lista de directorios en los que el motor busca los módulos instalados en una estructura de directorios basada en URL.

Por ejemplo, si /opt/MyApp/lib/imports está en la ruta, entonces QML que importa com.mycompany.Feature hará que QQmlEngine busque en /opt/MyApp/lib/imports/com/mycompany/Feature/ los componentes proporcionados por ese módulo. Se necesita un archivo qmldir para definir la asignación de versiones de tipos y, posiblemente, los plugins de extensiones QML.

Por defecto, esta lista contiene las rutas mencionadas en Ruta de importación QML.

Véase también addImportPath() y setImportPathList().

QQmlIncubationController *QQmlEngine::incubationController() const

Devuelve el controlador de incubación establecido actualmente, o 0 si no se ha establecido ningún controlador.

Véase también setIncubationController().

QUrl QQmlEngine::interceptUrl(const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const

Ejecuta los interceptores de URL actuales en el url dado del type dado y devuelve el resultado.

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

Si se llama a este método dentro de una función que forma parte de una vinculación en QML, la vinculación se tratará como una vinculación de traducción.

class I18nAwareClass : public QObject {

  //...

   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

Esta función se introdujo en Qt 6.6.

Véase también QQmlEngine::retranslate.

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

Devuelve un QNetworkAccessManager común que puede ser utilizado por cualquier tipo QML instanciado por este motor.

Si se ha establecido un QQmlNetworkAccessManagerFactory y aún no se ha creado un QNetworkAccessManager, se utilizará el QQmlNetworkAccessManagerFactory para crear el QNetworkAccessManager; de lo contrario, el QNetworkAccessManager devuelto no tendrá ningún proxy o caché establecido.

Véase también setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Devuelve la dirección actual QQmlNetworkAccessManagerFactory.

Véase también setNetworkAccessManagerFactory().

QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const

Devuelve la ruta del archivo donde se encuentra (o se encontraría) una base de datos Local Storage con el identificador databaseName.

Véase también LocalStorage.openDatabaseSync().

[signal, since 6.5] void QQmlEngine::offlineStoragePathChanged()

Esta señal se emite cuando cambia offlineStoragePath.

Esta función se introdujo en Qt 6.5.

bool QQmlEngine::outputWarningsToStandardError() const

Devuelve true si los mensajes de advertencia serán enviados a stderr además de ser emitidos por la señal warnings(), en caso contrario false.

El valor por defecto es true.

Véase también setOutputWarningsToStandardError().

QStringList QQmlEngine::pluginPathList() const

Devuelve la lista de directorios en los que el motor busca plugins nativos para módulos importados (referenciados en el archivo qmldir ).

Por defecto, la lista sólo contiene ., es decir, el motor busca en el directorio del propio archivo qmldir.

Véase también addPluginPath() y setPluginPathList().

[signal] void QQmlEngine::quit()

Esta señal se emite cuando el QML cargado por el motor desea salir.

Véase también exit().

void QQmlEngine::removeImageProvider(const QString &providerId)

Elimina el proveedor de imágenes de providerId.

Véase también addImageProvider() y QQuickImageProvider.

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Elimina un urlInterceptor que fue añadido previamente usando addUrlInterceptor. Los interceptores de URL no deben ser modificados mientras el motor está cargando archivos, o la selección de URL puede ser inconsistente.

Esto no elimina el interceptor, sino que simplemente lo retira del motor. Puede reutilizarlo posteriormente en el mismo motor o en otro diferente.

[slot] void QQmlEngine::retranslate()

Actualiza todas las expresiones vinculantes que utilizan cadenas marcadas para su traducción.

Llame a esta función después de haber instalado un nuevo traductor con QCoreApplication::installTranslator, para asegurarse de que su interfaz de usuario muestra traducciones actualizadas.

QQmlContext *QQmlEngine::rootContext() const

Devuelve el contexto raíz del motor.

El contexto raíz es creado automáticamente por QQmlEngine. Los datos que deben estar disponibles para todas las instancias de componentes QML que el motor implemente deben colocarse en el contexto raíz.

Los datos adicionales que sólo deben estar disponibles para un subconjunto de instancias de componentes deben añadirse a los subcontextos relacionados con el contexto raíz.

void QQmlEngine::setBaseUrl(const QUrl &url)

Establece la URL base para este motor en url.

Véase también baseUrl().

[static] void QQmlEngine::setContextForObject(QObject *object, QQmlContext *context)

Establece el QQmlContext para el object a context. Si el object ya tiene un contexto, se emite una advertencia, pero el contexto no se cambia.

Cuando QQmlEngine instancia un QObject, el contexto se establece automáticamente.

Véase también contextForObject().

void QQmlEngine::setImportPathList(const QStringList &paths)

Establece paths como la lista de directorios donde el motor busca los módulos instalados en una estructura de directorios basada en URL.

Por defecto, esta lista contiene las rutas mencionadas en Ruta de importación QML.

Véase también importPathList() y addImportPath().

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

Establece la incubación del motor controller. El motor sólo puede tener un controlador activo y no se apropia de él.

Véase también incubationController().

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Establece el factory que se utilizará para crear QNetworkAccessManager(s).

QNetworkAccessManager se utiliza para todos los accesos de red de QML. Implementando una fábrica es posible crear QNetworkAccessManager personalizados con soporte especializado de caché, proxy y cookies.

La fábrica debe establecerse antes de ejecutar el motor.

Véase también networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Establezca si los mensajes de advertencia se enviarán a stderr en enabled.

Si enabled es verdadero, cualquier mensaje de advertencia generado por QML será enviado a stderr y emitido por la señal warnings(). Si enabled es falso, sólo se emitirá la señal warnings(). De este modo, las aplicaciones pueden gestionar ellas mismas los mensajes de advertencia.

El valor por defecto es true.

Véase también outputWarningsToStandardError().

void QQmlEngine::setPluginPathList(const QStringList &paths)

Establece la lista de directorios en los que el motor busca plugins nativos para módulos importados (referenciados en el archivo qmldir ) en paths.

Por defecto, la lista sólo contiene ., es decir, el motor busca en el directorio del propio archivo qmldir.

Véase también pluginPathList() y addPluginPath().

template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)

Devuelve la instancia de un tipo singleton que se registró en qmlTypeId.

El argumento de plantilla T puede ser QJSValue o un puntero a un tipo derivado de QObject y depende de cómo se registró el singleton. Si todavía no se ha creado ninguna instancia de T, se crea ahora. Si qmlTypeId no representa un tipo singleton válido, se devuelve un QJSValue construido por defecto o un nullptr.

QObject* ejemplo:

class MySingleton : public QObject {
    Q_OBJECT

    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON

    static int typeId;
    // ...
};

    MySingleton::typeId = qmlTypeId(...);

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

QJSValue ejemplo:

    // Register with QJSValue callback
    int typeId = qmlRegisterSingletonType(...);

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

Se recomienda almacenar el id del tipo QML, por ejemplo, como un miembro estático en la clase singleton. La búsqueda a través de qmlTypeId() es costosa.

Véase también QML_SINGLETON, qmlRegisterSingletonType(), y qmlTypeId().

[since 6.5] template <typename T> T QQmlEngine::singletonInstance(QAnyStringView uri, QAnyStringView typeName)

Devuelve la instancia de un tipo singleton llamado typeName del módulo especificado por uri.

Este método puede utilizarse como alternativa a la llamada a qmlTypeId seguida de la sobrecarga basada en id de singletonInstance. Esto es conveniente cuando uno sólo necesita hacer una configuración única de un singleton; si se requiere acceso repetido al singleton, el almacenamiento en caché de su typeId permitirá un acceso posterior más rápido a través de type-id based overload.

El argumento T de la plantilla puede ser QJSValue o un puntero a un tipo derivado de QObject y depende de cómo se haya registrado el singleton. Si aún no se ha creado ninguna instancia de T, se crea ahora. Si typeName no representa un tipo singleton válido, se devuelve un QJSValue construido por defecto o un nullptr.

    QQmlEngine engine;
    MySingleton *singleton = engine.singletonInstance<MySingleton *>("mymodule", "MySingleton");

Esta función se introdujo en Qt 6.5.

Véase también QML_SINGLETON, qmlRegisterSingletonType(), y qmlTypeId().

void QQmlEngine::trimComponentCache()

Recorta la caché interna de componentes del motor.

Esta función hace que se destruyan los metadatos de propiedades de cualquier componente cargado que no se esté utilizando en ese momento.

Se considera que un componente está en uso si existen instancias del propio componente, instancias de otros componentes que utilicen el componente o cualquier objeto instanciado por cualquiera de esos componentes.

Véase también clearComponentCache().

QList<QQmlAbstractUrlInterceptor *> QQmlEngine::urlInterceptors() const

Devuelve la lista de interceptores de URL actualmente activos.

[signal] void QQmlEngine::warnings(const QList<QQmlError> &warnings)

Esta señal se emite cuando QML genera mensajes warnings.