QGraphicsScene Class

成员函数文档

QGraphicsScene::QGraphicsScene(QObject *parent = nullptr)

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

QGraphicsScene::QGraphicsScene(const QRectF &sceneRect, QObject *parent = nullptr)

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

另请参阅 sceneRect 。

QGraphicsScene::QGraphicsScene(qreal x, qreal y, qreal width, qreal height, QObject *parent = nullptr)

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

另请参阅 sceneRect 。

[virtual noexcept] QGraphicsScene::~QGraphicsScene()

在销毁场景对象之前，移除并删除该场景对象中的所有项目。该场景对象将从应用程序的全局场景列表中移除，并从所有关联的视图中移除。

QGraphicsItem *QGraphicsScene::activePanel() const

返回当前活动的面板；如果当前没有活动面板，则返回nullptr 。

另请参阅 QGraphicsScene::setActivePanel()。

QGraphicsWidget *QGraphicsScene::activeWindow() const

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

另请参阅 QGraphicsScene::setActiveWindow()。

QGraphicsEllipseItem *QGraphicsScene::addEllipse(const QRectF &rect, const QPen &pen = QPen(), const QBrush &brush = QBrush())

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

请注意，该项的几何形状以项坐标系为基准，其位置初始化为 (0, 0)。

如果该项目可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed()。

另请参阅 addLine()、addPath()、addPixmap()、addRect()、addText()、addItem() 以及addWidget()。

QGraphicsEllipseItem *QGraphicsScene::addEllipse(qreal x, qreal y, qreal w, qreal h, const QPen &pen = QPen(), const QBrush &brush = QBrush())

此便捷函数相当于调用 addEllipse(QRectF(x,y,w,h),pen,brush)。

void QGraphicsScene::addItem(QGraphicsItem *item)

将item 及其所有子节点添加或移动到此场景中。该场景将获得item 的所有权。

如果该项可见（即QGraphicsItem::isVisible() 返回 true），则当控制权返回事件循环时，QGraphicsScene 将触发changed() 事件。

如果该项已位于另一个场景中，则会先将其从原场景中移除，然后作为顶级项添加到本场景中。

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

如果该项是一个面板，且当前场景处于活动状态，同时该场景中尚无活动面板，则该项将被激活。

另请参阅 removeItem()、addEllipse()、addLine()、addPath()、addPixmap()、addRect()、addText()、addWidget() 以及Sorting 。

QGraphicsLineItem *QGraphicsScene::addLine(const QLineF &line, const QPen &pen = QPen())

创建并向场景中添加一条线段，并返回该线段的指针。该线段的几何形状由line 定义，其笔触初始化为pen 。

请注意，该项的几何形状以项坐标系表示，其位置初始化为 (0, 0)。

如果该项可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed()。

另请参阅 addEllipse()、addPath()、addPixmap()、addRect()、addText()、addItem() 以及addWidget()。

QGraphicsLineItem *QGraphicsScene::addLine(qreal x1, qreal y1, qreal x2, qreal y2, const QPen &pen = QPen())

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

QGraphicsPathItem *QGraphicsScene::addPath(const QPainterPath &path, const QPen &pen = QPen(), const QBrush &brush = QBrush())

创建并向场景中添加一个路径项，并返回该项的指针。路径的几何形状由path 定义，其笔和画笔分别初始化为pen 和brush 。

请注意，该项的几何形状以项坐标系表示，且其位置初始化为 (0, 0)。

如果该项可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed() 事件。

另请参阅 addEllipse()、addLine()、addPixmap()、addRect()、addText()、addItem() 以及addWidget()。

QGraphicsPixmapItem *QGraphicsScene::addPixmap(const QPixmap &pixmap)

创建并向场景中添加一个像素图项，并返回该项的指针。该像素图由pixmap 定义。

请注意，该项的几何信息以项坐标系为基准，其初始位置为 (0, 0)。

如果该项可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环后，QGraphicsScene 将触发changed()。

另请参阅 addEllipse()、addLine()、addPath()、addRect()、addText()、addItem()，以及addWidget()。

QGraphicsPolygonItem *QGraphicsScene::addPolygon(const QPolygonF &polygon, const QPen &pen = QPen(), const QBrush &brush = QBrush())

创建并向场景中添加一个多边形项目，并返回该项目的指针。该多边形由polygon 定义，其笔和画笔分别初始化为pen 和brush 。

请注意，该项的几何信息以项坐标系表示，其位置初始化为 (0, 0)。

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

