class QGraphicsScene#

QGraphicsScene 类提供了一个用于管理大量 2D 图形项的表面。 更多...

Inheritance diagram of PySide6.QtWidgets.QGraphicsScene

概要#

属性#

方法#

虚方法#

槽函数#

信号#

注意

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

详细说明#

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

此类用作QGraphicsItems的容器。它通常与 QGraphicsView 一起使用，用于在2D平面上可视化图形项，例如线条、矩形、文本，甚至自定义项。 QGraphicsScene 是 Graphics View Framework 的一部分。

QGraphicsScene 还提供功能，让您高效地确定项的位置，以及在场景中的任意区域可见的项。通过 QGraphicsView 小部件，您可以可视化整个场景，或者放大查看场景的某部分。

示例

scene = QGraphicsScene()
scene.addText("Hello, world!")
view = QGraphicsView(scene)
view.show()

请注意，QGraphicsScene 没有自己可见的外观；它仅管理项。您需要创建一个 QGraphicsView 小部件来可视化场景。

要将项目添加到场景中，您首先需要构造一个 QGraphicsScene 对象。然后，您有两个选择：一是通过调用 addItem() 将现有的 QGraphicsItem 对象添加到场景中，或者调用便利函数之一，如 addEllipse() ， addLine() ， addPath() ， addPixmap() ， addPolygon() ， addRect() 或 addText() ，所有这些函数都返回新添加的项目指针。这些函数添加的项目的尺寸相对于项目的坐标系，并且在场景中初始化项目的位置为 (0, 0)。

然后，您可以使用 QGraphicsView 可视化场景。当场景发生变化时（例如，当项目移动或变换时），QGraphicsScene 会发出 changed() 信号。要删除一个项目，调用 removeItem() 。

QGraphicsScene 使用索引算法有效地管理项目的位置。默认情况下，使用 BSP（二叉空间分割）树；这是一种适用于大型场景的算法，其中大多数项目保持静态（即不移动）。您可以通过调用 setItemIndexMethod() 来选择禁用此索引。有关可用的索引算法的更多信息，请参阅 itemIndexMethod 属性。

场景的边界矩形是通过调用 setSceneRect() 来设置的。可以将在场景的任意位置放置项，并且场景的大小默认是无限大的。场景矩形仅用于内部簿记，用于保持场景项索引。如果场景矩形未设置，QGraphicsScene 将使用itemsBoundingRect() 返回的所有项的边界区域作为场景矩形。然而，itemsBoundingRect() 是一个相对耗时的函数，因为它需要对场景上的每个项收集位置信息。因此，在处理大型场景时，应始终设置场景矩形。

QGraphicsScene 最强的功能之一是能够高效地确定项的位置。即使在场景上有数百万个项，items() 函数也可以在几毫秒内确定项的位置。有几种items() 的重载：一种是找到某个位置的项，一种是找到在多边形或矩形内或与其相交的项，等等。返回的项列表按堆叠顺序排序，最上面的项是列表中的第一项。为了方便，还有一个itemAt() 函数，它返回给定位置的顶层项。

QGraphicsScene 维护场景的选择信息。要选择项，请调用 setSelectionArea() ，要清除当前选择，请调用 clearSelection() 。通过调用 selectedItems() 获取所有选中项的列表。

事件处理和传播#

QGraphicsScene 还有一个职责，就是将 QGraphicsView 发生的事件传播出去。要向场景发送事件，你需要构建一个继承自 QEvent 的事件，然后使用，例如，QCoreApplication::sendEvent() 来发送它。event() 负责将事件分发给各个项目。一些常用的事件由便利的事件处理器来处理。例如，按键事件由 keyPressEvent() 处理，而鼠标按键事件由 mousePressEvent() 处理。

按键事件会被发送到 焦点项目。要设置焦点项目，你可以调用 setFocusItem() 并传入一个可以接受焦点的项目，或者项目本身可以调用 setFocus() 。调用 focusItem() 来获取当前焦点项目。为了与控件兼容，场景也维护了自己的焦点信息。默认情况下，场景没有焦点，所有按键事件都被丢弃。如果调用 setFocus()，或者场景上的项目获取了焦点，场景将自动获得焦点。如果场景有焦点，hasFocus() 将返回 true，如果有焦点项目，则按键事件将被转发到该项目。如果场景失去焦点（即某人调用 clearFocus()），而一个项目有焦点，场景将保持其项目焦点信息，并且一旦场景恢复焦点，将确保最后焦点项目重新获得焦点。

对于鼠标悬停效果，QGraphicsScene 分发 悬停事件。如果一个项目接受悬停事件（参见 acceptHoverEvents()），当鼠标进入其区域时，它将收到 GraphicsSceneHoverEnter 事件。当鼠标继续在项目区域内部移动时，QGraphicsScene 将发送 GraphicsSceneHoverMove 事件。当鼠标离开项目区域时，该项目将收到 GraphicsSceneHoverLeave 事件。

所有鼠标事件都传递给当前的 鼠标捕获器 项目。一个项目成为场景的鼠标捕获器，如果它接受鼠标事件（参见 acceptedMouseButtons() ）并且它接收到鼠标按下。在没有其他鼠标按钮按下的情况下接收鼠标释放时，它保持鼠标捕获器的状态。您可以通过调用 mouseGrabberItem() 来确定当前哪个项目正在捕获鼠标。

classItemIndexMethod#

此枚举描述了 QGraphicsScene 为管理场景中项目位置信息提供索引算法。

常量

描述

QGraphicsScene.BspTreeIndex

应用二叉空间分割树。所有 QGraphicsScene 的项目位置算法都是接近对数复杂度的，通过使用二分搜索。添加、移动和删除项目是逻辑的。这种方法最适合静态场景（即，大多数项目不移动的场景）。

QGraphicsScene.NoIndex

不应用索引。项目位置是线性的，因为搜索场景上的所有项目。然而，添加、移动和删除项目却是在常量时间内完成的。这种方法最适合动态场景，其中不断添加、移动或删除许多项目。

