class QQuickWidget

QQuickWidget类提供了一个用于显示Qt Quick用户界面的小部件。更多信息...

继承自： QAbstract3DGraph、Q3DSurface、Q3DScatter、Q3DBars

概述

属性

• resizeMode - 确定视图是否应该调整窗口内容的大小

• source - QML组件源的URL

• 状态

方法

• def __init__()

• def engine()

• errors() 方法

• format() 方法

• grabFramebuffer() 方法

• initialSize() 方法

• quickWindow() 方法

• resizeMode() 方法

• rootContext() 方法

• rootObject() 方法

• setClearColor() 方法

• setFormat() 方法

• setResizeMode() 方法

• source() 方法

• status() 方法

Slots

• setContent() 方法

• setSource() 方法

Signals

• sceneGraphError() 信号

• statusChanged() 信号

注意

此文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来告知我们。

详细描述

这是一个对 `QQuickWindow` 的便捷封装，它会在收到主源文件URL时自动加载并显示QML场景。或者，您可以使用《QQmlComponent》实例化自己的对象，并将它们放置在手动设置的《QQuickWidget` 中。

典型用法

QQuickWidget *view = new QQuickWidget;
view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
view->show();

要接收与《QQuickWidget` 相关的加载和执行错误，您可以连接到《statusChanged()` 信号，并监视《Error`。错误可以通过《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 所支持的图形API一起使用，也可与 软件 后端一起使用。但其他后端，例如 OpenVG，则不兼容。尝试构造 QQuickWidget 会导致问题。

覆盖平台的默认图形API的方法与 QQuickWindow 和 QQuickView 相同：或者通过在构造第一个 QQuickWidget 之前调用 setGraphicsApi() 处理，或者通过设置 QSG_RHI_BACKEND 环境变量。

注意

一个顶层窗口只能为渲染使用一个单一的图形API。例如，尝试在顶层窗口的小部件层次结构中放置使用 Vulkan 的 QQuickWidget 并同时有一个 QOpenGLWidget，将发生问题，并且其中一个小部件的渲染可能不会如预期那样进行。

场景图和上下文持久性

QQuickWidget 遵循 isPersistentSceneGraph() ，这意味着应用可以通过调用从 quickWindow() 函数返回的窗口上的 setPersistentSceneGraph() ，来决定在部件隐藏时是否释放 scenegraph 节点和其他 Qt Quick 场景相关资源。默认情况下启用持久性，就像 QQuickWindow 一样。

当使用 OpenGL 运行时，QQuickWindow 提供了禁用持久 OpenGL 上下文的可能性。此设置目前被 QQuickWidget 忽略，上下文始终是持久的。因此，在隐藏窗口时不会销毁 OpenGL 上下文。上下文仅在销毁部件或部件被移入另一个顶层窗口的子层次结构时才会被销毁。但是，一些应用程序，特别是那些在 Qt Quick 场景中执行自定义 OpenGL 渲染并拥有自己的图形资源的应用程序，可能希望禁用后一种情况，因为它们可能没有准备好处理在将 QQuickWidget 移入另一个窗口时上下文丢失的情况。此类应用程序可以设置 QCoreApplication::AA_ShareOpenGLContexts 属性。有关资源初始化和清理的详细信息，请参阅 QOpenGLWidget 文档。

注意

QQuickWidget 对其内部 OpenGL 上下文控制不如 QOpenGLWidget 细粒度，存在细微差别，最值得注意的是，禁用持久的场景图将导致在窗口更改时销毁上下文，无论 QCoreApplication::AA_ShareOpenGLContexts 是否存在。

限制

将其他部件置于下方并使 QQuickWidget 透明不会产生预期的结果：下方的部件将不可见。这是因为实际上，QQuickWidget 在所有其他常规、非 OpenGL 部件之前被绘制，因此透明的解决方案不可行。其他类型的布局，如将部件置于 QQuickWidget 上，将按预期工作。