另请参阅 addEllipse()、addLine()、addPath()、addRect()、addText()、addItem()，以及addWidget()。

QGraphicsRectItem *QGraphicsScene::addRect(const QRectF &rect, const QPen &pen = QPen(), const QBrush &brush = QBrush())

创建并向场景中添加一个矩形对象，并返回该对象的指针。矩形的几何形状由rect 定义，其笔和画笔分别初始化为pen 和brush 。

请注意，该对象的几何参数以对象坐标系为基准，且其位置初始化为 (0, 0)。 例如，如果添加了一个QRect(50, 50, 100, 100)，则其左上角相对于项目坐标系的原点将位于 (50, 50)。

如果该项目可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将发出changed() 事件。

另请参阅 addEllipse()、addLine()、addPixmap()、addText()、addItem() 以及addWidget()。

QGraphicsRectItem *QGraphicsScene::addRect(qreal x, qreal y, qreal w, qreal h, const QPen &pen = QPen(), const QBrush &brush = QBrush())

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

QGraphicsSimpleTextItem *QGraphicsScene::addSimpleText(const QString &text, const QFont &font = QFont())

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

该项的位置初始化为 (0, 0)。

如果该项可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed() 事件。

另请参阅 addEllipse()、addLine()、addPixmap()、addRect()、addItem()，以及addWidget()。

QGraphicsTextItem *QGraphicsScene::addText(const QString &text, const QFont &font = QFont())

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

该项的位置初始化为 (0, 0)。

如果该项可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed()。

另请参阅 addEllipse()、addLine()、addPixmap()、addRect()、addItem()，以及addWidget()。

QGraphicsProxyWidget *QGraphicsScene::addWidget(QWidget *widget, Qt::WindowFlags wFlags = Qt::WindowFlags())

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

该项的位置初始化为 (0, 0)。

如果该项目可见（即QGraphicsItem::isVisible() 返回true ），则当控制权返回事件循环时，QGraphicsScene 将触发changed()。

请注意，设置了Qt::WA_PaintOnScreen 控件属性的控件，以及封装了外部应用程序或控制器的控件均不被支持。例如QOpenGLWidget 和QAxWidget。

另请参阅 addEllipse()、addLine()、addPixmap()、addRect()、addText()、addSimpleText() 以及addItem()。

[slot] void QGraphicsScene::advance()

该插槽通过为场景中的所有项目调用 `QGraphicsItem::advance()` 方法，将场景推进一步。该过程分为两个阶段：第一阶段，通知所有项目场景即将发生变化；第二阶段，通知所有项目它们可以移动。 在第一阶段，调用QGraphicsItem::advance() 时传递参数值 0；在第二阶段，则传递参数值 1。

请注意，您还可以使用动画框架（AnimationFramework）来实现动画效果。

另请参阅 QGraphicsItem::advance() 和QTimeLine 。

[signal] void QGraphicsScene::changed(const QList<QRectF> &region)

当控制权进入事件循环且场景内容发生变化时，QGraphicsScene 会发出此信号。region 参数包含一个场景矩形列表，这些矩形指明了发生变化的区域。

另请参阅 QGraphicsView::updateScene()。

[slot] void QGraphicsScene::clear()

从场景中移除并删除所有项目，但除此之外，场景的状态保持不变。

另请参阅 addItem()。

void QGraphicsScene::clearFocus()

清除场景的焦点。如果调用此函数时有任何项目处于焦点状态，该项目将失去焦点，并在场景重新获得焦点后再次获得焦点。

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

另请参阅 hasFocus()、setFocus() 和setFocusItem()。

[slot] void QGraphicsScene::clearSelection()

清除当前选定内容。

另请参阅 setSelectionArea() 和selectedItems()。

QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

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

项目按堆叠顺序从高到低返回（即列表中的第一个项目位于最上方，最后一个项目位于最下方）。

另请参阅 items()、itemAt()、QGraphicsItem::collidesWithItem() 以及Sorting 。

[virtual protected] void QGraphicsScene::contextMenuEvent(QGraphicsSceneContextMenuEvent *contextMenuEvent)

该事件处理程序（针对contextMenuEvent 事件）可在子类中重新实现，以接收上下文菜单事件。默认实现会将事件转发给位于事件发生位置处、且接受上下文菜单事件的最顶层可见项。如果该位置没有项接受上下文菜单事件，则忽略该事件。

注意：有关本函数如何判定哪些项目被视为可见的定义，请参阅items()。

另请参阅 QGraphicsItem::contextMenuEvent() 函数。