另请参阅

setItemIndexMethod() bspTreeDepth

classSceneLayer#

(继承自 enum.Flag) 此枚举描述了 QGraphicsScene 中的渲染层。当 QGraphicsScene 绘制场景内容时，它按顺序单独渲染这些层。

每个层代表一个在调用如 invalidate() 或 invalidateScene() 等函数时可以进行逻辑或操作的标志。

常量

描述

QGraphicsScene.ItemLayer

物品层。通过调用虚函数drawItems()，QGraphicsScene 在此层渲染所有物品。物品层在背景层之后、前景层之前被绘制。

QGraphicsScene.BackgroundLayer

背景层。QGraphicsScene 通过调用虚函数drawBackground() 在此层渲染场景的背景。背景层是所有层中首先绘制的。

QGraphicsScene.ForegroundLayer

前景层。QGraphicsScene 通过调用虚函数drawForeground() 在此层渲染场景的前景。前景层是所有层中最后绘制的。

QGraphicsScene.AllLayers

所有层；该值代表所有三层的组合。

另请参阅

invalidate() invalidateScene()

注意

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

属性backgroundBrush: QBrush#

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

此属性持有场景的背景刷。

设置此属性可以将场景背景更改为不同的颜色、渐变或纹理。默认背景刷是Qt::NoBrush。背景在物品之前（在其后面）绘制。

示例

scene = QGraphicsScene()
view = QGraphicsView(scene)
view.show()
# a blue background
scene.setBackgroundBrush(Qt.blue)
# a gradient background
gradient = QRadialGradient(0, 0, 10)
gradient.setSpread(QGradient.RepeatSpread)
scene.setBackgroundBrush(gradient)

render() 调用 drawBackground() 来绘制场景背景。为了更详细地控制背景的绘制方式，您可以在 QGraphicsScene 的子类中重写 drawBackground() 函数。

访问函数
属性bspTreeDepth: int#

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

此属性持有 QGraphicsScene 的 BSP 索引树的深度。

当使用NoIndex时，此属性无效。

此值确定QGraphicsScene的BSP树深度。深度直接影响到QGraphicsScene的性能和内存使用；后者随着树深度的增加呈指数增长。在最佳树深度下，即使在成千上万项的场景中，QGraphicsScene也可以快速确定项的局部性。这也极大地提升了渲染性能。

默认情况下，此值为0，此时Qt将根据场景中项的大小、位置和数量猜测一个合理的默认深度。然而，如果这些参数频繁变化，那么您可能会在QGraphicsScene内部调整深度时遇到性能下降。您可以通过设置此属性来固定树深度，从而避免潜在的延迟。

树深度和场景矩形大小决定了场景划分的粒度。每个场景段的尺寸由以下算法确定

segmentSize = sceneRect().size() / pow(2, depth - 1)

BSP树在每个段包含0到10个项时达到最佳大小。

另请参阅

itemIndexMethod

访问函数
属性focusOnTouch: 布尔值#

此属性表示是否在接收touch begin事件时项获得焦点。

通常仅在项被点击时才传递焦点。触摸板的轻触通常被操作系统解释为等价于鼠标点击，并产生一个合成的点击事件。但是，至少在macOS上，您可以配置此行为。

默认情况下，QGraphicsScene在触摸板或类似设备上也会传递焦点。如果操作系统配置为在触摸板轻触时不会生成合成的鼠标点击，这可能会令人惊讶。如果操作系统在触摸板轻触时生成合成的鼠标点击，则在触摸手势开始时传递焦点是不必要的。

关闭focusOnTouch后，QGraphicsScene的行为与在macOS上预期一致。

默认值为true，确保默认行为与Qt 5.12之前版本相同。设置为false可以防止触摸事件触发焦点改变。

访问函数
属性font: QFont#

此属性保存场景的默认字体。

此属性提供场景的字体。场景字体默认为，并从 font 中解析所有其条目。

如果场景的字体发生更改，无论是通过 setFont() 直接更改还是当应用程序字体间接更改时，QGraphicsScene 首先发送自身一个 FontChange 事件，然后向场景中所有顶级小部件项发送 FontChange 事件。这些项通过将它们自己的字体解析到场景来响应，然后再通知它们的子项，依此类推，直到所有小部件项都已更新其字体。

更改场景字体（直接或通过 setFont() 间接），将自动安排整个场景的重绘。

另请参阅

font setFont() palette style()

访问函数
属性 foregroundBrush: QBrush#

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

此属性保存场景的前景色笔刷。

更改此属性以将场景的前景色设置为不同的颜色、渐变或纹理。

前景在项目之后（在项目之上）绘制。默认前景笔刷是 Qt::NoBrush（即不绘制前景）。

示例

scene = QGraphicsScene()
view = QGraphicsView(scene)
view.show()
# a white semi-transparent foreground
scene.setForegroundBrush(QColor(255, 255, 255, 127))
# a grid foreground
scene.setForegroundBrush(QBrush(Qt.lightGray, Qt.CrossPattern))

render() 调用 drawForeground() 来绘制场景前景。为了更详细地控制前景的绘制，您可以在 QGraphicsScene 子类中重新实现 drawForeground() 函数。

访问函数
属性 itemIndexMethod: QGraphicsScene.ItemIndexMethod#

此属性保存项目索引方法。

QGraphicsScene 会将索引算法应用于场景，以加快像 items() 和 itemAt() 这样的物品发现函数。索引在静态场景（即物品不会移动的场景）中效率最高。对于动态场景或包含许多动画物品的场景，索引维护可能会超过快速查找的优势。

对于常见情况，默认索引方法 BspTreeIndex 工作良好。如果您的场景使用了许多动画且您遇到速度较慢的问题，您可以通过调用 setItemIndexMethod(NoIndex) 来禁用索引。

另请参阅

bspTreeDepth

访问函数
属性 minimumRenderSize: float#

此属性存储一个物品必须具有的最小视图变换大小，以便被绘制。

