QQuickWidget Class
La clase QQuickWidget proporciona un widget para mostrar una interfaz de usuario de tipo « Qt Quick ». Más información...
| Encabezado: | #include <qquickwidget.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS QuickWidgets) target_link_libraries(mytarget PRIVATE Qt6::QuickWidgets) |
| qmake: | QT += quickwidgets |
| Heredan de: | QWidget |
Tipos públicos
| enum | ResizeMode { SizeViewToRootObject, SizeRootObjectToView } |
| enum | Status { Null, Ready, Loading, Error } |
Propiedades
- resizeMode : ResizeMode
- source : QUrl
- status : Status
Funciones públicas
| QQuickWidget(QWidget *parent = nullptr) | |
| QQuickWidget(QQmlEngine *engine, QWidget *parent) | |
| QQuickWidget(const QUrl &source, QWidget *parent = nullptr) | |
(since 6.9) | QQuickWidget(QAnyStringView uri, QAnyStringView typeName, QWidget *parent = nullptr) |
| virtual | ~QQuickWidget() override |
| QQmlEngine * | engine() const |
| QList<QQmlError> | errors() const |
| QSurfaceFormat | format() const |
| QImage | grabFramebuffer() const |
| QSize | initialSize() const |
| QQuickWindow * | quickWindow() const |
| QQuickWidget::ResizeMode | resizeMode() const |
| QQmlContext * | rootContext() const |
| QQuickItem * | rootObject() const |
| void | setClearColor(const QColor &color) |
| void | setFormat(const QSurfaceFormat &format) |
| void | setResizeMode(QQuickWidget::ResizeMode) |
| QUrl | source() const |
| QQuickWidget::Status | status() const |
Ranuras públicas
(since 6.9) void | loadFromModule(QAnyStringView uri, QAnyStringView typeName) |
(since 6.9) void | setInitialProperties(const QVariantMap &initialProperties) |
| void | setSource(const QUrl &url) |
Señales
| void | sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message) |
| void | statusChanged(QQuickWidget::Status status) |
Funciones protegidas reimplementadas
| virtual void | dragEnterEvent(QDragEnterEvent *e) override |
| virtual void | dragLeaveEvent(QDragLeaveEvent *e) override |
| virtual void | dragMoveEvent(QDragMoveEvent *e) override |
| virtual void | dropEvent(QDropEvent *e) override |
| virtual bool | event(QEvent *e) override |
| virtual void | focusInEvent(QFocusEvent *event) override |
| virtual bool | focusNextPrevChild(bool next) override |
| virtual void | focusOutEvent(QFocusEvent *event) override |
| virtual void | hideEvent(QHideEvent *) override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | keyReleaseEvent(QKeyEvent *e) override |
| virtual void | mouseDoubleClickEvent(QMouseEvent *e) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mousePressEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *event) override |
| virtual void | showEvent(QShowEvent *) override |
| virtual void | wheelEvent(QWheelEvent *e) override |
Descripción detallada
Se trata de un envoltorio de conveniencia para QQuickWindow que cargará y mostrará automáticamente una escena QML cuando se le proporcione la URL del archivo fuente principal. Como alternativa, puedes instanciar tus propios objetos utilizando QQmlComponent y colocarlos en un QQuickWidget configurado manualmente.
Uso habitual:
QQuickWidget *view = new QQuickWidget;
view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
view->show();Para recibir errores relacionados con la carga y la ejecución de QML con QQuickWidget, puedes conectarte a la señal « statusChanged()» y supervisar « QQuickWidget::Error ». Los errores están disponibles a través de « QQuickWidget::errors()».
QQuickWidget también gestiona el redimensionamiento de la vista y del objeto raíz. Por defecto, resizeMode es SizeViewToRootObject, lo que cargará el componente y lo redimensionará al tamaño de la vista. Alternativamente, resizeMode puede establecerse en SizeRootObjectToView, lo que redimensionará la vista al tamaño del objeto raíz.
Consideraciones sobre el rendimiento
QQuickWidget es una alternativa al uso de QQuickView y QWidget::createWindowContainer(). Las restricciones sobre el orden de apilamiento no se aplican, lo que convierte a QQuickWidget en la alternativa más flexible, ya que se comporta de forma más similar a un widget normal.
Sin embargo, las ventajas mencionadas anteriormente tienen un coste en términos de rendimiento:
- A diferencia de QQuickWindow y QQuickView, QQuickWidget implica al menos una pasada de renderizado adicional dirigida a un búfer de color fuera de pantalla, normalmente una textura 2D, seguida del dibujo de un cuadrante de textura. Esto supone una mayor carga, especialmente para el procesamiento de fragmentos de la GPU.
- El uso de QQuickWidget desactiva el bucle de renderizado multihilo en todas las plataformas. Esto implica que algunas de las ventajas del renderizado multihilo, como las clases Animator y las animaciones controladas por vsync, no estarán disponibles.
Nota: Evita llamar a ` winId()` en un `QQuickWidget`. Esta función activa la creación de una ventana nativa, lo que provoca una reducción del rendimiento y, posiblemente, fallos de renderizado. El objetivo principal de `QQuickWidget` es renderizar escenas Quick sin una ventana nativa independiente, por lo que siempre debe evitarse convertirlo en un widget nativo.
Compatibilidad con API gráficas
QQuickWidget es compatible con todas las API gráficas 3D que admite Qt Quick, así como con el backend software. Sin embargo, otros backends, como OpenVG, no son compatibles, y cualquier intento de crear un QQuickWidget provocará problemas.
La sustitución de la API gráfica predeterminada de la plataforma se realiza de la misma forma que con QQuickWindow y QQuickView: bien llamando a ` QQuickWindow::setGraphicsApi()` antes de crear el primer `QQuickWidget`, bien estableciendo la variable de entorno ` QSG_RHI_BACKEND `.
Nota: Una ventana de nivel superior solo puede utilizar una única API gráfica para el renderizado. Por ejemplo, si se intenta colocar un QQuickWidget que utiliza Vulkan y otro que utiliza QOpenGLWidget en la jerarquía de widgets de la misma ventana de nivel superior, se producirán problemas y uno de los widgets no se renderizará como se espera.
Grafo de escena y persistencia del contexto
QQuickWidget respeta la función ` QQuickWindow::isPersistentSceneGraph()`, lo que significa que las aplicaciones pueden decidir —mediante la llamada a ` QQuickWindow::setPersistentSceneGraph()` en la ventana devuelta por la función ` quickWindow()`— permitir que los nodos del grafo de escena y otros recursos relacionados con la escena de ` Qt Quick ` se liberen cada vez que el widget quede oculto. Por defecto, la persistencia está habilitada, al igual que con ` QQuickWindow`.
Al ejecutarse con OpenGL, QQuickWindow ofrece también la posibilidad de desactivar los contextos OpenGL persistentes. Actualmente, QQuickWidget ignora esta configuración y el contexto es siempre persistente. Por lo tanto, el contexto de OpenGL no se destruye al ocultar el widget. El contexto solo se destruye cuando se destruye el widget o cuando este pasa a formar parte de la jerarquía de hijos de otro widget de nivel superior. Sin embargo, algunas aplicaciones, en particular aquellas que cuentan con sus propios recursos gráficos debido a que realizan un renderizado OpenGL personalizado en la escena Qt Quick, pueden desear desactivar esta última opción, ya que es posible que no estén preparadas para gestionar la pérdida del contexto al mover un QQuickWidget a otra ventana. Dichas aplicaciones pueden establecer el atributo QCoreApplication::AA_ShareOpenGLContexts. Para obtener más información sobre los detalles de la inicialización y la limpieza de recursos, consulte la documentación de « QOpenGLWidget ».
Nota: QQuickWidget ofrece un control menos preciso sobre su contexto OpenGL interno que QOpenGLWidget, y existen diferencias sutiles, entre las que destaca que desactivar el grafo de escena persistente provocará la destrucción del contexto al cambiar de ventana, independientemente de la presencia de QCoreApplication::AA_ShareOpenGLContexts.
Limitaciones
Colocar otros widgets debajo y hacer que el QQuickWidget sea transparente no dará los resultados esperados: los widgets que se encuentran debajo no serán visibles. Esto se debe a que, en la práctica, el QQuickWidget se dibuja antes que todos los demás widgets normales (que no sean de OpenGL), por lo que las soluciones de tipo «transparente» no son viables. Otros tipos de diseños, como colocar widgets encima del QQuickWidget, funcionarán según lo esperado.
Cuando sea absolutamente necesario, esta limitación puede superarse configurando el atributo « Qt::WA_AlwaysStackOnTop » en el QQuickWidget. Ten en cuenta, sin embargo, que esto altera el orden de superposición. Por ejemplo, no será posible colocar otros widgets encima del QQuickWidget, por lo que solo debe utilizarse en situaciones en las que se requiera un QQuickWidget semitransparente con otros widgets visibles debajo.
Esta limitación solo se aplica cuando hay otros widgets debajo del QQuickWidget dentro de la misma ventana. Para hacer que la ventana sea semitransparente, con otras aplicaciones y el escritorio visibles en segundo plano, se procede de la forma tradicional: se establece « Qt::WA_TranslucentBackground » en la ventana de nivel superior, se solicita un canal alfa y se cambia el color de transparenci Qt Quick del Scenegraph a « Qt::transparent » mediante ` setClearColor()` ().
Véase también «Exposición de atributos de tipos de C++ a QML», «Ejemplo de widgetsQt Quick » y « QQuickView ».
Documentación sobre tipos de miembros
enum QQuickWidget::ResizeMode
Esta enumeración especifica cómo cambiar el tamaño de la vista.
| Constante | Valor | Descripción |
|---|---|---|
QQuickWidget::SizeViewToRootObject | 0 | La vista cambia de tamaño con el elemento raíz en el QML. |
QQuickWidget::SizeRootObjectToView | 1 | La vista ajustará automáticamente el tamaño del elemento raíz al tamaño de la vista. |
enum QQuickWidget::Status
Especifica el estado de carga de QQuickWidget.
| Constante | Valor | Descripción |
|---|---|---|
QQuickWidget::Null | 0 | Este « QQuickWidget » no tiene ninguna fuente definida. |
QQuickWidget::Ready | 1 | Este « QQuickWidget » ha cargado y creado el componente QML. |
QQuickWidget::Loading | 2 | Este ` QQuickWidget ` está cargando datos de red. |
QQuickWidget::Error | 3 | Se han producido uno o más errores. Llama a ` errors()` para obtener una lista de errores. |
Documentación de propiedades
resizeMode : ResizeMode
Determina si la vista debe ajustar el tamaño del contenido de la ventana.
Si esta propiedad se establece en « SizeViewToRootObject » (valor predeterminado), la vista se redimensiona al tamaño del elemento raíz en el QML.
Si esta propiedad se establece en « SizeRootObjectToView », la vista redimensionará automáticamente el elemento raíz al tamaño de la vista.
Independientemente de esta propiedad, el «sizeHint» de la vista es el tamaño inicial del elemento raíz. No obstante, hay que tener en cuenta que, dado que el QML puede cargarse dinámicamente, ese tamaño puede variar.
Funciones de acceso:
| QQuickWidget::ResizeMode | resizeMode() const |
| void | setResizeMode(QQuickWidget::ResizeMode) |
Véase también ` initialSize()`.
source : QUrl
Esta propiedad contiene la URL de la fuente del componente QML.
Asegúrate de que la URL proporcionada sea completa y correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.
Nota: Al establecer una URL de origen, se instanciará el componente QML, incluso si la URL no ha cambiado con respecto al valor actual.
Funciones de acceso:
[read-only] status : Status
status o actual del componente.
Funciones de acceso:
| QQuickWidget::Status | status() const |
Señal de notificación:
| void | statusChanged(QQuickWidget::Status status) |
Documentación de las funciones de miembro
[explicit] QQuickWidget::QQuickWidget(QWidget *parent = nullptr)
Crea un QQuickWidget con un motor QML predeterminado como elemento hijo de ` parent`.
El valor por defecto de ` parent ` es ` nullptr`.
QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)
Crea un QQuickWidget con el objeto ` engine ` de QML especificado como elemento secundario de ` parent`.
Nota: El QQuickWidget no asume la propiedad del objeto « engine » especificado; es responsabilidad de quien realiza la llamada destruir el motor. Si el « engine » se elimina antes que la vista, « status()» devolverá « QQuickWidget::Error ».
[explicit] QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)
Crea un QQuickWidget con un motor QML predeterminado y el source QML especificado como elemento secundario de parent.
El valor por defecto de ` parent ` es ` nullptr`.
[explicit, since 6.9] QQuickWidget::QQuickWidget(QAnyStringView uri, QAnyStringView typeName, QWidget *parent = nullptr)
Crea un QQuickWidget con el elemento especificado por uri y typeName, y con el padre parent. El valor por defecto de parent es nullptr.
Esta función se introdujo en Qt 6.9.
Véase también loadFromModule.
[override virtual noexcept] QQuickWidget::~QQuickWidget()
Destruye el « QQuickWidget ».
[override virtual protected] void QQuickWidget::dragEnterEvent(QDragEnterEvent *e)
Reimplementa: QWidget::dragEnterEvent(QDragEnterEvent *event).
[override virtual protected] void QQuickWidget::dragLeaveEvent(QDragLeaveEvent *e)
Reimplementa: QWidget::dragLeaveEvent(QDragLeaveEvent *event).
[override virtual protected] void QQuickWidget::dragMoveEvent(QDragMoveEvent *e)
Reimplementa: QWidget::dragMoveEvent(QDragMoveEvent *event).
[override virtual protected] void QQuickWidget::dropEvent(QDropEvent *e)
Reimplementa: QWidget::dropEvent(QDropEvent *event).
QQmlEngine *QQuickWidget::engine() const
Devuelve un puntero al objeto ` QQmlEngine ` utilizado para instanciar componentes QML.
QList<QQmlError> QQuickWidget::errors() const
Devuelve la lista de errores que se produjeron durante la última operación de compilación o creación. Cuando el estado no es « Error », se devuelve una lista vacía.
Véase también « status ».
[override virtual protected] bool QQuickWidget::event(QEvent *e)
Reimplementa: ` QWidget::event(QEvent *event)`.
[override virtual protected] void QQuickWidget::focusInEvent(QFocusEvent *event)
Reimplementa: QWidget::focusInEvent(QFocusEvent *event).
[override virtual protected] bool QQuickWidget::focusNextPrevChild(bool next)
Reimplementa: ` QWidget::focusNextPrevChild` (`bool next`).
[override virtual protected] void QQuickWidget::focusOutEvent(QFocusEvent *event)
Reimplementa: QWidget::focusOutEvent(QFocusEvent *event).
QSurfaceFormat QQuickWidget::format() const
Devuelve el formato real de la superficie.
Si el widget aún no se ha mostrado, se devuelve el formato solicitado.
Véase también setFormat().
QImage QQuickWidget::grabFramebuffer() const
Renderiza un fotograma y lo vuelve a leer en una imagen.
Nota: Se trata de una operación que puede resultar costosa.
[override virtual protected] void QQuickWidget::hideEvent(QHideEvent *)
Reimplementa: QWidget::hideEvent(QHideEvent *event).
QSize QQuickWidget::initialSize() const
Devuelve el tamaño inicial del objeto raíz.
Si ` resizeMode ` es ` SizeRootObjectToView`, el objeto raíz se redimensionará al tamaño de la vista. Esta función devuelve el tamaño del objeto raíz antes de que se redimensionara.
[override virtual protected] void QQuickWidget::keyPressEvent(QKeyEvent *e)
Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.
[override virtual protected] void QQuickWidget::keyReleaseEvent(QKeyEvent *e)
Reimplementa: ` QWidget::keyReleaseEvent(QKeyEvent *event)`.
[slot, since 6.9] void QQuickWidget::loadFromModule(QAnyStringView uri, QAnyStringView typeName)
Carga el componente QML identificado por uri y typeName. Si el componente se basa en un archivo QML, source se establecerá en consecuencia. Para los tipos definidos en C++, source estará vacío.
Si se había establecido algún source antes de llamar a este método, se borrará.
Llamar a este método varias veces con el mismo uri y typeName dará lugar a que el componente QML se reinstancie.
Esta función se introdujo en Qt 6.9.
Véase también setSource, QQmlComponent::loadFromModule y QQmlApplicationEngine::loadFromModule.
[override virtual protected] void QQuickWidget::mouseDoubleClickEvent(QMouseEvent *e)
Reimplementa: ` QWidget::mouseDoubleClickEvent(QMouseEvent *event)`.
[override virtual protected] void QQuickWidget::mouseMoveEvent(QMouseEvent *e)
Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.
[override virtual protected] void QQuickWidget::mousePressEvent(QMouseEvent *e)
Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.
[override virtual protected] void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)
Reimplementa: ` QWidget::mouseReleaseEvent(QMouseEvent *event)`.
[override virtual protected] void QQuickWidget::paintEvent(QPaintEvent *event)
Reimplementa: QWidget::paintEvent(QPaintEvent *event).
QQuickWindow *QQuickWidget::quickWindow() const
Devuelve el objeto « QQuickWindow » fuera de pantalla que utiliza este widget para controlar el renderizado de « Qt Quick ». Esto resulta útil si deseas utilizar las API de « QQuickWindow » que actualmente no están expuestas en « QQuickWidget », por ejemplo, conectándote a la señal « QQuickWindow::beforeRendering()» para dibujar contenido nativo de OpenGL por debajo del propio renderizado de « Qt Quick ».
Advertencia: Utiliza el valor de retorno de esta función con precaución. En particular, no intentes nunca mostrar la ventana QQuickWindow, y ten mucho cuidado al utilizar otras API exclusivas de QWindow.
Advertencia: La ventana fuera de pantalla puede eliminarse (y recrearse) durante el ciclo de vida de QQuickWidget, especialmente cuando el widget se mueve a otro QQuickWindow. Si necesitas saber cuándo se ha sustituido la ventana, conéctate a su señal destroyed().
QQmlContext *QQuickWidget::rootContext() const
Esta función devuelve la raíz de la jerarquía de contextos. Cada componente QML se instancia en un ` QQmlContext`. Los ` QQmlContext` son esenciales para pasar datos a los componentes QML. En QML, los contextos se organizan jerárquicamente y esta jerarquía la gestiona el ` QQmlEngine`.
QQuickItem *QQuickWidget::rootObject() const
Devuelve la raíz de la vista ` item`. Puede ser ` nullptr ` cuando no se haya llamado a ` setSource()` o si se ha llamado con un código ` QtQuick ` defectuoso, o si el elemento raíz no está definido por cualquier otro motivo.
[signal] void QQuickWidget::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)
Esta señal se emite cuando se produce un error de « error » durante la inicialización del grafo de escenas.
Las aplicaciones deben conectarse a esta señal si desean gestionar errores, como fallos en la creación del contexto de OpenGL, de forma personalizada. Cuando no hay ningún slot conectado a la señal, el comportamiento será diferente: Quick mostrará el message o mostrará un cuadro de mensaje y cerrará la aplicación.
Esta señal se emitirá desde el hilo de la interfaz gráfica de usuario.
Véase también QQuickWindow::sceneGraphError().
void QQuickWidget::setClearColor(const QColor &color)
Establece el color transparente color. Por defecto, se trata de un color opaco.
Para obtener un « QQuickWidget » semitransparente, llama a esta función con « color » establecido en « Qt::transparent », configura el atributo del widget « Qt::WA_TranslucentBackground » en la ventana de nivel superior y solicita un canal alfa mediante « setFormat()».
Véase también QQuickWindow::setColor().
void QQuickWidget::setFormat(const QSurfaceFormat &format)
Establece la superficie format para el contexto y la superficie fuera de pantalla que utiliza este widget.
Llama a esta función cuando sea necesario solicitar un contexto para una versión o perfil de OpenGL determinado. Los tamaños de los búferes de profundidad, plantilla y alfa se gestionan automáticamente, por lo que no es necesario solicitarlos explícitamente.
Véanse también QWindow::setFormat(), QWindow::format() y format().
[slot, since 6.9] void QQuickWidget::setInitialProperties(const QVariantMap &initialProperties)
Establece las propiedades iniciales initialProperties con las que se inicializa el componente QML tras llamar a QQuickWidget::setSource().
Nota: Solose puede utilizar esta función para inicializar propiedades de nivel superior.
Nota: Esta función siempre debe llamarse antes de setSource, ya que no tiene ningún efecto una vez que el componente se ha convertido en Ready.
Esta función se introdujo en Qt 6.9.
Véase también QQmlComponent::createWithInitialProperties().
[slot] void QQuickWidget::setSource(const QUrl &url)
Establece la fuente en url, carga el componente QML y crea una instancia del mismo.
Asegúrate de que la URL proporcionada esté completa y sea correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.
Si se llama a este método varias veces con la misma URL, se volverá a instanciar el componente QML.
Nota: Funciónde configuración para la propiedad source.
Véase también source().
[override virtual protected] void QQuickWidget::showEvent(QShowEvent *)
Reimplementa: ` QWidget::showEvent(QShowEvent *event)`.
QUrl QQuickWidget::source() const
Devuelve la URL de origen, si está definida.
Nota: Funcióngetter para la propiedad «source».
Véase también setSource().
[signal] void QQuickWidget::statusChanged(QQuickWidget::Status status)
Esta señal se emite cuando cambia la propiedad « status » del componente.
Nota: Señalde notificación para la propiedad status.
[override virtual protected] void QQuickWidget::wheelEvent(QWheelEvent *e)
Reimplementa: QWidget::wheelEvent(QWheelEvent *event).
© 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.