在绝对必要时，可以通过设置QQuickWidget的Qt::WA_AlwaysStackOnTop属性来克服此限制。注意，这将破坏堆栈顺序。例如，将无法在其他小部件之上放置QQuickWidget，因此它仅在需要具有半透明度并且下方可见其他小部件的QQuickWidget的情况下使用。

此限制仅适用于在同一窗口内部具有QQuickWidget的情况，并且下方有其他小部件。使窗口半透明，在背景中显示其他应用程序和桌面，可以采用传统方式：在顶层窗口上设置Qt::WA_TranslucentBackground，请求一个alpha通道，并通过setClearColor()将Qt Quick Scenegraph的clear颜色设置为Qt::transparent 。

Tab键处理

当按下键时，QQuickWidget内的项目将获得焦点。如果此项目可以处理键的按下，则焦点将相应地在项目内更改，否则下一个在焦点链中的小部件将获得焦点。

另请参阅

Qt Quick Widgets 示例 QQuickView

class ResizeMode

此枚举指定如何调整视图的大小。

常量	描述
QQuickWidget.SizeViewToRootObject	视图随着QML中的根项目而调整大小。
QQuickWidget.SizeRootObjectToView	视图将自动调整根项目的大小以匹配视图大小。

class Status

指定QQuickWidget的加载状态。

常量	描述
QQuickWidget.Null	此QQuickWidget没有设置资源。
QQuickWidget.Ready	此QQuickWidget已加载并创建了QML组件。
QQuickWidget.Loading	此QQuickWidget正在加载网络数据。
QQuickWidget.Error	发生了一个或多个错误。通过调用errors()获取错误列表。

注意

当使用 from __feature__ import true_property 时，可以直接使用属性；否则，可以通过访问器函数来使用。

属性resizeMode: QQuickWidget.ResizeMode

该属性决定视图是否应该调整窗口内容的大小。

如果将该属性设置为 SizeViewToRootObject（默认值），视图会调整大小以匹配 QML 中根项的大小。

如果将该属性设置为 SizeRootObjectToView，视图将自动调整根项的大小以匹配视图的大小。

不管这个属性如何设置，视图的 sizeHint 是根项的初始大小。请注意，由于 QML 可能动态加载，这个大小可能会发生变化。

另请参阅

initialSize()

访问函数

• resizeMode()

• setResizeMode()

属性source: QUrl

该属性包含 QML 组件源 URL。

请确保提供的 URL 是完整且正确的，特别是当从本地文件系统加载文件时，请使用 QUrl::fromLocalFile()。

注意

设置源 URL 将导致实例化 QML 组件，即使 URL 与当前值未更改。

访问函数

• source()

• setSource()

属性status: QQuickWidget.Status

组件当前的 status。

访问函数

• status()

• 信号 statusChanged()

__init__([parent=None])

参数：

parent - QWidget

使用给定的 parent 构造一个 QQuickWidget。默认的 parent 值为 0。

__init__(source[, parent=None])

参数：

• source – QUrl

• parent - QWidget

使用指定的 QML source 和 parent 构造一个 QQuickWidget。默认的 parent 值为 0。

__init__(engine, parent)

参数：

• engine – QQmlEngine

• parent - QWidget

使用指定的 QML engine 和 parent 构造一个 QQuickWidget。

注意：在这种情况下，QQuickWidget 不拥有给定的 engine 对象；销毁引擎的责任在于调用者。如果在视图之前删除了引擎，status() 将返回 Error。

另请参阅

Status status() errors()

engine()

返回类型：:

QQmlEngine

返回用于实例化 QML 组件的 QQmlEngine 指针。

errors()

返回类型：:

返回类型：:

QQmlError

另请参阅

返回在上一个编译或创建操作中发生的错误列表。当状态不是 Error 时，返回空列表。

format()

返回类型：:

QSurfaceFormat

返回实际表面格式。

如果小部件尚未显示，则返回请求的格式。

另请参阅

setFormat()