当场景被绘制时，任何其宽度或高度转换为目标视图后小于 minimumRenderSize() 的物品将不会被绘制。如果一个物品没有被绘制，并且它剪贴了其子物品，它们也将不会绘制。通过设置此值可以加快在放缩后的视图中进行的许多物体绘制的场景的渲染速度。

默认值为 0。如果没有设置，或者设置为 0 或负值，则所有物品将始终被绘制。

例如，设置此属性在场景由多个视图渲染时特别有用，其中一个视图作为概览图，始终显示所有物品。在包含许多物品的场景中，此类视图将使用高放大系数，以便显示所有物品。由于放大，较小的物品对最终渲染场景的贡献微乎其微。为了避免绘制这些物品并减少渲染场景所需的时间，您可以调用具有非负值的 setMinimumRenderSize()。

注意

由于太小而不绘制的物品仍然由诸如 items() 和 itemAt() 之类的方 法返回，并参与碰撞检测和交互。建议您将 minimumRenderSize() 设置为小于或等于 1 的值，以避免大型未被绘制的交互式物品。

另请参阅

levelOfDetailFromTransform()

访问函数
属性 palette: QPalette#

此属性存储场景的默认调色板。

该属性提供了场景调色板。场景调色板默认从palette 中获取。

如果场景调色板发生变化，无论是通过 setPalette() 直接更改，还是通过应用程序调色板间接更改，QGraphicsScene 首先会发送 itself 一个 PaletteChange 事件，然后向场景中的所有顶层小部件发送 PaletteChange 事件。这些小部件会通过将其自己的调色板解析到场景中来响应，然后通知其子项，子项再次通知子项，以此类推，直到所有小部件都已更新其调色板。

更改场景调色板（直接或通过 setPalette() 间接更改），将自动安排整个场景的重绘。

访问函数
property sceneRect: QRectF#

该属性保存场景矩形；场景的边界矩形。

场景矩形定义了场景的范围。它主要被 QGraphicsView 用来自定义视图的默认可滚动区域，以及由 QGraphicsScene 来管理项目索引。

如果没有设置，或者设置了为 null 的 QRectF，sceneRect() 将返回自场景创建以来所有项目在场景中的最大边界矩形（即当项目添加到场景或移动时增长，但从不缩小）。

另请参阅

width() height() sceneRect

访问函数
property stickyFocus: bool#

该属性保存了是否单击场景背景会清除焦点。

当 QGraphicsScene 对象的 stickyFocus 属性设置为 true 时，用户单击场景背景或不可接受焦点的项时，焦点将保持不变。否则，焦点将被清除。

默认情况下，该属性为 false。

焦点变化是鼠标点击的结果。您可以在 mousePressEvent() 中重写 QGraphicsScene 的子类，以根据用户点击的位置切换该属性。

访问函数
__init__(sceneRect[, parent=None])#
参数:

使用 sceneRect 作为其场景矩形来构造一个 QGraphicsScene 对象。参数 parent 被传递给 QObject 的构造函数。

另请参阅

sceneRect

__init__([parent=None])
参数:

parent – QObject

构造一个 QGraphicsScene 对象。参数 parent 被传递给 QObject 的构造函数。

__init__(x, y, width, height[, parent=None])
参数:

  • x – float

  • y – float

  • width – float

  • height – float

  • parent – QObject

使用由 (x, y) 指定的矩形以及给定的 width 和 height 作为其场景矩形来构造一个 QGraphicsScene 对象。参数 parent 被传递给 QObject 的构造函数。

另请参阅

sceneRect

activePanel()#
返回类型：

QGraphicsItem

返回当前活动面板，如果没有活动面板则返回 None。

另请参阅

setActivePanel()

activeWindow()#
返回类型：

QGraphicsWidget

返回当前活动窗口，如果没有活动窗口则返回 None。

另请参阅

setActiveWindow()

addEllipse(rect[, pen=QPen()[, brush=QBrush()]])#
参数:
返回类型：

QGraphicsEllipseItem

在场景中创建并添加一个椭圆项，并返回项指针。椭圆的几何形状由 rect 定义，其画笔和画刷初始化为 pen 和 brush。

注意，项的几何形状是在项坐标中提供的，并且其位置初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addEllipse(x, y, w, h[, pen=QPen()[, brush=QBrush()]])
参数:

  • x – float

  • y – float

  • 宽(w) - 浮点数

  • 高(h) - 浮点数

  • pen – QPen

  • brush – QBrush

返回类型：

QGraphicsEllipseItem

该便捷函数等同于调用 addEllipse (QRectF(x, y, w, h), pen, brush).

addItem(item)#
参数:

item – QGraphicsItem

将item及其所有子项添加到此场景中。此场景将拥有item的所有权。

如果项是可见的（即，isVisible()返回true），当控制权回到事件循环时，QGraphicsScene将发出changed()事件。

如果项已在其他场景中，它将先从其旧场景中移除，然后作为顶级项添加到此场景中。

当项被添加到场景中时，QGraphicsScene会向item发送ItemSceneChange通知。如果项目前不属于任何场景，则只发送一条通知。如果它已经属于场景（即，被移动到该场景），当项从其先前场景中移除时，QGraphicsScene将发送附加通知。

如果项是面板、场景处于激活状态且场景中没有活动面板，则该项将被激活。

addLine(line[, pen=QPen()])#
参数:
返回类型：

QGraphicsLineItem

创建并添加一个线项到场景中，并返回项指针。线的几何形状由 line 定义，其画笔初始化为 pen。

注意，项的几何形状是在项坐标中提供的，并且其位置初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addLine(x1, y1, x2, y2[, pen=QPen()])
参数:

  • x1 – float

  • y1 – float

  • x2 – float

  • y2 – float

  • pen – QPen

返回类型：

QGraphicsLineItem

此便捷函数等价于调用addLine (QLineF(x1, y1, x2, y2), pen))。

addPath(path[, pen=QPen()[, brush=QBrush()]])#
参数:
返回类型：

