Qt图形视图框架：QGraphicsScene详解

2023-11-06

一、描述

1、场景提供了一个用于管理大量2D图形项的平面。该类充当图形项的容器。它与视图一起用于可视化2D曲面上的图形图形项。

2、场景没有自己的视觉外观，只负责管理图形项。

3、场景的最大优势之一就是其快速有效地定位图形项的能力。即使场景中有数百万个图形项。

4、场景的另一个职责是传播来自视图的事件。要将事件发送到场景，可以构造一个继承QEvent的事件，然后使用QApplication::sendEvent()将其发送。event()负责将事件调度到各个图形项。

二、类型成员

1、QGraphicsScene::ItemIndexMethod：场景的索引算法。

QGraphicsScene::BspTreeIndex：二进制空间分区树算法。所有图形项定位算法的数量级都接近对数复杂度。添加，移动和删除图形项是对数的。这种方法最适合静态场景（即大多数图形项不移动的场景）。
QGraphicsScene::NoIndex：不保存图形项索引。定位图形项具有线性复杂性，因为会搜索场景中的所有图形项。但是，添加，移动和删除图形项是在固定时间内完成的。这种方法最适合动态场景，在动态场景中，要连续添加，移动或删除许多图形项。

2、QGraphicsScene::SceneLayer：该枚举描述了场景中的渲染层。当场景在绘制内容时，它将按顺序分别渲染每个图层。每一层代表一个标志。

绘制顺序：背景 > 图形项 > 前景。

QGraphicsScene::ItemLayer：图形项层。场景通过调用虚函数drawItems()来渲染的所有图形项在此层中。图形项层绘制在背景层之后，但在前景层之前。
QGraphicsScene::BackgroundLayer：背景层。场景通过调用虚函数drawBackground()在此层中渲染场景的背景。首先绘制的是背景层。
QGraphicsScene::ForegroundLayer：前景层。场景通过调用虚函数drawForeground()在此层中渲染场景的前景。前景层绘制在所有层的最后。
QGraphicsScene::AllLayers：所有层，该值代表所有三层的组合。

三、属性成员

1、backgroundBrush : QBrush

背景层画刷。例如可以它设置场景的背景网格：

    gphs->setBackgroundBrush(QBrush(QPixmap(":/background1.png")));

2、bspTreeDepth : int

BSP索引树的深度。使用QGraphicsScene::NoIndex时，此属性无效。

深度直接影响场景的性能和内存使用情况。后者随树的深度呈指数增长。凭借最佳的树深度，场景可以立即确定图形项的位置，甚至对于具有数千或数百万个图形项的场景也是如此。这也大大提高了渲染性能。

默认情况下，该值为0，在这种情况下，Qt将根据场景中图形项的大小，位置和数量猜测一个合理的默认深度。但是，如果这些参数频繁更改，则场景会在内部重新调整深度时，可能会遇到速度变慢的情况。可以通过设置此属性来固定树的深度，从而避免潜在的速度下降。

3、focusOnTouch : bool

此属性保存图形项在接收到触摸开始事件（移动设备）时是否获得焦点。通常的行为是仅在单击图形项时转移焦点。

4、font : QFont

场景的字体。更改对一般图形项无影响，只对QGraphicsWidget中嵌入的QWidget有影响。

5、foregroundBrush : QBrush

前景画刷。前景层在图形项层前面的，所以设置的前景画刷会挡住图形项。

    gphs->setForegroundBrush(QColor(255, 0, 0, 127));
    gphs->setForegroundBrush(QBrush(Qt::lightGray, Qt::CrossPattern));

6、minimumRenderSize : qreal

必须绘制的最小渲染大小。渲染场景时，其宽度或高度小于此值的任何图形项都不会被渲染。默认值为0。如果未设置，或者设置为0或负值，则将始终呈现所有图形项。由于太小而未绘制的图形项仍会由items()和itemAt()之类的方法返回，并参与碰撞检测和交互。

7、palette : QPalette

场景的调色板。更改对一般图形项无影响，只对QGraphicsWidget中嵌入的QWidget有影响。

8、sceneRect : QRectF

场景的边界矩形。场景边界矩形定义场景的范围。视图主要使用它来确定视图的默认可滚动区域，场景主要使用它来管理图形项索引。如果未设置或者设置为无效的矩形则SceneRect()将返回自创建场景以来场景中所有图形项的最大边界矩形（即当在场景中添加或移动图形项时矩形会增大，但是永不减小）。

9、stickyFocus : bool （实用）

单击场景背景是否会清除焦点。

四、成员函数

1、void advance()

调用场景中所有图形项的QGraphicsItem::advance()函数。

2、[信号] void changed(const QList<QRectF> &region)