QGraphicsItemGroup *QGraphicsScene::createItemGroup(const QList<QGraphicsItem *> &items)

将items 中的所有项目组合到一个新的QGraphicsItemGroup 中，并返回该组的指针。 该组以items 的共同祖先作为父对象，并位于位置(0, 0)。所有项目均被重新关联至该组，其位置和变换也映射到该组。如果items 为空，则该函数将返回一个空的顶级QGraphicsItemGroup 。

QGraphicsScene 拥有该组项的所有权；您无需将其删除。要拆解（取消分组）一个组，请调用destroyItemGroup()。

另请参阅 destroyItemGroup() 和QGraphicsItemGroup::addToGroup()。

void QGraphicsScene::destroyItemGroup(QGraphicsItemGroup *group)

将group 中的所有项目重新归属到group 的父项目下，然后将group 从场景中移除，最后将其删除。项目的位置和变换会从该组映射到该组的父组。

另请参阅 createItemGroup() 和QGraphicsItemGroup::removeFromGroup()。

[virtual protected] void QGraphicsScene::dragEnterEvent(QGraphicsSceneDragDropEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收场景的拖入事件。

默认实现会接受该事件，并使场景做好准备以接收拖动移动事件。

另请参阅 QGraphicsItem::dragEnterEvent()、dragMoveEvent()、dragLeaveEvent() 和dropEvent()。

[virtual protected] void QGraphicsScene::dragLeaveEvent(QGraphicsSceneDragDropEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收场景的拖动离开事件。

另请参阅 QGraphicsItem::dragLeaveEvent()、dragEnterEvent()、dragMoveEvent() 以及dropEvent()。

[virtual protected] void QGraphicsScene::dragMoveEvent(QGraphicsSceneDragDropEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收场景的拖动移动事件。

注意：关于该函数将哪些项目视为可见的定义，请参见items()。

另请参阅 QGraphicsItem::dragMoveEvent()、dragEnterEvent()、dragLeaveEvent() 和dropEvent()。

[virtual protected] void QGraphicsScene::drawBackground(QPainter *painter, const QRectF &rect)

在绘制任何项目和前景之前，使用painter 绘制场景的背景。重写此函数可为场景提供自定义背景。

所有绘制操作均在场景坐标系中进行。rect 参数表示可见的矩形区域。

若您仅需为背景定义颜色、纹理或渐变，可改用setBackgroundBrush() 函数。

另请参阅 drawForeground() 和drawItems()。

[virtual protected] void QGraphicsScene::drawForeground(QPainter *painter, const QRectF &rect)

在绘制完背景和所有项目后，使用painter 绘制场景的前景。重写此函数可为场景提供自定义前景。

所有绘制操作均在场景坐标系中进行。rect 参数表示要绘制的矩形区域。

若您仅需为前景定义颜色、纹理或渐变，则可改用setForegroundBrush() 函数。

另请参阅 drawBackground() 和drawItems()。

[virtual protected] void QGraphicsScene::dropEvent(QGraphicsSceneDragDropEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收场景的拖放事件。

另请参阅 QGraphicsItem::dropEvent()、dragEnterEvent()、dragMoveEvent() 以及dragLeaveEvent()。

[override virtual protected] bool QGraphicsScene::event(QEvent *event)

重写：QObject::event(QEvent *e)。

处理事件event ，并将其分发给相应的事件处理程序。

除了调用便捷事件处理程序外，当没有鼠标抓取项时，此函数还负责将鼠标移动事件转换为悬停事件。悬停事件会直接传递给项；对此没有相应的便捷函数。

与QWidget 不同，QGraphicsScene 不提供enterEvent()和leaveEvent()这两个便捷函数。请改用此函数来获取这些事件。

如果已识别并处理event ，则返回true ；否则，返回false 。

另请参阅 contextMenuEvent()、keyPressEvent()、keyReleaseEvent()、mousePressEvent()、mouseMoveEvent()、mouseReleaseEvent()、mouseDoubleClickEvent()、focusInEvent() 以及focusOutEvent()函数 。

[override virtual protected] bool QGraphicsScene::eventFilter(QObject *watched, QEvent *event)

重写了：QObject::eventFilter(QObject *watched, QEvent *event)。

QGraphicsScene 过滤QApplication 的事件，以检测调色板和字体的变化。

[virtual protected] void QGraphicsScene::focusInEvent(QFocusEvent *focusEvent)

该事件处理程序（针对focusEvent 事件）可在子类中重新实现，以便在事件中获取焦点。

默认实现会将焦点设置在场景上，然后设置在最后一个焦点项目上。

另请参阅 QGraphicsItem::focusOutEvent()。

QGraphicsItem *QGraphicsScene::focusItem() const

当场景处于活动状态时，该函数返回场景的当前焦点项；如果当前没有项处于焦点状态，则返回nullptr 。当场景处于非活动状态时，该函数返回场景恢复活动状态时将获得输入焦点的项。

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

另请参阅 setFocusItem()、QGraphicsItem::hasFocus() 和isActive()。

[signal] void QGraphicsScene::focusItemChanged(QGraphicsItem *newFocusItem, QGraphicsItem *oldFocusItem, Qt::FocusReason reason)

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

oldFocusItem 是之前拥有焦点的项目的指针，如果在信号发出之前没有任何项目拥有焦点，则为 0。newFocusItem 是获得输入焦点的项目的指针，如果焦点丢失，则为nullptr 。reason 是焦点变化的原因（例如，如果输入字段拥有焦点时场景被停用，则oldFocusItem 将指向该输入字段项，newFocusItem 将指向nullptr ，而reason 将指向Qt::ActiveWindowFocusReason ）。

[virtual protected slot] bool QGraphicsScene::focusNextPrevChild(bool next)

查找一个新的控件以将键盘焦点移至该控件，以适应 Tab 和 Shift+Tab 键的操作；若找到新控件则返回true ，否则返回 false。如果next 为 true，则该函数向前搜索；如果next 为 false，则向后搜索。

您可以在 `QGraphicsScene ` 的子类中重写此函数，以便对场景内 Tab 焦点传递的方式进行精细控制。默认实现基于 `QGraphicsWidget::setTabOrder()` 定义的 Tab 焦点链。

[virtual protected] void QGraphicsScene::focusOutEvent(QFocusEvent *focusEvent)

该事件处理程序（针对事件focusEvent ）可在子类中重新实现，以接收焦点移出事件。

默认实现会先移除任何焦点项的焦点，然后移除场景的焦点。

另请参阅 QGraphicsItem::focusInEvent()。

bool QGraphicsScene::hasFocus() const

如果场景处于焦点状态，则返回true ；否则返回false 。如果场景处于焦点状态，它会将来自QKeyEvent 的键盘事件转发给任何处于焦点状态的项目。

另请参见 setFocus() 和setFocusItem()。

qreal QGraphicsScene::height() const

此便捷函数相当于调用sceneRect().height() 。

另请参阅 width()。

[virtual protected] void QGraphicsScene::helpEvent(QGraphicsSceneHelpEvent *helpEvent)

该事件处理程序（针对helpEvent 事件）可在子类中重新实现，以接收帮助事件。这些事件的类型为QEvent::ToolTip ，是在请求工具提示时生成的。

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

注意：关于该函数如何判定哪些项被视为可见，请参阅items()。

另请参阅 QGraphicsItem::toolTip() 和QGraphicsSceneHelpEvent 。

[virtual protected] void QGraphicsScene::inputMethodEvent(QInputMethodEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收场景的输入法事件。

默认实现会将事件转发给 `focusItem()`。如果当前没有项目获得焦点，或者当前获得焦点的项目不接受输入方法，则该函数不执行任何操作。

另请参阅 QGraphicsItem::inputMethodEvent()。

[virtual] QVariant QGraphicsScene::inputMethodQuery(Qt::InputMethodQuery query) const

输入法使用此方法查询场景的一组属性，以便支持“包围文本”和“重新转换”等复杂的输入法操作。

query 参数指定要查询的属性。

另请参阅 QWidget::inputMethodQuery()。

[slot] void QGraphicsScene::invalidate(const QRectF &rect = QRectF(), QGraphicsScene::SceneLayers layers = AllLayers)

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

您可以使用此函数重载来通知QGraphicsScene 场景背景或前景的变更。该函数通常用于具有瓦片式背景的场景，当QGraphicsView 启用了CacheBackground 时，用于通知相关变更。

示例：

QRectF TileScene::rectForTile(int x, int y) const
{
    // Return the rectangle for the tile at position (x, y).
    return QRectF(x * tileWidth, y * tileHeight, tileWidth, tileHeight);
}

void TileScene::setTile(int x, int y, const QPixmap &pixmap)
{
    // Sets or replaces the tile at position (x, y) with pixmap.
    if (x >= 0 && x < numTilesH && y >= 0 && y < numTilesV) {
        tiles[y][x] = pixmap;
        invalidate(rectForTile(x, y), BackgroundLayer);
    }
}

void TileScene::drawBackground(QPainter *painter, const QRectF &exposed)
{
    // Draws all tiles that intersect the exposed area.
    for (int y = 0; y < numTilesV; ++y) {
        for (int x = 0; x < numTilesH; ++x) {
            QRectF rect = rectForTile(x, y);
            if (exposed.intersects(rect))
                painter->drawPixmap(rect.topLeft(), tiles[y][x]);
        }
    }
}

请注意，QGraphicsView 目前仅支持背景缓存（参见QGraphicsView::CacheBackground ）。如果传入的图层中不包含BackgroundLayer ，则该函数等同于调用update()。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        graphicsScene, qOverload(&QGraphicsScene::invalidate));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        graphicsScene, [receiver = graphicsScene](const QRectF &rect, QGraphicsScene::SceneLayers layers) { receiver->invalidate(rect, layers); });

另请参阅 QGraphicsView::resetCachedContent()。

void QGraphicsScene::invalidate(qreal x, qreal y, qreal w, qreal h, QGraphicsScene::SceneLayers layers = AllLayers)

此便捷函数等同于调用 invalidate(QRectF(x,y,w,h),layers);

bool QGraphicsScene::isActive() const

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

另请参阅 QGraphicsItem::isActive() 和QWidget::isActiveWindow()。

QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const

返回位于指定坐标position 处的最顶层可见项；如果该位置没有项，则返回nullptr 。

deviceTransform 是应用于视图的变换，如果场景中包含忽略变换的项目，则必须提供该参数。

注意：关于本函数如何判定哪些项目被视为可见，请参阅items()。

另请参阅 items()、collidingItems(）以及Sorting 。

QGraphicsItem *QGraphicsScene::itemAt(qreal x, qreal y, const QTransform &deviceTransform) const

返回位于 (x,y) 指定位置处的最顶层可见项；如果该位置没有项，则返回nullptr 。

deviceTransform 是应用于视图的变换，如果场景中包含忽略变换的项目，则必须提供该变换。

此便捷函数等同于调用itemAt(QPointF(x, y), deviceTransform) 。

注意：关于该函数将哪些项目视为可见的定义，请参阅items()。

QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order = Qt::DescendingOrder) const

返回场景中所有元素的有序列表。order 决定堆叠顺序。

另请参阅 addItem()、removeItem() 以及Sorting 。

QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::DescendingOrder, const QTransform &deviceTransform = QTransform()) const

返回所有可见的项目，这些项目根据mode 的设置，位于指定的pos 位置，并按order 排序。在此情况下，“可见”指满足以下条件的项目：isVisible()返回true ，effectiveOpacity()返回大于0.0（即完全透明）的值，且父项目未对其进行裁剪。

mode 的默认值为Qt::IntersectsItemShape ；所有形状与pos 精确相交的项都会被返回。

deviceTransform 是应用于视图的变换，如果场景中包含忽略变换的项目，则必须提供该变换。

另请参阅 itemAt() 和Sorting 。

QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::DescendingOrder, const QTransform &deviceTransform = QTransform()) const

返回所有可见的项目，这些项目根据mode 的设置，要么位于指定的path 内部，要么与之相交，并按order 排序成列表。在此情况下，“可见”指满足以下条件的项目：isVisible()返回true ，effectiveOpacity()返回大于0.0（即完全透明）的值，且父项目未对其进行裁剪。

mode 的默认值为Qt::IntersectsItemShape ；所有形状与path 精确相交或被其完全包含的项都会被返回。

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

另请参阅 itemAt() 和Sorting 。

QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::DescendingOrder, const QTransform &deviceTransform = QTransform()) const