QGraphicsPathItem

创建并添加路径项到场景，并返回项指针。路径的几何形状由path定义，其笔和刷初始化为pen和brush。

注意，项的几何形状是在项坐标中提供的，并且其位置初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addPixmap(pixmap)#
参数:

pixmap – QPixmap

返回类型：

QGraphicsPixmapItem

创建并添加位图到场景，并返回项指针。位图由pixmap定义。

注意，项的几何形状是在项坐标中提供的，并且其位置初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addPolygon(polygon[, pen=QPen()[, brush=QBrush()]])#
参数:
返回类型：

QGraphicsPolygonItem

创建并将其添加到场景中的多边形项，并返回项指针。多边形由 polygon 定义，其笔和画笔初始化为 pen 和 brush。

注意，项的几何形状是在项坐标中提供的，并且其位置初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addRect(rect[, pen=QPen()[, brush=QBrush()]])#
参数:
返回类型：

QGraphicsRectItem

创建并将其添加到场景中的矩形项，并返回项指针。矩形的几何形状由 rect 定义，其笔和画笔初始化为 pen 和 brush。

请注意，项的几何形状使用项坐标提供，其位置初始化为 (0, 0)。例如，如果添加 QRect(50, 50, 100, 100)，则其左上角相对于项的坐标系原点将位于 (50, 50)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addRect(x, y, w, h[, pen=QPen()[, brush=QBrush()]])
参数:

  • x – float

  • y – float

  • 宽(w) - 浮点数

  • 高(h) - 浮点数

  • pen – QPen

  • brush – QBrush

返回类型：

QGraphicsRectItem

此便捷函数等价于调用 addRect (QRectF(x, y, w, h), pen, brush)。

addSimpleText(text[, font=QFont()])#
参数:

  • text – str

  • font – QFont

返回类型：

QGraphicsSimpleTextItem

创建并添加一个 QGraphicsSimpleTextItem 到场景中，并返回项目指针。文本字符串被初始化为 text，其字体被初始化为 font。

项目位置被初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addText(text[, font=QFont()])#
参数:

  • text – str

  • font – QFont

返回类型：

QGraphicsTextItem

创建并添加文本项目到场景中，并返回项目指针。文本字符串被初始化为 text，其字体被初始化为 font。

项目位置被初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

addWidget(widget[, wFlags=Qt.WindowFlags()])#
参数:
返回类型：

QGraphicsProxyWidget

为 widget 创建一个新的 QGraphicsProxyWidget，将其添加到场景中，并返回代理的指针。wFlags 设置嵌入代理小部件的默认窗口标志。

项目位置被初始化为 (0, 0)。

如果项是可见的（即，isVisible() 返回 true），在控制返回到事件循环后，QGraphicsScene 将发出 changed() 信号。

注意，Qt::WA_PaintOnScreen 小部件属性被设置为和封装外部应用程序或控制器的工具小部件不支持。例如：QOpenGLWidget 和 QAxWidget。

advance()#

此槽通过调用场景上所有项目的 advance() 函数使场景前进一步。这分两个阶段完成：在第一阶段，所有项目都会接到通知场景即将更改；在第二阶段，所有项目都会接到可以移动的通知。在第一阶段，传递值 0 给 advance()，在第二阶段传递值 1。

请注意，您还可以使用动画框架进行动画。

另请参阅

advance() QTimeLine

backgroundBrush()#
返回类型：

QBrush

另请参阅

setBackgroundBrush()

属性 backgroundBrushᅟ 的获取器。

bspTreeDepth()#
返回类型：

int

另请参阅

setBspTreeDepth()

属性 bspTreeDepthᅟ 的获取器。

changed(region)#
参数:

region – .list of QRectF

此信号由 QGraphicsScene 在达到事件循环时发出，如果场景内容发生变化。参数 region 包含一系列场景矩形，指示已更改的区域。

另请参阅

updateScene()

clear()#

从场景中删除并删除所有项，但保留场景的其余状态。

另请参阅

addItem()

clearFocus()#

清除场景中的焦点。如果在调用此函数时任何项有焦点，它将会失去焦点，并再次在场景获得焦点时重新获得焦点。

没有焦点的场景会忽略按键事件。

clearSelection()#

清除当前选择。

collidingItems(item[, mode=Qt.IntersectsItemShape])#
参数:
返回类型：

.list of QGraphicsItem

返回与 item 发生碰撞的所有项列表。碰撞是通过调用 collidesWithItem() 来确定的；碰撞检测由 mode 确定。默认情况下，返回所有与 item 形状相交或包含在 item 形状内的项。

项按降序堆叠顺序返回（即列表中的第一个项是上层的项，最后一个项是下层的项）。

另请参阅

items() itemAt() collidesWithItem() 排序

contextMenuEvent(event)#
参数:

event – QGraphicsSceneContextMenuEvent

此事件处理程序，针对 contextMenuEvent 事件，可以在子类中重新实现以接收上下文菜单事件。默认实现将事件转发到接受上下文菜单事件的最顶层可见项，其位置为事件的位置。如果没有项在此位置接受上下文菜单事件，则事件将被忽略。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

另请参阅

contextMenuEvent()

createItemGroup(items)#
参数:

items – .QGraphicsItem 列表

返回类型：

QGraphicsItemGroup

将 items 中的所有项组合到一个新的 QGraphicsItemGroup 中，并返回指向组的指针。组以 items 的共同祖先作为其父级，以及位置（0,0）创建。所有项都被重新绑定到组，它们的位置和转换映射到组。如果 items 为空，该函数将返回一个空的顶层 QGraphicsItemGroup 。

QGraphicsScene 拥有组项的所有权；您不需要删除它。要解散（取消分组）一个组，请调用 destroyItemGroup() .

destroyItemGroup(group)#
参数:

group – QGraphicsItemGroup

将 group 中的所有对象重新归到其父对象，然后从场景中删除 group ，最后删除它。对象的定位和变换从组映射到组的父对象。