grabFramebuffer()

返回类型：:

QImage

渲染一个帧并将其读入图像中。

注意

这是一个可能昂贵的操作。

initialSize()

返回类型：:

QSize

返回根对象初始大小。

如果 resizeMode 是 SizeRootObjectToView，则根对象将被调整大小以匹配视图大小。此函数返回调整大小之前根对象的大小。

quickWindow()

返回类型：:

QQuickWindow

返回由这个小部件用于驱动 Qt Quick 渲染的离屏 QQuickWindow。如果您想使用 QQuickWindow API 而这些 API 目前未由 QQuickWidget 暴露，这将很有用，例如连接到 beforeRendering() 信号以在 Qt Quick 自身渲染下绘制本机 OpenGL 内容。

警告

请谨慎使用此函数的返回值。特别是永远不会尝试显示 QQuickWindow，并且在使用其他仅适用于 QWindow 的 API 时非常小心。

警告

在 QQuickWidget 的生命周期内，离屏窗口可能会被删除（并重新创建），尤其是在小部件移动到另一个 QQuickWindow 时。如果您需要知道何时已替换了窗口，请连接到其 destroyed() 信号。

resizeMode()

返回类型：:

ResizeMode

另请参阅

setResizeMode()

属性 resizeMode 的获取器。

rootContext()

返回类型：:

QQmlContext

此函数返回上下文层次结构的根。每个 QML 组件都在一个 QQmlContext 中实例化。QQmlContext 对于向 QML 组件传递数据非常重要。在 QML 中，上下文是按层次结构排列的，并且由 QQmlEngine 管理此层次结构。

rootObject()

返回类型：:

QQuickItem

返回视图的根item。当调用setSource()时未执行，或者使用有错误的QtQuick代码，或者正在创建QtQuick内容时，它可以返回null。

场景图错误(error, message)

参数：

• 错误 – SceneGraphError

• 信息 – str

当在场景图初始化过程中发生错误时，会发出此信号。

如果应用程序希望以自定义方式处理错误，例如处理OpenGL上下文创建失败，则应连接到该信号。如果没有槽连接到该信号，则行为将不同：Quick会打印信息，或者显示消息框，并中止应用程序。

此信号将在GUI线程中发出。

另请参阅

场景图错误()

setClearColor(color)

参数：

颜色 – QColor

设置清除颜色。默认情况下这为一个不透明的颜色。

为了得到一个半透明的QQuickWidget，调用此函数并将color设置为Qt::transparent，将Qt::WA_TranslucentBackground窗口属性设置在顶层窗口上，并通过setFormat()请求Alpha通道。

另请参阅

设置颜色()

setContent(url, component, item)

参数：

• URL – QUrl

• 组件 – QQmlComponent

• 项目 – QObject

setFormat(format)

参数：

格式 – QSurfaceFormat

设置此小部件所用的上下文和离屏表面使用的 format。

当需要请求特定 OpenGL 版本或配置的上下文时，调用此函数。深度、模板和 alpha 缓冲区的大小将自动处理，无需明确请求。

另请参阅

format()

setResizeMode(arg__1)

参数：

arg__1 – ResizeMode

另请参阅

resizeMode()

设置 resizeMode 属性的值。

setSource(arg__1)

参数：

arg__1 – QUrl

将源设置为 url，加载 QML 组件并实例化它。

请确保提供的 URL 是完整且正确的，特别是当从本地文件系统加载文件时，请使用 QUrl::fromLocalFile()。

使用相同的 URL 多次调用此方法将导致 QML 组件被重新实例化。

另请参阅

source()

设置 source 属性的值。

source()

返回类型：:

QUrl

如果设置了，则返回源 URL。

另请参阅

setSource()

获取 source 属性的值。

status()

返回类型：:

状态

获取 status 属性的值。

statusChanged(arg__1)

参数：

arg__1 – Status

当组件的当前 status 发生变化时，将发出此信号。

属性 status 的通知信号。