场景内容发生更改时发出的信号（场景任何更改都会发此信号，此信号发送极其频繁）。参数包含场景矩形的列表，这些矩形指示已更改的区域。

3、void clear()

从场景中删除所有图形项。（移除并且delete删除）

4、void clearSelection()

清除当前选择状态。

5、[信号] void focusItemChanged(QGraphicsItem *newFocusItem, QGraphicsItem *oldFocusItem, Qt::FocusReason reason)

每当场景中的焦点发生变化时（某项获得或失去输入焦点时（涉及一个图形项），或者当焦点从一个图形项传递到另一个图形项时（涉及两个图形项）），场景都会发出此信号。如果需要跟踪其他图形项何时获得输入焦点，则可以连接到此信号。

oldFocusItem是指向以前具有焦点的图形项的指针，如果在发出信号之前没有图形项具有焦点，则为nullptr。newFocusItem是指向获得输入焦点的图形项的指针；如果焦点丢失，则返回nullptr。参数3见QGraphicsItem详解的第61个成员函数。

6、bool focusNextPrevChild(bool next)

查找一个新的QGraphicsWidget，以使键盘焦点对准Tab和Shift + Tab键，如果可以找到则返回true；否则返回false。如果next为true则此函数向前搜索，否则向后搜索。

7、void invalidate(const QRectF &rect = QRectF(), QGraphicsScene::SceneLayers layers = AllLayers)

使场景中的rect无效并重绘。图层中的所有缓存内容都将无条件无效并重新绘制。

8、[信号] void sceneRectChanged(const QRectF &rect)

场景矩形发生变化时发出此信号。参数是新的场景矩形。

9、[信号] void selectionChanged()

选择改变时发出这个信号。可以调用selectedItems()来获取所选图形项的新列表。无论何时选择或取消选择图形项、设置、清除或以其他方式更改选择区域、将预选图形项添加到场景或从场景中移除选定图形项，选择都会改变。

对于组选择操作，场景只发出一次此信号。

10、void update(const QRectF &rect = QRectF())

重绘参数中的区域。

11、~QGraphicsScene()

析构函数。在销毁场景对象之前，从场景对象中删除并删除所有图形项。场景对象从所有关联的视图中删除。

12、QGraphicsItem *activePanel()

返回当前活动的面板。

13、QGraphicsWidget *activeWindow()

返回当前活动的窗口。

14、void addItem(QGraphicsItem *item)

将图形项及其所有子项添加或移动到此场景。如果该项是可见的（即QGraphicsItem::isVisible()返回true）。

如果该图形项已经在其他场景中，则它将首先从其旧场景中删除，然后作为顶层添加到该场景中。

当图形项添加到场景中时，场景将向图形项发送ItemSceneChange通知。

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

15、void clearFocus()

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

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

返回与参数1碰撞的所有图形项的列表。碰撞是通过调用QGraphicsItem::collidesWithItem()确定的。碰撞检测由模式决定。默认情况下，将返回形状与图形项相交或包含在图形项形状内的所有图形项。

17、QGraphicsItemGroup *createItemGroup(const QList<QGraphicsItem *> &items)

将参数列表中的所有图形项分组到一个新的组中，并返回指向该组的指针。

18、void destroyItemGroup(QGraphicsItemGroup *group)

从场景中删除组。组中的图形项移到组的父级。

19、void drawBackground(QPainter *painter, const QRectF &rect) （虚函数）

绘制场景的背景层。所有绘制都在场景坐标中完成。rect参数是暴露的矩形。

20、void drawForeground(QPainter *painter, const QRectF &rect) （虚函数）

绘制场景的前景层。所有绘制都在场景坐标中完成。rect参数是暴露的矩形。

21、QGraphicsItem *focusItem()

当场景处于活动状态时，此函数将返回场景的当前焦点项，如果当前没有焦点，则返回nullptr。当场景处于非活动状态时，此函数返回在场景变为活动状态时将获得输入焦点的图形项。当场景接收到按键事件时，焦点项将接收键盘输入。

22、bool hasFocus()

场景是否有焦点。如果场景有焦点，它将把按键事件从QKeyEvent转发到有焦点的图形项。

23、qreal height() / qreal width()

sceneRect()的宽 / 高。

24、QVariant inputMethodQuery(Qt::InputMethodQuery query)

输入法使用此方法来查询场景的一组属性，以便能够支持复杂的输入法操作。

25、bool isActive()

如果场景处于活动状态（例如，至少有一个QGraphicsView处于活动状态），则返回true，否则返回false。

26、QGraphicsItem *itemAt(const QPointF &position, const QTransform &deviceTransform)

返回指定位置最上面的可见项，如果此位置没有项，则返回nullptr。deviceTransform是应用于视图的变换。