dragEnterEvent(event)#
参数:

event – QGraphicsSceneDragDropEvent

此事件处理程序，为事件 event，可在子类中重写以接收场景的拖入事件。

默认实现接受事件并准备场景接受拖动移动事件。

dragLeaveEvent(event)#
参数:

event – QGraphicsSceneDragDropEvent

此事件处理程序，为事件 event，可在子类中重写以接收场景的拖出事件。

dragMoveEvent(event)#
参数:

event – QGraphicsSceneDragDropEvent

此事件处理器处理 event 事件，可以在子类中重新实现以接收场景的拖动移动事件。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

drawBackground(painter, rect)#
参数:

使用 painter 绘制场景的背景，在绘制任何项和前景之前。重新实现此函数以提供场景的自定义背景。

所有绘制都在 scene 坐标系中完成。参数 rect 是暴露的矩形。

如果您只想定义背景的颜色、纹理或渐变，可以直接调用 setBackgroundBrush()。

另请参阅

drawForeground() drawItems()

drawForeground(painter, rect)#
参数:

使用 painter 绘制场景的前景，在背景和所有项目绘制之后。重新实现此函数以提供场景的自定义前景。

所有绘制都在 scene 坐标系中完成。参数 rect 是暴露的矩形。

如果您只想定义前景的颜色、纹理或渐变，可以直接调用 setForegroundBrush()。

另请参阅

drawBackground() drawItems()

dropEvent(event)#
参数:

event – QGraphicsSceneDragDropEvent

此事件处理器处理 event 事件，可以在子类中重新实现以接收场景的放下事件。

focusInEvent(event)#
参数:

event – QFocusEvent

此事件处理程序，用于 focusEvent 事件，可以在子类中重写以接收焦点事件。

默认实现将焦点放在场景上，然后是最后一个焦点项。

另请参阅

focusOutEvent()

focusItem()#
返回类型：

QGraphicsItem

当场景为活动状态时，此函数返回场景的当前焦点项，或者 None（如果没有项目当前具有焦点）。当场景不为活动状态时，此函数返回当场景变为活动状态时将获得输入焦点的项目。

焦点项在场景接收到键事件时接收键盘输入。

focusItemChanged(newFocus, oldFocus, reason)#
参数:

此信号由 QGraphicsScene 在场景中焦点变化时发出（即项目获得或失去输入焦点，或当一个项目的焦点传递到另一个项目时）。如果您需要跟踪其他项目何时获得输入焦点，可以连接到该信号。这对于实现虚拟键盘、输入方法和光标项特别有用。

oldFocusItem 是之前有焦点的项目的指针，或信号发出前没有项目有焦点时为0。 newFocusItem 是获得输入焦点的项目的指针，如果焦点丢失则 None。 reason 表示焦点变化的原因（例如，如果场景在输入字段有焦点时被禁用，oldFocusItem 将指向输入字段项目，newFocusItem 将是 None，并且 reason 将是 Qt::ActiveWindowFocusReason）。

focusNextPrevChild(next)#
参数:

next – bool

返回类型：

bool

查找合适的新的小部件给予键盘焦点，如 Tab 和 Shift+Tab，如果找到新的小部件返回 true，否则返回 false。如果 next 是 true，则此函数将向前搜索；如果 next 是 false，则它将向后搜索。

您可以在 QGraphicsScene 的子类中重新实现此函数，以提供对您场景中 Tab 焦点传递的精细控制。默认实现基于由 setTabOrder() 定义的 tab 焦点链。

focusOnTouch()#
返回类型：

bool

另请参阅

setFocusOnTouch()

属性 focusOnTouch 的获取器。

focusOutEvent(event)#
参数:

event – QFocusEvent

这个事件处理器，用于处理 focusEvent 事件，可以由子类重新实现来接收焦点丢失事件。

默认实现从任何焦点项目移除焦点，然后从场景中移除焦点。

另请参阅

focusInEvent()

font()#
返回类型：

QFont

另请参阅

setFont()

属性 font 的获取器。

foregroundBrush()#
返回类型：

QBrush

另请参阅

setForegroundBrush()

属性 foregroundBrush 的获取器。

hasFocus()#
返回类型：

bool

如果场景具有焦点，则返回 true；否则返回 false。如果场景具有焦点，它将把按键事件从 QKeyEvent 传递给任何具有焦点的项目。

另请参阅

setFocus() setFocusItem()

高度()#
返回类型：

浮点数

此便捷函数等同于调用 sceneRect().height()。

另请参阅

width()

helpEvent(event)#
参数:

事件 – QGraphicsSceneHelpEvent

此事件处理程序，对于事件 helpEvent，可以在子类中重新实现来接收帮助事件。该事件为 QEvent::ToolTip 类型，当请求工具提示时创建。

默认实现在鼠标光标位置显示最顶层可见项目的工具提示，即具有最高 z 值的项目。如果没有项目设置了工具提示，此函数不执行任何操作。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

inputMethodEvent(event)#
参数:

事件 – QInputMethodEvent

此事件处理程序，对于事件 event，可以在子类中重新实现来接收场景的输入方法事件。

默认实现将事件转发到 focusItem()。如果没有项目当前具有焦点，或者当前焦点项目不接受输入方法，此函数不执行任何操作。

另请参阅

inputMethodEvent()

inputMethodQuery(query)#
参数:

查询 – InputMethodQuery

返回类型：

对象

此方法由输入法用于查询场景的一组属性，以便能够支持复杂输入法操作，如支持周围文本和重构。

query 参数指定查询哪个属性。

另请参阅

inputMethodQuery()

invalidate([rect=QRectF()[, layers=QGraphicsScene.SceneLayer.AllLayers]])#
参数:

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

在场景中使 rect 中的 layers 无效并安排重新绘制。在 layers 中的任何缓存内容都将无条件地失效并重新绘制。

您可以使用此函数重载来通知 QGraphicsScene 场景的背景或前景已更改。此函数通常用于具有基于瓦片的背景的场景，在 QGraphicsView 启用 CacheBackground 时通知更改。