返回所有可见的项目，这些项目根据mode 的设置，要么位于指定的polygon 内部，要么与之相交，并按order 排序成列表。在此情况下，“可见”指满足以下条件的项目：isVisible()返回true ，effectiveOpacity()返回大于0.0（即完全透明）的值，且父项目未对其进行裁剪。

mode 的默认值为Qt::IntersectsItemShape ；所有与polygon 精确形状相交或被其包含的项都会被返回。

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

另请参阅 itemAt() 和Sorting 。

QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, Qt::SortOrder order = Qt::DescendingOrder, const QTransform &deviceTransform = QTransform()) const

返回所有可见的项目，这些项目根据mode 的设置，要么位于指定的rect 内部，要么与之相交，并按order 排序后以列表形式返回。在此情况下，“可见”指满足以下条件的项目：isVisible()返回true ，effectiveOpacity()返回大于0.0（即完全透明）的值，且其父项目未对其进行裁剪。

mode 的默认值为Qt::IntersectsItemShape ；所有形状与rect 精确相交或被其完全包含的项都会被返回。

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

另请参阅 itemAt() 和Sorting 。

QList<QGraphicsItem *> QGraphicsScene::items(qreal x, qreal y, qreal w, qreal h, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform = QTransform()) const

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

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

QRectF QGraphicsScene::itemsBoundingRect() const