27、QList<QGraphicsItem *> items(Qt::SortOrder order = Qt::DescendingOrder)

返回场景中所有图形项的有序列表。顺序由堆放顺序决定。

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

返回在参数1位置的使用可见项（effectiveOpacity() > 0的图形项）（见QGraphicsItem详解的第65个成员函数）。

参数2是与参数1相交的方式，见下面第42个函数。

参数3是按堆叠顺序排序方式。

Qt::SortOrder：此枚举描述了排序方式。

Qt::AscendingOrder：升序。
Qt::DescendingOrder：降序。

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

28的重载函数。

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

28的重载函数。

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

28的重载函数。

32、QRectF itemsBoundingRect()

计算并返回场景中所有图形项的边界矩形。此功能通过遍历所有图形项而起作用，因此对于大型场景，它可能会很慢。

33、QGraphicsItem *mouseGrabberItem()

返回当前的鼠标抓取器图形项。鼠标抓取器图形项是接收发送到场景的所有鼠标事件的图形项。

当一个图形项接收并接受鼠标按下事件时，它便成为鼠标抓取器，并且在发生以下事件之一之前，它将一直保留在鼠标抓取器中：

没有其他鼠标按钮按下的情况下图形项收到鼠标释放事件。

图形项变为不可见或者被禁用。

图形项从场景中删除。

34、void removeItem(QGraphicsItem *item)

从场景中删除该图形项及其所有子项。图形项的所有权将传递给调用方（即场景在销毁时将不再删除该图形项）。

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

使用Painter将源rect从场景渲染到target。

如果source是一个空矩形，则此函数将使用sceneRect()确定要渲染的内容。

如果target是一个空矩形，则将使用painter的绘画设备的尺寸。

源rect内容将根据AspectRatioMode进行转换以适合目标rect。默认情况下，将保留宽高比，并缩放源以适合目标。

此功能对于将场景的内容捕获到绘图设备（例如QImage）（例如截取屏幕截图）或使用QPrinter进行打印很有用。例如：

 QGraphicsScene scene;
 scene.addItem(...
 ...
 QPrinter printer(QPrinter::HighResolution);
 printer.setPaperSize(QPrinter::A4);

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

36、QList<QGraphicsItem *> selectedItems()

返回所有当前选定图形项的列表。图形项以不特定的顺序返回。

37、void setActivePanel(QGraphicsItem *item)

激活场景中的图形项。若传入nullptr，场景将停用任何当前活动的面板。如果场景当前处于非活动状态，则图形项将保持不活动状态，直到场景变为活动状态为止。

38、void setActiveWindow(QGraphicsWidget *widget)

激活场景中的小部件。若传入nullptr，场景将停用任何当前活动的窗口。

39、void setFocus(Qt::FocusReason focusReason = Qt::OtherFocusReason)

通过将QFocusEvent发送到场景，并将focusReason作为焦点变化的原因，从而将焦点设置在场景上。

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

从可能具有焦点的任何先前图形项中移除焦点之后，将场景的焦点图形项设置为参数1是图形项。

如果参数1为nullptr，或者它不接受焦点（即它没有启用QGraphicsItem::ItemIsFocusable标志），或者不可见或未启用，则此函数仅将焦点从任何先前的focusitem中移除。

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

41、void setSelectionArea(const QPainterPath &path, const QTransform &deviceTransform)

将选择区域设置为路径。该区域内的所有图形项都将立即被选中，外部的所有图形项都将被取消选中。对于要选择的图形项，必须将其标记为可选择的（QGraphicsItem :: ItemIsSelectable）。

42、void setSelectionArea(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape, const QTransform &deviceTransform = QTransform())

重载函数。参数2为选择模式。

Qt::ItemSelectionMode：图形视图框架中使用此枚举来指定如何选择图形项或如何确定形状和图形项是否碰撞。

Qt::ContainsItemShape：输出形状（QGraphicsItem::shape()）完全包含在选择区域内的图形项，与区域轮廓相交的图形项不包括在内。
Qt::IntersectsItemShape：输出形状（QGraphicsItem::shape()）完全包含在选择区域内的图形项以及与该区域的轮廓相交的图形项。这是框选的常见模式。
Qt::ContainsItemBoundingRect：输出边界矩形（QGraphicsItem::boundingRect()）完全包含在选择区域内的图形项。与区域轮廓相交的图形项不包括在内。
Qt::IntersectsItemBoundingRect：输出边界矩形（QGraphicsItem::boundingRect()）完全包含在选择区域内的图形项与包含与该区域的轮廓相交的图形项。此方法通常用于确定需要重绘的区域。

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

重载函数，参数2确定如何处理当前选定的图形项。

Qt::ItemSelectionOperation：场景中使用此枚举来指定设置选择区域时如何处理当前选择的图形项。

Qt::ReplaceSelection：当前选中的图形项被取消选中，指定区域的图形项被选中。
Qt::AddToSelection：当前选中的图形项状态不变，指定区域的图形项被选中。

44、void setStyle(QStyle *style)

为场景中的QGraphicsWidget设置样式。

45、QList<QGraphicsView *> views()

获取展示当前场景的视图列表。

五、事件成员函数

1、void contextMenuEvent(QGraphicsSceneContextMenuEvent *contextMenuEvent)

上下文菜单事件。默认实现将事件转发到最顶部可见的图形项。如果在此位置没有任何图形项接受上下文菜单事件，则该事件将被忽略。

2、void dragEnterEvent(QGraphicsSceneDragDropEvent *event)

拖拽进入事件。默认实现接受事件。

3、void dragLeaveEvent(QGraphicsSceneDragDropEvent *event)

拖拽离开事件。

4、void dragMoveEvent(QGraphicsSceneDragDropEvent *event)

拖动移动事件。

5、void dropEvent(QGraphicsSceneDragDropEvent *event)

拖拽放下事件。

6、bool event(QEvent *event)

实现自QObject::event()。处理事件事件，并将其分派到相应的事件处理程序。除了调用便捷事件处理函数之外，此函数还负责在没有鼠标抓取器项时将鼠标移动事件转换为鼠标悬停事件。鼠标悬停事件直接传递给图形项。场景没有鼠标进入、鼠标悬停、鼠标离开事件的便捷处理函数，这几种事件在event()中处理。

7、bool eventFilter(QObject *watched, QEvent *event)

实现自QObject::eventFilter()。场景过滤QApplication的事件以检测调色板和字体更改。

8、void focusInEvent(QFocusEvent *focusEvent)

接收焦点事件。默认实现将焦点设置在场景上，然后设置在最后一个焦点项（上一次失去焦点之前最后获得焦点的图形项）上。

9、void helpEvent(QGraphicsSceneHelpEvent *helpEvent)

帮助事件。事件的类型为QEvent::ToolTip，它是在请求工具提示时创建的。默认实现在鼠标光标位置显示最上面可见项（z值最高的项）的工具提示。如果没有项设置工具提示，则此函数不执行任何操作。

10、void inputMethodEvent(QInputMethodEvent *event)

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

11、void keyPressEvent(QKeyEvent *keyEvent)

键盘按下事件。默认实现将事件转发到当前焦点图形项。

12、void keyReleaseEvent(QKeyEvent *keyEvent)

按键释放事件。默认实现将事件转发到当前焦点图形项。

13、void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *mouseEvent)