示例

def rectForTile(self, int x, int y):

    # Return the rectangle for the tile at position (x, y).
    return QRectF(x * tileWidth, y * tileHeight, tileWidth, tileHeight)

def setTile(self, x, y, pixmap):

    # Sets or replaces the tile at position (x, y) with pixmap.
    if x >= 0 and x < numTilesH and y >= 0 and y < numTilesV:
        tiles[y][x] = pixmap
        invalidate(rectForTile(x, y), BackgroundLayer)


def drawBackground(self, painter, exposed):

    # Draws all tiles that intersect the exposed area.
    for y in range(0, numTilesV):
        for x in range(0, numTilesH):
            rect = rectForTile(x, y)
            if exposed.intersects(rect):
                painter.drawPixmap(rect.topLeft(), tiles[y][x])

请注意，QGraphicsView 目前仅支持背景缓存（见 CacheBackground）。如果传入了除 BackgroundLayer 之外的其他任何层，则此函数与调用 update() 等效。

另请参阅

resetCachedContent()

invalidate(x, y, w, h[, layers=QGraphicsScene.SceneLayer.AllLayers])
参数:

  • x – float

  • y – float

  • 宽(w) - 浮点数

  • 高(h) - 浮点数

  • layers – 组合 SceneLayer

这是一个重载函数。

此便利函数等效于调用 invalidate(QRectF(x, y, w, h), layers)；

isActive()#
返回类型：

bool

如果场景是活动的（例如，至少有一个活动的 QGraphicsView 正在查看），则返回 true；否则返回 false。

itemAt(pos, deviceTransform)#
参数:
返回类型：

QGraphicsItem

返回指定位置的顶端可见项，如果该位置没有项，则返回None。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

另请参阅

items() collidingItems() Sorting

itemAt(x, y, deviceTransform)
参数:

  • x – float

  • y – float

  • deviceTransform – QTransform

返回类型：

QGraphicsItem

这是一个重载函数。

返回指定位置（x，y）的顶端可见项，如果该位置没有项，则返回None。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

该便利函数等价于调用itemAt(QPointF(x, y), deviceTransform)。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

itemIndexMethod()#
返回类型：

ItemIndexMethod

另请参阅

setItemIndexMethod()

获取属性itemIndexMethod。

items(path[, mode=Qt.IntersectsItemShape[, order=Qt.DescendingOrder[, deviceTransform=QTransform()]]]])#
参数:
返回类型：

.list of QGraphicsItem

这是一个重载函数。

返回所有可见项，根据mode，这些项要么在指定的path内，要么与之相交，并按order进行排序。在这种情况下，“可见”定义为对于：isVisible()返回true，effectiveOpacity()返回的值大于0.0（这是完全透明的），并且父项不会剪裁它。

mode的默认值是Qt::IntersectsItemShape；所有与path形状相交或包含在其中的项都被返回。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

另请参阅

itemAt() 排序

items(pos[, mode=Qt.IntersectsItemShape[, order=Qt.DescendingOrder[, deviceTransform=QTransform()]]]])
参数:
返回类型：

.list of QGraphicsItem

返回所有可见的项目，根据mode，它们在列表中按order排序，位于指定的pos位置。在这种情况下，“可见”定义了以下项目：isVisible()返回true，effectiveOpacity()返回大于0.0（这是完全透明）的值，并且父项目没有裁剪它。

mode的默认值是Qt::IntersectsItemShape；返回所有与pos位置准确形状相交的项目。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

另请参阅

itemAt() 排序

items(polygon[, mode=Qt.IntersectsItemShape[, order=Qt.DescendingOrder[, deviceTransform=QTransform()]]])
参数:
返回类型：

.list of QGraphicsItem

这是一个重载函数。

返回所有可见的项目，根据mode，它们位于或与指定的polygon相交，在列表中按order排序。在这种情况下，“可见”定义了以下项目：isVisible()返回true，effectiveOpacity()返回大于0.0（这是完全透明）的值，并且父项目没有裁剪它。

mode的默认值是Qt::IntersectsItemShape；返回所有与或包含在polygon中的项目的准确形状相交的项目。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

另请参阅

itemAt() 排序

items(rect[, mode=Qt.IntersectsItemShape[, order=Qt.DescendingOrder[, deviceTransform=QTransform()]]])
参数:
返回类型：

.list of QGraphicsItem

这是一个重载函数。

返回所有可见的项目，根据mode，它们位于或与指定的rect相交，在列表中按order排序。在这种情况下，“可见”定义了以下项目：isVisible()返回true，effectiveOpacity()返回大于0.0（这是完全透明）的值，并且父项目没有裁剪它。

mode的默认值是Qt::IntersectsItemShape；返回所有与或包含在rect中的项目的准确形状相交的项目。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

另请参阅

itemAt() 排序

items(x, y, w, h, mode, order[, deviceTransform=QTransform()])
参数:
返回类型：

.list of QGraphicsItem

这是一个重载函数。

根据 mode 的不同，返回所有可见项目，这些项目要么在由 x、y、w 和 h 定义的矩形内，要么与该矩形相交，列表按 order 排序。在这种情况下，“可见”定义了如下项目：isVisible() 返回 true、effectiveOpacity() 返回一个大于 0.0 的值（这表示完全透明）且父项目不对其剪裁。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

items([order=Qt.DescendingOrder])
参数:

order – SortOrder

返回类型：

.list of QGraphicsItem

返回场景上所有项目的有序列表。 order 决定堆叠顺序。

另请参阅

addItem() removeItem() Sorting

itemsBoundingRect()#
返回类型：

QRectF

计算并返回场景上所有项目的边界矩形。该函数通过遍历所有项目工作，因此对于大型场景可能会很慢。

另请参阅

sceneRect()

keyPressEvent(event)#
参数:

event – QKeyEvent

此事件处理程序，用于处理 keyEvent 事件，可以在子类中重新实现以接收按键事件。默认实现将事件转发到当前的焦点项目。

