Qt图形视图框架：QGraphicsWidget详解

一、描述

1、QGraphicsWidget 是一个扩展的基础项，它在 QGraphicsItem 之上提供额外的功能。 它在很多方面与 QWidget 相似：

• 提供调色板、字体、样式。
• 有geometry()。
• 可使用 setLayout() 和 layout()支持布局。
• 支持使用grabShortcut() 和insertAction() 的快捷键和QAction。
• 与QGraphicsItem不同，QGraphicsWidget不是抽象类。

2、由于QGraphicsWidget与QWidget类似并且具有相似的API，因此将小部件从QWidget移植到QGraphicsWidget比QGraphicsItem更为容易。

3、QGraphicsWidget默认支持的Qt小部件属性如下：

• Qt::WA_RightToLeft：表示窗口小部件的布局方向是从右到左。
• Qt::WA_SetStyle：表示小部件具有自己的样式。如果设置了此属性（由setStyle()设置），则小部件已明确分配了样式。如果未设置，则小部件将使用场景或应用程序的样式。
• Qt::WA_Resized：表示小部件具有明确的大小。
• Qt::WA_SetPalette：表示小部件有自己的调色板。
• Qt::WA_SetFont：表示小部件有自己的字体。
• Qt::WA_WindowPropagation：使顶层窗口从其父级继承字体、调色板和区域设置。

4、尽管QGraphicsWidget继承自QObject和QGraphicsItem（这俩都有一套自己的管理子项的系统），但是应该使用QGraphicsItem提供的功能（而不是QObject）来管理父项和子项之间的关系。由QGraphicsItem的函数控制图形项的堆叠顺序及其所有权。

二、属性成员

1、autoFillBackground : bool

是否自动填充小部件背景。如果启用，此属性将导致 Qt 在调用paint() 方法之前填充小部件的背景。使用的颜色由小部件调色板中的 QPalette::Window 颜色角色定义。QGraphicsWidget总是用QPalette::Window 填充，除非设置了 WA_OpaquePaintEvent 属性（属性）。默认此属性为 false。

2、focusPolicy : Qt::FocusPolicy

接受键盘焦点的策略（焦点策略Qt::FocusPolicy）。

如果小部件处理键盘事件，则必须为小部件启用键盘焦点例如，QLineEdit 构造函数调用 setFocusPolicy(Qt::StrongFocus)。

如果您启用焦点策略（即，不是Qt::NoFocus），QGraphicsWidget 将自动启用 ItemIsFocusable 标志（图形项标志）。在小部件上设置 Qt::NoFocus 将清除 ItemIsFocusable 标志。

 3、font : QFont

小部件的字体。此属性由显式定义的字体属性和从窗口小部件的父级隐式继承的属性组成。 因此，与使用 setFont()设置的字体相比，font()可以返回不同的字体。 此方案允许您在字体中定义单个条目，而不会影响字体的继承条目。

当小部件的字体更改时，它会根据其父小部件解析其条目。 如果小部件没有父小部件，它会根据场景解析其条目。 然后小部件向自己发送一个FontChange()事件并通知它的所有后代，以便他们也可以解析他们的字体。默认情况下，此属性包含应用程序的默认字体。

4、geometry : QRectF

小部件的几何形状。将图形项的几何体设置为矩形。调用此函数会修改图形项的位置和大小。该图形项首先移动，然后调整大小。调用此函数的一个副作用是小部件将接收一个移动事件和一个调整大小事件。 此外，如果小部件分配了布局，则布局将激活。

5、layout : QGraphicsLayout*

小部件的布局。QGraphicsWidget 拥有布局的所有权。

6、maximumSize : const QSizeF / minimumSize : const QSizeF / preferredSize : const QSizeF

小部件的最大 / 最小 / 首选尺寸。

7、palette : QPalette

小部件的调色板。调色板为颜色组提供颜色和画笔，定义小部件及其子项的一般外观。QPalette 由显式定义的颜色组和从窗口小部件的父级隐式继承的组组成。 因此，palette() 可以返回与 setPalette() 设置不同的调色板。当小部件的调色板更改时，它会根据其父小部件解析其条目，或者如果它没有父小部件，则会针对场景进行解析。 然后它向自己发送一个 PaletteChange() 事件，并通知它的所有后代，以便他们也可以解析他们的调色板。默认情况下，此属性包含应用程序的默认调色板。

8、size : QSizeF