计算并返回场景中所有项的边界矩形。该函数通过遍历所有项来工作，因此对于大型场景而言，其运行速度可能会较慢。

另请参阅 sceneRect()。

[virtual protected] void QGraphicsScene::keyPressEvent(QKeyEvent *keyEvent)

该事件处理程序（针对keyEvent 事件）可在子类中重新实现，以接收按键事件。默认实现会将事件转发给当前焦点项。

另请参阅 QGraphicsItem::keyPressEvent() 和focusItem()。

[virtual protected] void QGraphicsScene::keyReleaseEvent(QKeyEvent *keyEvent)

该事件处理程序（针对keyEvent 事件）可在子类中重新实现，以接收按键释放事件。默认实现会将事件转发给当前焦点项。

另请参阅 QGraphicsItem::keyReleaseEvent() 和focusItem()。

[virtual protected] void QGraphicsScene::mouseDoubleClickEvent(QGraphicsSceneMouseEvent *mouseEvent)

该事件处理程序（针对mouseEvent 事件）可在子类中重新实现，以接收场景的鼠标双击事件。

如果用户在场景上双击，场景将首先收到一个按键事件，随后是一个释放事件（即一次点击），然后是一个双击事件，最后是一个释放事件。 如果双击事件传递到的对象与接收第一个按下和释放事件的对象不同，则该事件将作为按下事件传递。但是，在这种情况下，三击事件不会作为双击事件传递。