keyReleaseEvent(event)#
参数:

event – QKeyEvent

此事件处理程序，用于处理 keyEvent 事件，可以在子类中重新实现以接收按键释放事件。默认实现将事件转发到当前的焦点项目。

minimumRenderSize()#
返回类型：

浮点数

另请参阅

setMinimumRenderSize()

获取属性 minimumRenderSize 的值。

mouseDoubleClickEvent(event)#
参数:

event – QGraphicsSceneMouseEvent

此事件处理程序处理mouseEvent事件，可以在子类中重写以接收场景的鼠标双击事件。

如果用户在场景上双击，则场景将首先接收鼠标按下事件，然后是释放事件（即单击），然后是双击事件，最后是释放事件。如果双击事件被发送到不同于第一次按下和释放的项，则它将作为按下事件传递。然而，在这种情况下，三击事件不会被作为双击事件传递。

默认实现类似于mousePressEvent()。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

mouseGrabberItem()#
返回类型：

QGraphicsItem

返回当前鼠标抓取项，如果没有项当前抓取鼠标，则返回None。鼠标抓取项是接收发送到场景的所有鼠标事件的项目。

当一个项目接收并接受鼠标按下事件时，该项目就成为鼠标抓取项，并且它保持鼠标抓取项的状态，直到以下事件之一发生

  • 如果项目在没有任何其他按钮按下时接收到鼠标释放事件，则它将失去鼠标抓取。

  • 如果项目变为不可见（即有人调用item->setVisible(false)），或者如果该项目变为禁用（即有人调用item->setEnabled(false)），则它将失去鼠标抓取。

  • 如果项目从场景中删除，则它将失去鼠标抓取。

如果项目失去鼠标抓取，则场景将忽略所有鼠标事件，直到新项抓取鼠标（即，直到新项接收鼠标按下事件）。

mouseMoveEvent(event)#
参数:

event – QGraphicsSceneMouseEvent

该事件处理器用于事件 mouseEvent，可以通过子类重新实现以接收场景的鼠标移动事件。

默认实现依赖于鼠标捕获状态。如果存在鼠标捕获项，则事件被发送到鼠标捕获项。如果当前位置有任何接受悬停事件的项，则事件被转换为悬停事件并接受；否则将忽略该事件。

mousePressEvent(event)#
参数:

event – QGraphicsSceneMouseEvent

该事件处理器用于事件 mouseEvent，可以通过子类重新实现以接收场景的鼠标按下事件。

默认实现依赖于场景状态。如果存在鼠标捕获项，则事件会被发送到鼠标捕获项。否则，事件会被转发到场景中最上层的可见项，该项接受从事件位置发送的鼠标事件，并且该项立即成为鼠标捕获项。

如果在场景的给定位置上没有项，选择区域会重置，任何获得焦点的项都会失去输入焦点，然后事件就会被忽略。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

mouseReleaseEvent(event)#
参数:

event – QGraphicsSceneMouseEvent

该事件处理器用于事件 mouseEvent，可以通过子类重新实现以接收场景的鼠标释放事件。

默认实现依赖于鼠标捕获状态。如果没有鼠标捕获，则事件会被忽略。否则，如果存在鼠标捕获项，事件会被发送到鼠标捕获项。如果这个鼠标释放代表最后按下的按钮，则鼠标捕获项会失去鼠标捕获。

palette()#
返回类型：

QPalette

另请参阅

setPalette()

属性 palette 的 getter。

removeItem(item)#
参数:

item – QGraphicsItem

从场景中删除项 item 及其所有子项。将 item 的所有权传递给调用者（即，QGraphicsScene 在销毁时将不再删除 item）。

另请参阅

addItem()

render(painter[, target=QRectF()[, source=QRectF()[, aspectRatioMode=Qt.KeepAspectRatio]]])#
参数:

警告

本节包含从C++自动转换为Python的片段，可能包含错误。

使用 painter 将场景中 source 矩形的区域绘制到 target。此函数非常有用，可以将场景 contents 捕获到 paint device 上，例如到 QImage（例如，进行截图），或与 QPrinter 打印。例如