小部件的大小。此属性仅影响小部件的宽度和高度。小部件的位置和左上角不受影响。调整小部件的大小会触发GraphicsSceneResize() 事件。

9、sizePolicy : QSizePolicy

大小策略。

10、windowFlags : Qt::WindowFlags

窗口标志。窗口标志是一个窗口类型（如 Qt::Dialog）和几个提供窗口行为提示的标志的组合。默认情况下，此属性不包含窗口标志。窗户是面板，如果设置了Qt::Window标志，则 ItemIsPanel（图形项标志） 标志将自动设置。如果清除 Qt::Window 标志，则 ItemIsPanel 标志也会被清除。 注意，ItemIsPanel 标志可以独立于 Qt::Window 设置。

11、windowTitle : QString

窗口标题。此属性仅用于窗口。

三、成员函数

1、void addAction(QAction *action) / void addActions(QList actions)

添加动作到QAction列表。QGraphicsWidgets 有一个 QActions 列表。

2、void adjustSize()

将小部件的大小调整为其有效的首选大小（effectiveSizeHint(Qt::PreferredSize)（QGraphicsLayoutItem））。当图形项第一次显示时，这个函数被隐式调用。

3、bool close()

关闭小部件。如果小部件成功关闭，则返回 true，否则返回false。首先向小部件发送一个 QCloseEvent，该小部件可能接受也可能不接受该事件。如果事件被忽略，则不做任何操作。如果事件被接受，它将关闭小部件。如果小部件设置了 Qt::WA_DeleteOnClose 属性，它将被删除。

4、[虚函数] bool focusNextPrevChild(bool next)

按下 Tab 和 Shift+Tab，查找一个新的小部件以将键盘焦点置于其上，如果可以找到新的小部件，则返回 true否则返回 false。如果 next 为true，则向前搜索否则向后搜索。

5、QGraphicsWidget *focusWidget()

如果此小部件、此小部件的子代或后代当前具有输入焦点，则此函数将返回指向该小部件的指针。

6、[信号] void geometryChanged()

只要在 setGeometry() 中更改几何图形，就会发出此信号。

7、void getWindowFrameMargins(qreal *left, qreal *top, qreal *right, qreal *bottom)

获取小部件的窗口边距。

8、int grabShortcut(const QKeySequence &sequence, Qt::ShortcutContext context = Qt::WindowShortcut)

向 Qt 的快捷系统添加一个快捷键（QKeySequence是封装了快捷键按键信息的类），该系统在给定的环境（参数2）中监视给定的键序列。

Qt::ShortcutContext：快捷键所处的环境。

• Qt::WidgetShortcut：当父小部件具有焦点时，快捷键处于活动状态。
• Qt::WidgetWithChildrenShortcut：当父小部件或其任何子部件具有焦点时，快捷键处于活动状态。
• Qt::WindowShortcut：对于不属于窗口的小部件（即顶级小部件及其子部件），快捷键适用于场景。
• Qt::ApplicationShortcut：快捷键适用于整个应用程序。

9、void initStyleOption(QStyleOption *option)

根据样式设置对象（QStyleOption）设置QGraphicsWidget对象的小部件样式。QStyleOption对象有如下成员：

默认会用这些成员设置QGraphicsWidget的以下属性：

• state & QStyle::State_Enabled：isEnabled()
• state & QStyle::State_HasFocus：hasFocus()
• state & QStyle::State_MouseOver：isUnderMouse()
• direction：layoutDirection()
• rect：rect().toRect()
• palette：palette()
• fontMetrics：QFontMetrics(font())

10、void insertAction(QAction *before, QAction *action) / void insertActions(QAction *before, QList actions)

将参数2的动作插入到参数1的动作之前。如果before == nullptr或before不是当前小部件的动作则在动作列表后面追加。

11、bool isActiveWindow()

小部件的窗口位于活动窗口中，或者小部件没有窗口但位于活动场景（即当前具有焦点的场景）中，则返回 true。（活动窗口是包含当前具有输入焦点的子窗口小部件或本身具有输入焦点的窗口）

12、[虚函数] void paintWindowFrame(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr)

由场景调用，在本地坐标中为窗口绘制窗口边框。基本实现使用当前样式来呈现边框和标题栏。

13、void removeAction(QAction *action)

移除动作。

14、void resize(qreal w, qreal h)

重设宽高。