鼠标双击事件。事件过程：双击场景-->场景将首先收到鼠标按下事件-->然后收到释放事件（即单击）-->然后是双击事件-->最后是释放事件。

14、void mouseMoveEvent(QGraphicsSceneMouseEven按下后的t *mouseEvent)

鼠标移动事件（不用按下只移动就能触发）。默认实现取决于鼠标抓取器状态。如果存在鼠标抓取器图形项，则事件将发送到鼠标采集器。如果在当前位置有任何接受悬停事件的图形项，则将该事件转换为悬停事件并接受。

15、void mousePressEvent(QGraphicsSceneMouseEvent *mouseEvent)

鼠标按下事件。默认实现取决于场景的状态。如果存在鼠标抓取器图形项，则事件将发送到鼠标抓取器。否则，它将转发到从事件开始的场景位置处接受鼠标事件的最上面可见的图形项，并且该图形项成为鼠标抓取器图形项。如果场景中给定位置上没有任何图形项，则重置选择区域，任何焦点图形项都会失去其输入焦点，然后事件将被忽略。

16、void mouseReleaseEvent(QGraphicsSceneMouseEvent *mouseEvent)

鼠标释放事件。默认实现取决于鼠标抓取器状态。如果没有鼠标抓取器，则将忽略该事件。如果有鼠标抓取器图形项，则事件将发送到鼠标抓取器图形项。

17、bool sendEvent(QGraphicsItem *item, QEvent *event)

将某事件发送给图形项，如果事件已被过滤或该图形项被禁用，则返回false。否则，返回事件处理程序返回的值。用法类似于QAppliction::postEvent()发送事件：

    qApp->postEvent(this, event);

18、void wheelEvent(QGraphicsSceneWheelEvent *wheelEvent)

鼠标滚轮事件。默认情况下，事件传递到光标下最上面的可见图形项。如果忽略，事件讲往下传播，直到事件被接受或到达场景。如果没有图形项接受该事件，则忽略该事件。

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)