scene = QGraphicsScene()
scene.addItem(...
...
printer = QPrinter(QPrinter.HighResolution)
printer.setPaperSize(QPrinter.A4)
painter = QPainter(printer)
scene.render(painter)

如果 source 是空矩形，此函数将使用 sceneRect 来确定要绘制的内容。如果 target 是空矩形，则使用 painter 的 paint device 的尺寸。

根据 aspectRatioMode 将源矩形的内容转换，以适应目标矩形。默认情况下，保持宽高比，并将 source 缩放以适合 target。

另请参阅

render()

sceneRect()#
返回类型：

QRectF

另请参阅

setSceneRect()

属性 sceneRect 的 getter。

sceneRectChanged(rect)#
参数:

rect – QRectF

此信号由 QGraphicsScene 在场景矩形改变时发出。参数 rect 是新的场景矩形。

另请参阅

updateSceneRect()

selectedItems()#
返回类型：

.list of QGraphicsItem

返回所有当前选中项的列表。项的返回顺序无关紧要。

另请参阅

setSelectionArea()

selectionArea()#
返回类型：

QPainterPath

返回之前通过 setSelectionArea() 设置的选择区域，或如果没有设置选择区域，则返回一个空的 QPainterPath。

另请参阅

setSelectionArea()

selectionChanged()#

此信号由 QGraphicsScene 在选择更改时发出。您可以通过调用 selectedItems() 来获取新的选中项列表。

当选择项或取消选择项、设置或清除选择区域、如果将预选项添加到场景或从场景中删除选中项时，选择会更改。

QGraphicsScene 只在组选择操作中发出此信号一次。例如，如果您设置了选择区域，选中或取消选中一个 QGraphicsItemGroup 或者在场景中添加或移除了包含多个选中项的父项，那么在操作完成后才会发射 selectionChanged() 信号（而不是为每个项都发射一次）。

sendEvent(item, event)#
参数:
返回类型：

bool

通过可能的事件过滤器将事件 event 发送到项 item。

只有当该项启用时，才发送事件。

如果事件被过滤器过滤或如果该项被禁用，则返回 false。否则返回事件处理程序返回的值。

另请参阅

有关 sceneEvent() 方法的更多信息，请参阅 sceneEventFilter()

setActivePanel(item)#
参数:

item – QGraphicsItem

激活 item，它必须是此场景中的一个项目。您也可以为 item 传递 0，此时 QGraphicsScene 将将任何当前激活的面板置为非激活状态。

如果场景当前处于非活动状态，则 item 将保持非活动状态，直到场景变为活动状态（或者，如果 item 为 None，则不会激活任何项）。

setActiveWindow(widget)#
参数:

widget – QGraphicsWidget

激活 widget，它必须是此场景中的一个小部件。您也可以为 widget 传递 0，此时 QGraphicsScene 将将任何当前激活的窗口置为非激活状态。

setBackgroundBrush(brush)#
参数:

brush – QBrush

另请参阅

backgroundBrush()

属性 backgroundBrushᅟ 的设置器。

setBspTreeDepth(depth)#
参数:

depth – int

另请参阅

bspTreeDepth()

属性 bspTreeDepthᅟ 的设置器。

setFocus([focusReason=Qt.OtherFocusReason])#
参数:

focusReason – FocusReason

通过向场景发送一个QFocusEvent来设置场景的焦点，将focusReason作为原因。如果场景之前失去焦点并在某个项目获得焦点，场景再次获得焦点时，上一次焦点项目将收到焦点，并以focusReason作为原因。

如果场景已经具有焦点，此函数不做任何操作。

setFocusItem(item[, focusReason=Qt.OtherFocusReason])#
参数:

将场景的焦点项目设置为item，使用焦点原因focusReason，并在移除任何以前可能有焦点的项目焦点后执行。

如果item是None，或者它不接受焦点（即未启用ItemIsFocusable标志），或者不可见或未启用，此函数仅从任何以前的焦点项目中移除焦点。

如果项目不是None，并且场景当前没有焦点（即hasFocus()返回false），此函数将自动调用setFocus()。

setFocusOnTouch(enabled)#
参数:

enabled – bool

另请参阅

focusOnTouch()

属性focusOnTouchᅟ的设置器。

setFont(font)#
参数:

font – QFont

另请参阅

font()

属性 font 的设置器。

setForegroundBrush(brush)#
参数:

brush – QBrush

另请参阅

foregroundBrush()

属性 foregroundBrush 的设置器。

setItemIndexMethod(method)#
参数:

method – ItemIndexMethod

另请参阅

itemIndexMethod()

属性 itemIndexMethod 的设置器。

setMinimumRenderSize(minSize)#
参数:

minSize – float

另请参阅

minimumRenderSize()

属性 minimumRenderSize 的设置器。

setPalette(palette)#
参数:

palette – QPalette

另请参阅

palette()

属性 palette 的设置器。

setSceneRect(rect)#
参数:

rect – QRectF

另请参阅

sceneRect()

属性 sceneRect 的设置器。

setSceneRect(x, y, w, h)
参数:

  • x – float

  • y – float

  • 宽(w) - 浮点数

  • 高(h) - 浮点数

setSelectionArea(path[, selectionOperation=Qt.ReplaceSelection[, mode=Qt.IntersectsItemShape[, deviceTransform=QTransform()]]]])#
参数:

这是一个重载函数。

使用mode确定哪些项在选择区域内，将选择区域设置为path。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

selectionOperation确定对当前选中项的操作。

setSelectionArea(path, deviceTransform)
参数:

将选择区域设置为path。该区域内的所有项都将立即选中，区域外的项将被取消选中。您可以调用selectedItems()以获取所有选中项的列表。

deviceTransform 是应用于视图的转换，如果场景包含忽略变换的项，则需要提供。

要选中一个项，该项目必须被标记为可选的（ItemIsSelectable）。

setStickyFocus(enabled)#
参数:

enabled – bool

另请参阅

stickyFocus()

属性stickyFocusᅟ的设置器。

setStyle(style)#
参数:

style – QStyle

将场景的样式设置为style，并将样式重新父化到场景上。任何先前分配的样式都将被删除。场景的样式默认为style()，并作为场景中所有QGraphicsWidget项的默认样式。

通过调用此函数或通过调用setStyle()来更改样式，将自动更新场景中所有未明确分配样式的控件样式。

如果style为None，QGraphicsScene将恢复到style()。

另请参阅

style()

stickyFocus()#
返回类型：

bool

另请参阅

setStickyFocus()

属性《stickyFocus》的获取器。

style()#
返回类型：

QStyle

返回场景的样式，如果没有为场景明确分配样式，则与style()相同。

另请参阅

setStyle()

update([rect=QRectF()])#
参数:

rect – QRectF

在场景上计划重绘区域 rect。

另请参阅

sceneRect() changed()

update(x, y, w, h)
参数:

  • x – float

  • y – float

  • 宽(w) - 浮点数

  • 高(h) - 浮点数

这是一个重载函数。

此函数相当于调用 update(QRectF(x, y, w, h));

views()#
返回类型：

为QGraphicsView的列表

返回显示此场景的所有视图的列表。

另请参阅

scene()

wheelEvent(event)#
参数:

event – QGraphicsSceneWheelEvent

此事件处理程序，针对事件 wheelEvent，可以在子类中重新实现以接收场景的鼠标滚轮事件。

默认情况下，事件会传递到鼠标下的最顶层可见项。如果忽略，则事件会传播到该项下的项，依此类推，直到事件被接受或达到场景。如果没有项接受事件，则事件被忽略。

注意：有关此函数认为哪些项是可见的，请参阅 items() 的定义。

另请参阅

wheelEvent()

width()#
返回类型：

浮点数

此便利函数等同于调用 sceneRect() .width()。

另请参阅

height()