默认实现与mousePressEvent() 类似。

注意：关于该函数将哪些项目视为可见的定义，请参阅items()。

另请参阅 QGraphicsItem::mousePressEvent()、QGraphicsItem::mouseMoveEvent()、QGraphicsItem::mouseReleaseEvent() 以及QGraphicsItem::setAcceptedMouseButtons()。

QGraphicsItem *QGraphicsScene::mouseGrabberItem() const

返回当前的鼠标捕获对象；如果当前没有对象捕获鼠标，则返回nullptr 。鼠标捕获对象是指接收发送到该场景的所有鼠标事件的对象。

当某个对象接收并接受了鼠标按下事件时，它便成为鼠标捕获对象，并一直保持该状态，直到发生以下任一事件为止：

• 如果该对象在没有其他按钮被按下的情况下接收到鼠标释放事件，则会失去鼠标捕获状态。
• 如果该对象变为不可见（即有人调用了item->setVisible(false) ），或者被禁用（即有人调用了item->setEnabled(false) ），它将失去鼠标捕获状态。
• 如果该项被从场景中移除，它将失去鼠标捕获状态。

如果该项目失去了鼠标捕获状态，场景将忽略所有鼠标事件，直到有一个新项目捕获了鼠标（即，直到有一个新项目接收到了鼠标按下事件）。

[virtual protected] void QGraphicsScene::mouseMoveEvent(QGraphicsSceneMouseEvent *mouseEvent)

该事件处理程序（针对mouseEvent 事件）可在子类中重新实现，以接收场景的鼠标移动事件。

默认实现取决于鼠标抓取器的状态。如果存在鼠标抓取器项，则将事件发送至鼠标抓取器；如果当前位置存在任何接受悬停事件的项，则将该事件转换为悬停事件并予以处理；否则将其忽略。

另请参阅 QGraphicsItem::mousePressEvent()、QGraphicsItem::mouseReleaseEvent()、QGraphicsItem::mouseDoubleClickEvent() 以及QGraphicsItem::setAcceptedMouseButtons()。

[virtual protected] void QGraphicsScene::mousePressEvent(QGraphicsSceneMouseEvent *mouseEvent)

该事件处理程序（针对mouseEvent 事件）可在子类中重新实现，以接收场景的鼠标按下事件。

默认实现取决于场景的状态。如果存在鼠标抓取项，则将事件发送给该鼠标抓取项。否则，事件将转发给位于场景中该事件位置处、且处于最顶层可见状态、并接受鼠标事件的项，该项随即成为鼠标抓取项。

如果场景中给定位置没有对象，则选择区域将被重置，任何具有焦点的对象将失去输入焦点，随后该事件将被忽略。

