QQuickWidget 类
QQuickWidget 类提供一个用于显示 Qt Quick 用户界面的小部件。 更多...
| 头文件 | #include <QQuickWidget> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS QuickWidgets) target_link_libraries(mytarget PRIVATE Qt6::QuickWidgets) |
| qmake | QT += quickwidgets |
| 继承 | QWidget |
公共类型
| 枚举 | ResizeMode { SizeViewToRootObject, SizeRootObjectToView } |
| 枚举 | Status { Null, Ready, Loading, Error } |
属性
- resizeMode : ResizeMode
- source : QUrl
- status : const Status
公共函数
| QQuickWidget(QWidget *parent = nullptr) | |
| QQuickWidget(QQmlEngine *engine, QWidget *parent) | |
| QQuickWidget(const QUrl &source, 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 |
公共槽
| void | setSource(const QUrl &url) |
信号
| void | sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message) |
| void | statusChanged(QQuickWidget::Status status) |
重实现受保护的函数
| 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 |
详细描述
这是一个对QQuickWindow的便利包装，当提供主源文件的URL时，将自动加载并显示一个QML场景。或者，您可以使用QQmlComponent实例化自己的对象，并将它们放入手动设置的QQuickWidget中。
典型用法
QQuickWidget *view = new QQuickWidget; view->setSource(QUrl::fromLocalFile("myqmlfile.qml")); view->show();
要接收与QQuickWidget加载和执行QML相关的问题，您可以连接到statusChanged() 信号并监控QQuickWidget::Error。错误可以通过QQuickWidget::errors获取。
QQuickWidget还管理视图和根对象的尺寸。默认情况下，resizeMode 是 SizeViewToRootObject，这将加载组件并将其调整到视图的大小。或者，可以将 resizeMode 设置为 SizeRootObjectToView，这将调整视图的大小以匹配根对象。
性能考虑
QQuickWidget是使用QQuickView和QWidget::createWindowContainer()的替代品。堆叠顺序的限制不适用，这使得QQuickWidget成为更灵活的替代品，其行为更像是一个普通的小部件。
但是，上述优势是以性能为代价的
- 与QQuickWindow和QQuickView不同，QQuickWidget包含至少一个渲染过程，目标是在离屏颜色缓冲区（通常是一个2D纹理）上，然后绘制一个纹理四边形。这意味着对GPU碎片处理增加了负担。
- 使用QQuickWidget会在所有平台上禁用线程渲染循环。这意味着一些线程渲染的优点，例如Animator类和vsync驱动的动画，将无法使用。
注意：请勿在QQuickWidget上调用winId()。此函数会触发原生窗口的创建，导致性能下降以及可能的渲染故障。QQuickWidget的整个目的是在不使用单独的原生窗口的情况下渲染Quick场景，因此始终应避免将其作为原生小部件使用。
图形API支持
QQuickWidget与Qt Quick支持的3D图形API以及软件后端兼容。然而，例如OpenVG等其它后端并不兼容，尝试构建QQuickWidget会导致问题。
覆盖平台的默认图形API的方式与QQuickWindow和QQuickView相同：或者在构建第一个QQuickWidget之前提前调用QQuickWindow::setGraphicsApi()，或者通过设置QSG_RHI_BACKEND环境变量。
注意：顶级窗口只能使用一个图形API进行渲染。例如，在同一个顶级窗口的小部件层次结构中尝试放置使用Vulkan的QQuickWidget和QOpenGLWidget，将发生问题，且其中的一个小部件将无法按照预期渲染。
场景图和上下文持久性
QQuickWidget遵守QQuickWindow::isPersistentSceneGraph，这意味着应用程序可以通过在从quickWindow()函数返回的窗口上调用QQuickWindow::setPersistentSceneGraph()来决定何时释放场景图节点和其他与Qt Quick场景相关的资源。默认情况下，持久性是启用的，就像QQuickWindow一样。
当使用OpenGL时，QQuickWindow还提供禁用持久OpenGL上下文的可能性。当前此设置被QQuickWidget忽略，上下文始终持久。因此，当隐藏小部件时上下文不会被销毁。上下文仅在销毁小部件或小部件被移至另一个顶层小部件的子层次结构中时销毁。然而，一些应用程序，特别是在Qt Quick场景中执行自定义OpenGL渲染并且拥有自己的图形资源的应用程序，可能希望禁用后者，因为它们可能没有准备处理将QQuickWidget移到另一个窗口时上下文丢失的情况。这类应用程序可以设置QCoreApplication::AA_ShareOpenGLContexts属性。有关资源初始化和清理的详细讨论，请参阅QOpenGLWidget文档。
注意：与QOpenGLWidget相比，QQuickWidget对其内部OpenGL上下文控制的粒度更低，并且存在细微的差异，最重要的是，即使启用了QCoreApplication::AA_ShareOpenGLContexts，禁用持久场景图也将导致在窗口更改时销毁上下文。
限制
将其他小部件放在下面并使 QQuickWidget 透明化不会得到预期的结果：下面的小部件将不可见。这是因为在实践中 QQuickWidget 总是在所有其他常规（非OpenGL）小部件之前绘制，因此不透明类型的解决方案是不可行的。其他类型的布局，例如在小部件上方放置 QQuickWidget，会按预期工作。
如果绝对必要，可以通过设置 QQuickWidget 上的 Qt::WA_AlwaysStackOnTop 属性来克服这种限制。但请注意，这将破坏堆叠顺序。例如，将无法在 QQuickWidget 上面放置其他小部件，因此它应仅在需要带有其他小部件可见的下部半透明 QQuickWidget 的场合使用。
此限制仅在 QQuickWidget 内有其他小部件且处于同一窗口的情况下适用。以传统方式使窗口半透明，其他应用程序和桌面在背景中可见：在顶层窗口上设置 Qt::WA_TranslucentBackground，请求一个 Alpha 通道，并通过 setClearColor() 将 Qt Quick Scenegraph 的清除颜色更改为 Qt::transparent。
Tab 键处理
当按下 [TAB] 键时，QQuickWidget 内的项目会获得焦点。如果此项目可以处理 [TAB] 键的按下，焦点将相应地在该项目内更改，否则下一个具有焦点的 widget 会获得焦点。
参见将 C++ 类型的属性公开给 QML，Qt Quick Widgets 示例，和 QQuickView。
成员类型文档
enum QQuickWidget::ResizeMode
此枚举指定如何调整视图大小。
| 常量 | 值 | 描述 |
|---|---|---|
QQuickWidget::SizeViewToRootObject | 0 | 视图根据 QML 中的根项目调整大小。 |
QQuickWidget::SizeRootObjectToView | 1 | 视图将自动将根项目调整到视图大小。 |
enum QQuickWidget::Status
指定 QQuickWidget 的加载状态。
| 常量 | 值 | 描述 |
|---|---|---|
QQuickWidget::Null | 0 | 此 QQuickWidget 没有设置源。 |
QQuickWidget::Ready | 1 | 此 QQuickWidget 已加载并创建了 QML 组件。 |
QQuickWidget::Loading | 2 | 此 QQuickWidget 正在加载网络数据。 |
QQuickWidget::Error | 3 | 发生了一个或多个错误。调用 errors() 获取错误列表。 |
属性文档
resizeMode : ResizeMode
确定视图是否应调整窗口内容的大小。
如果此属性设置为 SizeViewToRootObject（默认值），则视图将调整大小以匹配 QML 中的根项的大小。
如果此属性设置为 SizeRootObjectToView，视图将自动将根项目调整到视图大小。
不管这个属性如何，视图的大小提示是根项的初始大小。请注意，由于 QML 可能会动态加载，该大小可能会更改。
访问函数
| QQuickWidget::ResizeMode | resizeMode() const |
| void | setResizeMode(QQuickWidget::ResizeMode) |
另请参阅initialSize。
source : QUrl
此属性持有 QML 组件源的 URL。
确保提供的URL完整且正确，特别是当从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。
注意：设置源URL将导致QML组件被实例化，即使URL值未更改。
访问函数
[只读] 状态 : const 状态
组件的当前状态。
访问函数
| QQuickWidget::Status | 状态() const |
通知器信号
| void | statusChanged(QQuickWidget::状态 状态) |
成员函数说明
[明确] QQuickWidget::QQuickWidget(QWidget *parent = nullptr)
构造一个QQuickWidget，将其默认QML引擎作为parent的孩子。
parent的默认值为nullptr。
QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)
构造一个带有给定QMLengine的QQuickWidget，作为parent的孩子。
注意：QQuickWidget不会获取给定的engine对象的所有权；销毁引擎是调用者的责任。如果在视图中删除了engine，则状态()将返回QQuickWidget::Error。
[明确] QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)
使用默认QML引擎和给定的QMLsource构造一个QQuickWidget，将其作为parent的孩子。
parent的默认值为nullptr。
[覆盖虚函数 noexcept] QQuickWidget::~QQuickWidget()
销毁QQuickWidget。
[覆盖保护虚函数] void QQuickWidget::dragEnterEvent(QDragEnterEvent *e)
重实现了：QWidget::dragEnterEvent(QDragEnterEvent *event)。
[覆盖保护虚函数] void QQuickWidget::dragLeaveEvent(QDragLeaveEvent *e)
重实现了：QWidget::dragLeaveEvent(QDragLeaveEvent *event)。
[覆盖保护虚函数] void QQuickWidget::dragMoveEvent(QDragMoveEvent *e)
重实现了：QWidget::dragMoveEvent(QDragMoveEvent *event)。
[覆盖保护虚函数] void QQuickWidget::dropEvent(QDropEvent *e)
重实现了：QWidget::dropEvent(QDropEvent *event)。
QQmlEngine *QQuickWidget::engine() const
返回用于实例化QML组件所使用的QQmlEngine指针。
QList<QQmlError> QQuickWidget::errors() const
返回上一次编译或创建操作中发生的错误列表。当状态不是Error时，返回空列表。
另请参阅 status。
[覆盖虚受保护] bool QQuickWidget::event(QEvent *e)
重实现了: QWidget::event(QEvent *event)。
[覆盖虚受保护] void QQuickWidget::focusInEvent(QFocusEvent *event)
重实现了: QWidget::focusInEvent(QFocusEvent *event)。
[覆盖虚受保护] bool QQuickWidget::focusNextPrevChild(bool next)
重实现了: QWidget::focusNextPrevChild(bool next)。
[覆盖虚受保护] void QQuickWidget::focusOutEvent(QFocusEvent *event)
重实现了: QWidget::focusOutEvent(QFocusEvent *event)。
QSurfaceFormat QQuickWidget::format() const
返回实际的外观格式。
如果小部件尚未显示，则返回请求的格式。
另请参阅 setFormat。
QImage QQuickWidget::grabFramebuffer() const
渲染一个帧并将其读取回一个图像。
注意: 这是一个可能开销较大的操作。
[覆盖虚受保护] void QQuickWidget::hideEvent(QHideEvent *)
重实现了: QWidget::hideEvent(QHideEvent *event)。
QSize QQuickWidget::initialSize() const
返回根对象初始大小。
如果resizeMode是SizeRootObjectToView，则根对象将根据视图大小进行调整。此函数返回调整大小前的根对象大小。
[覆盖虚受保护] void QQuickWidget::keyPressEvent(QKeyEvent *e)
重实现了: QWidget::keyPressEvent(QKeyEvent *event)。
[重写虚保护] void QQuickWidget::keyReleaseEvent(QKeyEvent *e)
重新实现: QWidget::keyReleaseEvent(QKeyEvent *event).
[重写虚保护] void QQuickWidget::mouseDoubleClickEvent(QMouseEvent *e)
重新实现: QWidget::mouseDoubleClickEvent(QMouseEvent *event).
[重写虚保护] void QQuickWidget::mouseMoveEvent(QMouseEvent *e)
重新实现: QWidget::mouseMoveEvent(QMouseEvent *event).
[重写虚保护] void QQuickWidget::mousePressEvent(QMouseEvent *e)
重新实现: QWidget::mousePressEvent(QMouseEvent *event).
[重写虚保护] void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)
重新实现: QWidget::mouseReleaseEvent(QMouseEvent *event).
[重写虚保护] void QQuickWidget::paintEvent(QPaintEvent *event)
重新实现: QWidget::paintEvent(QPaintEvent *event).
QQuickWindow *QQuickWidget::quickWindow() const
返回该小部件用于驱动 Qt Quick 渲染的离屏 QQuickWindow。如果您想要使用当前不通过 QQuickWidget 暴露的 QQuickWindow API，此功能很有用，例如连接到 QQuickWindow::beforeRendering() 信号以在 Qt Quick 自身渲染下面绘制原生的 OpenGL 内容。
警告：谨慎使用此函数的返回值。尤其是永远不要尝试显示 QQuickWindow，并且在使用其他仅支持 QWindow 的 API 时非常小心。
警告：在 QQuickWidget 的生命周期中，离屏窗口可能被删除（并重新创建），特别是在小部件被移动到另一个 QQuickWindow 时。如果您需要知道何时窗口被替换，请连接到其 destroyed() 信号。
QQmlContext *QQuickWidget::rootContext() const
此函数返回上下文层次结构的根。每个 QML 组件都在一个 QQmlContext 中实例化。上下文对于将数据传递给 QML 组件是必不可少的。在 QML 中，上下文是按层次结构组织的，而此层次结构由 QQmlEngine 管理。
QQuickItem *QQuickWidget::rootObject() const
返回视图的根 item。如果调用过setSource() 且参数错误或有错误代码，或者在创建QtQuick内容时，该值可能为null。
[信号] void QQuickWidget::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)
在场景图初始化过程中发生错误时，会发出此信号。
如果应用程序希望以自定义方式处理错误（如OpenGL上下文创建失败），则应将此信号连接到槽。如果没有槽连接到信号，则行为将不同：Quick将打印消息或显示消息框，然后终止应用程序。
此信号将在GUI线程中发出。
另请参阅QQuickWindow::sceneGraphError。
void QQuickWidget::setClearColor(const QColor &color)
设置清除颜色。默认情况下，这是一个不透明颜色。
要获取半透明QQuickWidget，调用此函数并将颜色设置为Qt::transparent，设置顶层窗口的Qt::WA_TranslucentBackground小部件属性，并通过setFormat()请求alpha通道。
void QQuickWidget::setFormat(const QSurfaceFormat &format)
为小部件使用的上下文和离屏表面设置表面格式。
在需要为给定的OpenGL版本或配置请求上下文时调用此函数。将自动处理深度、模板和alpha缓冲区的大小，无需显式请求它们。
另请参阅QWindow::setFormat()、QWindow::format和format。
[槽] void QQuickWidget::setSource(const QUrl &url)
设置到url的源，加载QML组件并将其实例化。
确保提供的URL完整且正确，特别是当从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。
使用相同的URL多次调用此方法会导致QML组件被重新实例化。
注意：属性source的设置器函数。
另请参阅source。
[重写虚受保护] void QQuickWidget::showEvent(QShowEvent *)
重新实现：QWidget::showEvent(QShowEvent *event)。
QUrl QQuickWidget::source() const
如果已设置，返回源URL。
注意：属性source的获取器函数。
另请参阅setSource。
[信号] void QQuickWidget::statusChanged(QQuickWidget::Status status)
当组件的当前状态发生改变时，会发出此信号。
注意：属性状态的通知器信号。
[重写虚保护] void QQuickWidget::wheelEvent(QWheelEvent *e)
重写：QWidget::wheelEvent(QWheelEvent *event).
© 2024 Qt公司。本文件中的文档贡献是有版权的，归各自所有者所有。所提供的文档根据自由软件基金会发布的GNU自由文档许可版本1.3的条款使用许可。Qt和相应的标志是芬兰及其它国家的Qt公司商标。所有其他商标均为各自所有者的财产。