15、void setAttribute(Qt::WidgetAttribute attribute, bool on = true)

如果 on 为true，则此函数启用属性，否则属性被禁用。实用的属性

16、void setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)

设置左、上、右、下的内容边距。布局使用内容边距来定义子小部件和布局的位置。

17、void setLayout(QGraphicsLayout *layout)

设置布局。在分配新布局之前，将删除任何现有布局管理器。QGraphicsWidget 拥有布局的所有权。

18、[static] void setTabOrder(QGraphicsWidget * A, QGraphicsWidget * B)

设置当按下tab键时焦点从A移到B。

设置焦点a->b->c->d移动：

 setTabOrder(a, b); // a -> b
 setTabOrder(b, c); // a -> b -> c
 setTabOrder(c, d); // a -> b -> c -> d

19、void setWindowFrameMargins(QMarginsF margins)

设置小部件窗口边距。默认边距由样式提供，取决于当前窗口标志。如果您想绘制自己的窗口样式，可以设置自己的框架边距以覆盖默认边距。

20、bool testAttribute(Qt::WidgetAttribute attribute)

返回小部件是否启用了属性。

21、void unsetWindowFrameMargins()

将边框边距重置为样式提供的默认值。

四、事件成员函数

1、void changeEvent(QEvent *event)

状态更改事件。包括：

• QEvent::ActivationChange
• QEvent::EnabledChange
• QEvent::FontChange
• QEvent::StyleChange
• QEvent::PaletteChange
• QEvent::ParentChange
• QEvent::LayoutDirectionChange
• QEvent::ContentsRectChange

2、void closeEvent(QCloseEvent *event)

小部件关闭事件。默认实现接受事件。

3、bool event(QEvent *event)

处理事件。可处理以下事件：

• QEvent::Polish
• QEvent::GraphicsSceneMove：在场景中的位置改变。
• QEvent::GraphicsSceneResize：在场景中的尺寸改变。
• QEvent::Show：小部件显示在屏幕上了。
• QEvent::Hide：小部件隐藏了。
• QEvent::PaletteChange：调色板改变。
• QEvent::FontChange：字体改变。
• QEvent::EnabledChange：启用状态改变。
• QEvent::StyleChange：样式改变。
• QEvent::LayoutDirectionChange：布局方向改变。
• QEvent::ContentsRectChange：内容边距/范围改变。

4、void grabKeyboardEvent(QEvent *event)

处理QEvent::GrabKeyboard （图形项获取键盘抓取）事件。

5、void grabMouseEvent(QEvent *event)

处理QEvent::GrabMouse（图形项获取鼠标抓取）事件。

6、void hideEvent(QHideEvent *event)

隐藏事件。在事件上调用 QEvent::accept() 或 QEvent::ignore() 无效。

7、void moveEvent(QGraphicsSceneMoveEvent *event)

移动事件。仅当图形项本身移动时才会传递此事件。调用 setTransform() 或移动任何图形项的祖先都不会影响图形项的本地位置。在事件上调用 QEvent::accept() 或 QEvent::ignore() 无效。

8、void polishEvent()

该事件在图形项构建之后的某个时间点由场景传递给图形项，此事件的作用是图形项在显示之前进行最后的初始化操作。

9、void resizeEvent(QGraphicsSceneResizeEvent *event)

调整大小事件。只有在本地调整小部件大小时才会传递此事件。在小部件或其任何祖先或视图上调用 setTransform() 不会影响小部件的本地大小。在事件上调用 QEvent::accept() 或 QEvent::ignore() 无效。

10、bool sceneEvent(QEvent *event)

从 QGraphicsItem::sceneEvent() 重新实现。QGraphicsWidget 的sceneEvent() 实现只是将事件传递给QGraphicsWidget::event()。不应该在 QGraphicsWidget 的子类中重新实现这个函数。

11、void showEvent(QShowEvent *event)

显示事件。在显示小部件之前传递此事件。 在事件上调用 QEvent::accept() 或 QEvent::ignore() 无效。

12、void ungrabKeyboardEvent(QEvent *event)

处理失去键盘抓取事件QEvent::UngrabKeyboard。

13、void ungrabMouseEvent(QEvent *event)

处理失去鼠标抓取事件QEvent::UngrabMouse。

14、bool windowFrameEvent(QEvent *event)

处理窗口框架的事件。它的基本实现提供了对默认窗口框架交互的支持，例如移动、调整大小等。