注意：关于本函数如何判定哪些项被视为可见，请参阅items()。

另请参阅 QGraphicsItem::mousePressEvent() 和QGraphicsItem::setAcceptedMouseButtons()。

[virtual protected] void QGraphicsScene::mouseReleaseEvent(QGraphicsSceneMouseEvent *mouseEvent)

该事件处理程序（针对mouseEvent 事件）可在子类中重新实现，以接收场景的鼠标释放事件。

默认实现取决于鼠标抓取器的状态。如果不存在鼠标抓取器，则忽略该事件。否则，如果存在鼠标抓取器项，则将该事件发送给鼠标抓取器。如果此次鼠标释放对应的是鼠标上最后按下的按钮，则鼠标抓取器项将释放该鼠标抓取。

另请参阅 QGraphicsItem::mousePressEvent()、QGraphicsItem::mouseMoveEvent()、QGraphicsItem::mouseDoubleClickEvent() 以及QGraphicsItem::setAcceptedMouseButtons()。

void QGraphicsScene::removeItem(QGraphicsItem *item)

从场景中移除对象item 及其所有子节点。item 的所有权将转移给调用方（即，当QGraphicsScene 被销毁时，将不再删除item ）。

另请参阅 addItem()。

void QGraphicsScene::render(QPainter *painter, const QRectF &target = QRectF(), const QRectF &source = QRectF(), Qt::AspectRatioMode aspectRatioMode = Qt::KeepAspectRatio)

使用painter 将场景中的source 矩形渲染到target 中。该函数可用于将场景内容捕获到绘图设备（如QImage ，例如用于截屏）上，或通过QPrinter进行打印。例如：

QGraphicsScene scene;
scene.addItem(someItem);
//...
QPrinter printer(QPrinter::HighResolution);
printer.setPageSize(QPageSize::A4);

QPainter painter(&printer);
scene.render(&painter);

如果 `source ` 为空矩形，该函数将使用 `sceneRect()` 来确定渲染内容。如果 `target ` 为空矩形，则将使用 `painter` 绘图设备的尺寸。

源矩形的内容将根据aspectRatioMode 进行变换，以适应目标矩形。默认情况下，纵横比将保持不变，且source 将进行缩放以适应target 。

另请参阅 QGraphicsView::render()。

[signal] void QGraphicsScene::sceneRectChanged(const QRectF &rect)

每当场景矩形发生变化时，QGraphicsScene 都会触发此信号。rect 参数即为新的场景矩形。

另请参阅 QGraphicsView::updateSceneRect()。

QList<QGraphicsItem *> QGraphicsScene::selectedItems() const

返回当前所有已选中项目的列表。这些项目返回的顺序不固定。

另请参阅 setSelectionArea()。

QPainterPath QGraphicsScene::selectionArea() const

返回先前通过 `setSelectionArea()` 设置的选择区域；如果未设置选择区域，则返回空的 `QPainterPath `。

另请参阅 setSelectionArea()。

[signal] void QGraphicsScene::selectionChanged()

每当选择状态发生变化时，QGraphicsScene 都会发出此信号。您可以调用selectedItems() 来获取新的选中项列表。

每当选中或取消选中某个项目、设置、清除或以其他方式更改选区、将预选项目添加到场景中，或者将选中项目从场景中移除时，选区都会发生变化。

QGraphicsScene 对于组选择操作，仅会触发一次此信号。例如，如果您设置了一个选择区域、选中或取消选中一个QGraphicsItemGroup ，或者向场景中添加或从场景中移除一个包含多个已选项目的父项目，则 selectionChanged() 仅在操作完成后触发一次（而不是针对每个项目分别触发一次）。

另请参阅 setSelectionArea()、selectedItems() 和QGraphicsItem::setSelected()。

bool QGraphicsScene::sendEvent(QGraphicsItem *item, QEvent *event)

通过可能的事件过滤器，向项目item 发送事件event 。

仅当该项目已启用时，才会发送该事件。

如果事件被过滤，或者项目处于禁用状态，则返回 `false `。否则，返回事件处理程序返回的值。

另请参阅 QGraphicsItem::sceneEvent() 和QGraphicsItem::sceneEventFilter()。

void QGraphicsScene::setActivePanel(QGraphicsItem *item)

激活item ，该面板必须是本场景中的一个元素。您也可以将item 的参数设为0，此时QGraphicsScene 将停用当前任何处于活动状态的面板。

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

另请参阅 activePanel()、isActive() 和QGraphicsItem::isActive()。

