QQmlApplicationEngine Class
QQmlApplicationEngine ofrece una forma sencilla de cargar una aplicación a partir de un único archivo QML. Más información...
| Encabezado: | #include <QQmlApplicationEngine> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Heredado de: | QQmlEngine |
Funciones públicas
| QQmlApplicationEngine(QObject *parent = nullptr) | |
| QQmlApplicationEngine(const QString &filePath, QObject *parent = nullptr) | |
| QQmlApplicationEngine(const QUrl &url, QObject *parent = nullptr) | |
(since 6.5) | QQmlApplicationEngine(QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr) |
| virtual | ~QQmlApplicationEngine() override |
| QList<QObject *> | rootObjects() const |
Ranuras públicas
| void | load(const QString &filePath) |
| void | load(const QUrl &url) |
| void | loadData(const QByteArray &data, const QUrl &url = QUrl()) |
(since 6.5) void | loadFromModule(QAnyStringView uri, QAnyStringView typeName) |
(since 6.0) void | setExtraFileSelectors(const QStringList &extraFileSelectors) |
| void | setInitialProperties(const QVariantMap &initialProperties) |
Señales
| void | objectCreated(QObject *object, const QUrl &url) |
(since 6.4) void | objectCreationFailed(const QUrl &url) |
Descripción detallada
Esta clase combina un « QQmlEngine » y un « QQmlComponent » para ofrecer una forma cómoda de cargar un único archivo QML. También expone algunas funcionalidades centrales de la aplicación a QML, que una aplicación híbrida C++/QML controlaría normalmente desde C++.
Se puede utilizar de la siguiente manera:
#include <QGuiApplication>
#include <QQmlApplicationEngine>
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine("main.qml");
return app.exec();
}Nota: A diferencia de QQuickView, QQmlApplicationEngine no crea automáticamente una ventana raíz. Si utilizas elementos visuales de Qt Quick, deberás colocarlos dentro de un Window.
También puedes utilizar QCoreApplication con QQmlApplicationEngine, si no utilizas ningún módulo QML que requiera un QGuiApplication (como QtQuick).
Lista de cambios de configuración respecto a un QQmlEngine predeterminado:
- quitConexión de Qt XML-ph-0000@deepl.internal con QCoreApplication::quit
- Carga automáticamente los archivos de traducción desde un directorio i18n adyacente al archivo QML principal.
- Las traducciones se vuelven a cargar cuando se modifica la propiedad
QJSEngine::uiLanguage/Qt.uiLanguage. - Establece automáticamente un controlador de incubación si la escena contiene un QQuickWindow.
- Establece automáticamente un `
QQmlFileSelector` como interceptor de URL, aplicando selectores de archivos a todos los archivos QML y recursos.
El comportamiento del motor se puede ajustar aún más utilizando los métodos heredados de ` QQmlEngine`.
Nota: Los archivosde traducción deben llevar el prefijo «qml_» para que se reconozcan, p. ej., «qml_ja_JP.qm».
Nota: Para colocar los archivos de traducción de forma relativa al archivo QML principal, es necesario añadir un RESOURCE_PREFIX a la llamada correspondiente a `qt_add_translations`. Este debe incluir el prefijo de recursos del módulo Qml del archivo principal (/qt/qml por defecto) y el URI del módulo. Por ejemplo, para proporcionar archivos de traducción para un módulo llamado «Translated»:
qt_add_translations(App
RESOURCE_PREFIX /qt/qml/Translated/i18n
TS_FILE_BASE qml
TS_FILE_DIR i18n
)Documentación de funciones de miembro
QQmlApplicationEngine::QQmlApplicationEngine(QObject *parent = nullptr)
Crea un nuevo objeto `QQmlApplicationEngine` con la dirección ` parent` indicada. Más adelante tendrás que llamar a ` load()` para cargar un archivo QML.
QQmlApplicationEngine::QQmlApplicationEngine(const QString &filePath, QObject *parent = nullptr)
Crea un nuevo `QQmlApplicationEngine` y carga el archivo QML en la ruta ` filePath` indicada, que debe ser un archivo local o una ruta `qrc`. Si se especifica una ruta relativa, se interpretará como relativa al directorio de trabajo de la aplicación.
Esto se ofrece para mayor comodidad y equivale a utilizar el constructor vacío y llamar a load a continuación.
QQmlApplicationEngine::QQmlApplicationEngine(const QUrl &url, QObject *parent = nullptr)
Crea un nuevo objeto `QQmlApplicationEngine` y carga el archivo QML en la ruta indicada ` url`. Esta función se ofrece para mayor comodidad y equivale a utilizar el constructor vacío y llamar a `load` a continuación.
[explicit, since 6.5] QQmlApplicationEngine::QQmlApplicationEngine(QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)
Crea un nuevo `QQmlApplicationEngine` y carga el tipo QML especificado por ` uri ` y ` typeName `. Esta función se proporciona para mayor comodidad y equivale a utilizar el constructor vacío y llamar a ` loadFromModule ` a continuación.
Esta función se introdujo en Qt 6.5.
[override virtual noexcept] QQmlApplicationEngine::~QQmlApplicationEngine()
Elimina el objeto « QQmlApplicationEngine » y todos los objetos QML que haya cargado.
[slot] void QQmlApplicationEngine::load(const QString &filePath)
Carga el archivo QML raíz ubicado en filePath. filePath debe ser una ruta a un archivo local o una ruta a un archivo del sistema de recursos. Si filePath es una ruta relativa, se considera relativa al directorio de trabajo de la aplicación. El árbol de objetos definido por el archivo se instancia inmediatamente.
Si se produce un error, se muestran mensajes de error mediante ` qWarning`.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
qmlApplicationEngine, qOverload(&QQmlApplicationEngine::load));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
qmlApplicationEngine, [receiver = qmlApplicationEngine](const QString &filePath) { receiver->load(filePath); }); [slot] void QQmlApplicationEngine::load(const QUrl &url)
Carga el archivo QML raíz ubicado en url. El árbol de objetos definido por el archivo se crea inmediatamente en el caso de las URL de archivos locales. Las URL remotas se cargan de forma asíncrona; hay que estar atento a la señal objectCreated para determinar cuándo está listo el árbol de objetos.
Si se produce un error, se emite la señal ` objectCreated ` con un puntero nulo como parámetro y se muestran los mensajes de error mediante ` qWarning`.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
qmlApplicationEngine, qOverload(&QQmlApplicationEngine::load));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
qmlApplicationEngine, [receiver = qmlApplicationEngine](const QUrl &url) { receiver->load(url); }); [slot] void QQmlApplicationEngine::loadData(const QByteArray &data, const QUrl &url = QUrl())
Carga el código QML que figura en data. El árbol de objetos definido en data se instancia inmediatamente.
Si se especifica una URL en url, esta se utiliza como URL base del componente. Esto afecta a las rutas relativas dentro de los datos y a los mensajes de error.
Si se produce un error, los mensajes de error se muestran utilizando qWarning.
[slot, since 6.5] void QQmlApplicationEngine::loadFromModule(QAnyStringView uri, QAnyStringView typeName)
Carga el tipo QML « typeName » desde el módulo especificado por « uri ». Si el tipo procede de un archivo QML ubicado en una URL remota, se cargará de forma asíncrona. Se debe escuchar la señal « objectCreated » para determinar cuándo está listo el árbol de objetos.
Si se produce un error, se emite la señal ` objectCreated ` con un puntero nulo como parámetro y se muestran mensajes de error mediante ` qWarning`.
QQmlApplicationEngine engine;
engine.loadFromModule("QtQuick", "Rectangle");Nota: El módulo identificado por ` uri ` se busca en la ruta de importación, del mismo modo que si se utilizara ` import uri ` dentro de un archivo QML. Si el módulo no se encuentra allí, esta función fallará.
Esta función se introdujo en Qt 6.5.
Véase también QQmlComponent::loadFromModule.
[signal] void QQmlApplicationEngine::objectCreated(QObject *object, const QUrl &url)
Esta señal se emite cuando un objeto termina de cargarse. Si la carga se ha realizado correctamente, ` object ` contiene un puntero al objeto cargado; en caso contrario, el puntero es `NULL`.
También se proporciona el ` url ` al componente del que procede el ` object `.
Nota: Si la ruta al componente se proporcionó como un ` QString ` que contiene una ruta relativa, el ` url ` contendrá una ruta completamente resuelta al archivo.
[signal, since 6.4] void QQmlApplicationEngine::objectCreationFailed(const QUrl &url)
Esta señal se emite cuando finaliza la carga debido a que se ha producido un error.
Se proporciona como argumento el objeto ` url ` correspondiente al componente que no se ha podido cargar.
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;
// exit on error
QObject::connect(&engine, &QQmlApplicationEngine::objectCreationFailed,
&app, []() { QCoreApplication::exit(-1); }, Qt::QueuedConnection);
engine.load(QUrl());
return app.exec();Nota: Si la ruta al componente se proporcionó como un ` QString ` que contiene una ruta relativa, el ` url ` contendrá una ruta completamente resuelta al archivo.
Véase también QQmlApplicationEngine::objectCreated, que se emitirá además de esta señal (aunque la creación haya fallado).
Esta función se introdujo en Qt 6.4.
QList<QObject *> QQmlApplicationEngine::rootObjects() const
Devuelve una lista de todos los objetos raíz instanciados mediante ` QQmlApplicationEngine`. Esta lista solo contendrá objetos cargados mediante ` load()` o un constructor de conveniencia.
Nota: En las versiones de Qt anteriores a la 5.9, esta función está marcada como noconst.
[slot, since 6.0] void QQmlApplicationEngine::setExtraFileSelectors(const QStringList &extraFileSelectors)
Establece los valores de ` extraFileSelectors ` que se pasarán a la función interna ` QQmlFileSelector `, utilizada para resolver las URL en archivos locales. Los valores de ` extraFileSelectors ` se aplican al cargarse el primer archivo QML. Establecerlos posteriormente no tiene ningún efecto.
Esta función se introdujo en Qt 6.0.
Véase también QQmlFileSelector y QFileSelector::setExtraSelectors.
[slot] void QQmlApplicationEngine::setInitialProperties(const QVariantMap &initialProperties)
Establece el ` initialProperties ` con el que se inicializa el componente QML tras su carga.
QQmlApplicationEngine engine;
EventDatabase eventDatabase;
EventMonitor eventMonitor;
engine.setInitialProperties({
{ "eventDatabase", QVariant::fromValue(&eventDatabase) },
{ "eventMonitor", QVariant::fromValue(&eventMonitor) }
});Véase también QQmlComponent::setInitialProperties, QQmlApplicationEngine::load y QQmlApplicationEngine::loadData.
© 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.