PySide6.QtQuickWidgets.QQuickWidget¶

class QQuickWidget¶

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

概要¶

属性¶

resizeModeᅟ - 确定视图是否应调整窗口内容的大小
sourceᅟ - QML组件的源URL
statusᅟ

注意

本文档可能包含从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加载和执行QML相关的错误，您可以连接到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 支持的所有 3D 图形 API 以及 software 后端一起使用。然而，其他后端（例如 OpenVG）不兼容，尝试构建 QQuickWidget 会导致问题。

覆盖平台的默认图形API的方式与QQuickWindow和QQuickView相同：要么在构建第一个QQuickWidget之前尽早调用setGraphicsApi()，要么设置QSG_RHI_BACKEND环境变量。

注意

一个顶级窗口只能使用一个图形API进行渲染。例如，尝试在同一个顶级窗口的小部件层次结构中放置一个使用Vulkan的QQuickWidget和一个QOpenGLWidget，将会出现问题，其中一个部件将无法按预期渲染。

场景图和上下文持久性¶

QQuickWidget 遵循 isPersistentSceneGraph()，这意味着应用程序可以通过在从 quickWindow() 函数返回的窗口上调用 setPersistentSceneGraph() 来决定是否在小部件隐藏时释放场景图节点和其他与 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的清除颜色更改为Qt::transparent。

Tab键处理¶

按下[TAB]键时，QQuickWidget内的项目会获得焦点。如果该项目能够处理[TAB]键按下，焦点将在项目内相应改变，否则焦点链中的下一个部件将获得焦点。

另请参阅

Qt Quick 小部件示例 QQuickView

class ResizeMode¶

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

常量

描述

QQuickWidget.SizeViewToRootObject

视图会随着QML中的根项目调整大小。

QQuickWidget.SizeRootObjectToView

视图将自动调整根项目的大小以适应视图的大小。

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

class Status¶

指定QQuickWidget的加载状态。

常量

描述

QQuickWidget.Null

这个 QQuickWidget 没有设置源。

QQuickWidget.Ready

这个 QQuickWidget 已经加载并创建了 QML 组件。

QQuickWidget.Loading

这个 QQuickWidget 正在加载网络数据。

QQuickWidget.Error

发生了一个或多个错误。调用 errors() 以检索错误列表。

常量	描述
QQuickWidget.Null	这个 `QQuickWidget` 没有设置源。
QQuickWidget.Ready	这个 `QQuickWidget` 已经加载并创建了 QML 组件。
QQuickWidget.Loading	这个 `QQuickWidget` 正在加载网络数据。
QQuickWidget.Error	发生了一个或多个错误。调用 `errors()` 以检索错误列表。

注意

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

property resizeModeᅟ: QQuickWidget.ResizeMode¶

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

如果此属性设置为 SizeViewToRootObject（默认值），视图将调整为 QML 中根项目的大小。

如果此属性设置为 SizeRootObjectToView，视图将自动调整根项目的大小以适应视图的大小。

无论此属性如何，视图的 sizeHint 是根项目的初始大小。但请注意，由于 QML 可能会动态加载，该大小可能会发生变化。

另请参阅

initialSize()

Access functions:

resizeMode()
setResizeMode()

property sourceᅟ: QUrl¶

此属性保存QML组件源的URL。

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

注意

设置源URL将导致QML组件被实例化，即使URL与当前值相比没有变化。

Access functions:

source()
setSource()

property statusᅟ: QQuickWidget.Status¶

组件的当前status。

Access functions:

status()
信号 statusChanged()

__init__([parent=None])¶

Parameters:: 父级 – QWidget

构造一个QQuickWidget，使用默认的QML引擎作为parent的子对象。

parent的默认值是nullptr。

__init__(engine, parent)

Parameters:

engine – QQmlEngine
parent – QWidget

使用给定的QML engine作为parent的子项构造一个QQuickWidget。

注意

QQuickWidget 不会接管给定的 engine 对象的所有权；销毁引擎是调用者的责任。如果 engine 在视图之前被删除，status() 将返回 Error。

__init__(source[, parent=None])

Parameters:

source – QUrl
parent – QWidget

使用默认的QML引擎和给定的QML source作为parent的子项构造一个QQuickWidget。

parent 的默认值是 nullptr。

engine()¶

Return type:: QQmlEngine

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

errors()¶

Return type:: QQmlError的列表

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

另请参阅

status

format()¶

Return type:: QSurfaceFormat

返回实际的表面格式。

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

另请参阅

setFormat()

grabFramebuffer()¶

Return type:: QImage

渲染一个帧并将其读回为图像。

注意

这是一个可能代价高昂的操作。

initialSize()¶

Return type:: QSize

返回根对象的初始大小。

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

quickWindow()¶

Return type:: QQuickWindow

返回此小部件用于驱动Qt Quick渲染的离屏QQuickWindow。如果您想使用QQuickWidget当前未公开的QQuickWindow API，例如连接到beforeRendering()信号以便在Qt Quick自己的渲染下方绘制原生OpenGL内容，这将非常有用。

警告

请谨慎使用此函数的返回值。特别是，切勿尝试显示QQuickWindow，并且在使用其他仅限QWindow的API时要非常小心。

警告

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

resizeMode()¶

Return type:: ResizeMode

另请参阅

setResizeMode()

属性 resizeModeᅟ 的获取器。

rootContext()¶

Return type:: QQmlContext

此函数返回上下文层次结构的根。每个QML组件都在QQmlContext中实例化。QQmlContext对于将数据传递给QML组件至关重要。在QML中，上下文按层次结构排列，此层次结构由QQmlEngine管理。

rootObject()¶

Return type:: QQuickItem

返回视图的根item。当setSource()未被调用时，如果调用时使用了损坏的QtQuick代码或在QtQuick内容正在创建时，可能为null。

sceneGraphError(error, message)¶

Parameters:

错误 – SceneGraphError
message – str

当场景图初始化期间发生error时，会发出此信号。

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

此信号将从GUI线程发出。

另请参阅

sceneGraphError()

setClearColor(color)¶

Parameters:: 颜色 – QColor

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

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

另请参阅

setColor()

setContent(url, component, item)¶

Parameters:

url – QUrl
组件 – QQmlComponent
项目 – QObject

setFormat(format)¶

Parameters:: 格式 – QSurfaceFormat

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

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

另请参阅

format()

setResizeMode(arg__1)¶

Parameters:: arg__1 – ResizeMode

另请参阅

resizeMode()

属性 resizeModeᅟ 的设置器。

setSource(url)¶

Parameters:: url – QUrl

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

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

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

另请参阅

source()

属性 sourceᅟ 的设置器。

source()¶

Return type:: QUrl

如果设置了，返回源URL。

另请参阅

setSource()

属性 sourceᅟ 的获取器。

status()¶

Return type:: 状态

属性 statusᅟ 的获取器。

statusChanged(status)¶

Parameters:: 状态 – Status

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

属性 statusᅟ 的通知信号。

PySide6.QtQuickWidgets.QQuickWidget¶

概要¶

属性¶

方法¶

插槽¶

信号¶

详细描述¶

性能考虑¶

图形API支持¶

场景图和上下文持久性¶

限制¶

Tab键处理¶