void QGraphicsScene::setActiveWindow(QGraphicsWidget *widget)

激活widget ，该对象必须是本场景中的控件。您也可以将widget 的参数设为0，此时QGraphicsScene 将关闭当前所有已激活的窗口。

另请参阅 activeWindow() 和QGraphicsWidget::isActiveWindow()。

void QGraphicsScene::setFocus(Qt::FocusReason focusReason = Qt::OtherFocusReason)

通过向场景发送QFocusEvent ，并将focusReason 作为原因，将焦点设置到该场景上。如果场景在某个项目拥有焦点时曾失去焦点，随后又重新获得焦点，则最后一个拥有焦点的项目将再次获得焦点，且原因将设置为focusReason 。

如果场景已处于焦点状态，则此函数不执行任何操作。

另请参阅 hasFocus()、clearFocus() 和setFocusItem()。

void QGraphicsScene::setFocusItem(QGraphicsItem *item, Qt::FocusReason focusReason = Qt::OtherFocusReason)

将场景的焦点项设置为item ，焦点原因设为focusReason ，同时先将焦点从任何可能曾拥有焦点的先前项上移开。

如果 `item ` 为 `nullptr`，或者该项不接受焦点（即未启用 `QGraphicsItem::ItemIsFocusable ` 标志），或者不可见或未启用，则此函数仅会从任何先前具有焦点的焦点项上移除焦点。

如果 item 不是nullptr ，且场景当前没有焦点（即hasFocus() 返回false ），则该函数将自动调用setFocus()。

另请参阅 focusItem()、hasFocus()和setFocus()。

void QGraphicsScene::setSelectionArea(const QPainterPath &path, const QTransform &deviceTransform)

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

deviceTransform 是应用于视图的变换，如果场景中包含忽略变换的项目，则必须提供该变换。

要使某个项目被选中，必须将其标记为可选中（QGraphicsItem::ItemIsSelectable ）。

另请参阅 clearSelection() 和selectionArea()。

void QGraphicsScene::setSelectionArea(const QPainterPath &path, Qt::ItemSelectionOperation selectionOperation = Qt::ReplaceSelection, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, const QTransform &deviceTransform = QTransform())

将选择区域设置为path ，并使用mode 来确定项目是否包含在选择区域内。

deviceTransform 是应用于视图的变换，如果场景中包含忽略变换的对象，则必须提供该变换。

selectionOperation 确定对当前选中的项目采取何种操作。

另请参阅 clearSelection() 和selectionArea()。

void QGraphicsScene::setStyle(QStyle *style)

将场景的样式设置或替换为style ，并将该样式重新关联至此场景。此前分配的任何样式均会被删除。场景的样式默认值为QApplication::style()，并作为场景中所有QGraphicsWidget 项的默认样式。

无论直接调用此函数，还是间接调用QApplication::setStyle() 来更改样式，系统都会自动更新场景中所有未被显式分配样式的控件的样式。

如果 `style ` 的值为 `nullptr`，则 `QGraphicsScene ` 将恢复为 `QApplication::style()`。

另请参阅 style()。

QStyle *QGraphicsScene::style() const

返回场景的样式；如果场景未被显式分配样式，则返回结果与QApplication::style() 相同。

另请参阅 setStyle()。

[slot] void QGraphicsScene::update(const QRectF &rect = QRectF())

安排对场景中rect 区域进行重绘。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        graphicsScene, qOverload(&QGraphicsScene::update));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        graphicsScene, [receiver = graphicsScene](const QRectF &rect) { receiver->update(rect); });

另请参阅 sceneRect() 和changed()。

void QGraphicsScene::update(qreal x, qreal y, qreal w, qreal h)

该函数等同于调用 update(QRectF(x,y,w,h));

QList<QGraphicsView *> QGraphicsScene::views() const

返回一个包含所有显示此场景的视图的列表。

另请参阅 QGraphicsView::scene()。

[virtual protected] void QGraphicsScene::wheelEvent(QGraphicsSceneWheelEvent *wheelEvent)

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

默认情况下，该事件将传递给光标下方的最顶层可见项目。如果被忽略，该事件将向下传播至下一个项目，并重复此过程，直到有项目接受该事件，或者事件传播至场景本身。如果没有项目接受该事件，则该事件将被忽略。

注意：关于该函数将哪些项视为可见的定义，请参阅items()。

另请参阅 QGraphicsItem::wheelEvent()。

qreal QGraphicsScene::width() const

此便捷函数相当于调用sceneRect().width()。

另请参阅 height()。