QGraphicsLayout Class
QGraphicsLayout 类为图形视图中的所有布局提供了基类。更多
头文件: | #include <QGraphicsLayout> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
qmake: | QT += widgets |
继承: | QGraphicsLayoutItem |
继承于 | QGraphicsAnchorLayout,QGraphicsGridLayout, 以及QGraphicsLinearLayout |
公共函数
QGraphicsLayout(QGraphicsLayoutItem *parent = nullptr) | |
virtual | ~QGraphicsLayout() |
void | activate() |
virtual int | count() const = 0 |
virtual void | invalidate() |
bool | isActivated() const |
virtual QGraphicsLayoutItem * | itemAt(int i) const = 0 |
virtual void | removeAt(int index) = 0 |
void | setContentsMargins(qreal left, qreal top, qreal right, qreal bottom) |
virtual void | widgetEvent(QEvent *e) |
重新实现的公共函数
virtual void | getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const override |
virtual void | updateGeometry() override |
受保护函数
void | addChildLayoutItem(QGraphicsLayoutItem *layoutItem) |
详细说明
QGraphicsLayout 是一个抽象类,它定义了一个虚拟 API,用于为QGraphicsWidget 安排QGraphicsWidget 子对象和其他QGraphicsLayoutItem 对象。QGraphicsWidget 通过QGraphicsWidget::setLayout() 将责任分配给 QGraphicsLayout。在调整 widget 的大小时,布局会自动安排 widget 的子对象。QGraphicsLayout 继承于QGraphicsLayoutItem ,因此它可以被任何布局管理,包括它自己的子类。
编写自定义布局
您可以使用 QGraphicsLayout 作为基础来编写自己的自定义布局(如 flowlayout),但更常见的做法是使用它的一个子类--QGraphicsLinearLayout 或QGraphicsGridLayout 。在创建自定义布局时,至少必须重新实现以下函数:
函数 | 函数 |
---|---|
QGraphicsLayoutItem::setGeometry() | 设置布局的几何图形时发出通知。您可以在重新实现此函数时将几何图形存储在自己的布局类中。 |
QGraphicsLayoutItem::sizeHint() | 返回布局的尺寸提示。 |
QGraphicsLayout::count() | 返回布局中的条目数。 |
QGraphicsLayout::itemAt() | 返回布局中项目的指针。 |
QGraphicsLayout::removeAt() | 从布局中删除一个项目,但不销毁该项目。 |
有关如何实现每个函数的详细信息,请参阅各个函数的文档。
每种布局都定义了自己的 API 来排列部件和布局项。例如,网格布局需要行和列索引,以及可选的行距和列距、对齐方式、间距等。而线性布局只需要一个行或列索引来定位其项目。对于网格布局而言,插入的顺序不会对布局产生任何影响,但对于线性布局而言,插入的顺序则至关重要。在编写自己的布局子类时,您可以自由选择最适合您布局的 API。
QGraphicsLayout 提供了addChildLayoutItem() 方便函数,用于将布局项添加到自定义布局中。如果需要,该函数将自动重新呈现图形项。
激活布局
当布局的几何形状发生变化时,QGraphicsLayout 会立即在每个项目上调用setGeometry() 来重新排列其所有托管项目。这种重新排列称为激活布局。
QGraphicsLayout 会更新自己的几何图形,使其与所管理QGraphicsLayoutItem 的contentsRect() 相匹配。因此,当窗口部件调整大小时,它将自动重新排列所有项目。QGraphicsLayout 会缓存其管理的所有项目的大小,以避免频繁调用setGeometry() 。
注: QGraphicsLayout 的几何图形与它所分配的 widget(而非布局)的contentsRect() 相同。
隐式激活布局
可以通过以下两种方式之一隐式激活布局:调用activate() 或调用invalidate() 。调用activate() 会立即激活布局。相反,调用invalidate() 则会延迟,因为它会向受管 widget 发布一个LayoutRequest 事件。由于事件压缩,activate() 只会在控制返回事件循环后被调用一次。这被称为布局无效。布局失效也会使任何缓存信息失效。此外,invalidate() 函数是一个虚拟函数。因此,您可以在 QGraphicsLayout 的子类中通过重新实现该函数来使自己的缓存无效。
事件处理
QGraphicsLayout 通过虚拟widgetEvent() 事件处理程序监听其管理的 widget 的事件。当布局被分配给一个部件时,交付给该部件的所有事件都会首先由widgetEvent() 进行处理。这样,布局就能感知部件的任何相关状态变化,如可见性变化或布局方向变化。
边距处理
可以通过重新实现setContentsMargins() 和getContentsMargins() 来修改 QGraphicsLayout 的边距。
成员函数文档
QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutItem *parent = nullptr)
构造一个 QGraphicsLayout 对象。
parent QGraphicsLayout 将传递给 的构造函数,并将 的 isLayout 参数设置为QGraphicsLayoutItem QGraphicsLayoutItemtrue。
如果parent 是QGraphicsWidget ,则布局将安装在该 widget 上。(请注意,安装布局将删除已安装的旧布局)。
[virtual noexcept]
QGraphicsLayout::~QGraphicsLayout()
销毁QGraphicsLayout 对象。
void QGraphicsLayout::activate()
激活布局,使布局中的所有项目立即重新排列。此函数基于调用count() 和itemAt() ,然后在所有项目上依次调用setGeometry() 。激活后,布局将根据父节点的contentsRect() 调整其几何图形。然后,父节点将使其自身的任何布局无效。
如果依次调用或递归调用(例如,由其中一个被排列的项目在调整大小后调用),该函数将不起任何作用。
请注意,布局可以自由使用几何图形缓存来优化这一过程。要强制使任何此类缓存失效,可以在调用 activate() 之前调用invalidate() 。
另请参阅 invalidate()。
[protected]
void QGraphicsLayout::addChildLayoutItem(QGraphicsLayoutItem *layoutItem)
该函数是一个为自定义布局提供的方便函数,它将遍历布局中的所有项目,并将其图形项目重新代理到最接近该布局的QGraphicsWidget 祖先。
如果layoutItem 已在其他布局中,则会从该布局中移除。
如果自定义布局需要特殊行为,它们可以忽略使用此函数,并实现自己的行为。
另请参阅 graphicsItem()。
[pure virtual]
int QGraphicsLayout::count() const
必须在QGraphicsLayout 的子类中重新实现这个纯虚函数,才能返回布局中的条目数。
子类可自行决定如何存储条目。
[override virtual]
void QGraphicsLayout::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const
重实现:QGraphicsLayoutItem::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const.
[virtual]
void QGraphicsLayout::invalidate()
清除布局中任何缓存的几何图形和尺寸提示信息,并向受管父级QGraphicsLayoutItem 发布LayoutRequest 事件。
另请参阅 activate() 和setGeometry()。
bool QGraphicsLayout::isActivated() const
如果布局正在被激活,则返回true
;否则返回false
。如果布局正在激活,则表示当前正在重新排列其项目(即已调用activate() 函数,但尚未返回)。
另请参阅 activate() 和invalidate()。
[pure virtual]
QGraphicsLayoutItem *QGraphicsLayout::itemAt(int i) const
必须在QGraphicsLayout 的子类中重新实现这个纯虚函数,以返回指向索引i 项目的指针。重新实现时可以假定i 有效(即它尊重count() 的值。)它与count() 一起作为遍历布局中所有项目的方法提供。
子类可以自行决定如何存储项目,视觉排列也不必通过该函数反映出来。
[pure virtual]
void QGraphicsLayout::removeAt(int index)
要删除index 上的项目,必须在QGraphicsLayout 的子类中重新实现这个纯虚函数。重新实现可以假定index 是有效的(即它尊重count() 的值。)
实现必须确保被移除项的parentLayoutItem() 不指向该布局,因为该项目被视为已从布局层次结构中移除。
如果布局要在应用程序之间重复使用,我们建议布局删除该项目,但图形视图框架并不依赖于这一点。
子类可以自由决定如何存储项。
void QGraphicsLayout::setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)
将内容页边距设置为left,top,right 和bottom 。顶层布局的默认内容页边距取决于样式(通过查询QStyle::PM_LayoutLeftMargin,QStyle::PM_LayoutTopMargin,QStyle::PM_LayoutRightMargin 和QStyle::PM_LayoutBottomMargin 的 pixelMetric)。
对于子布局,默认边距为 0。
更改内容页边距会自动使布局失效。
另请参见 invalidate().
[override virtual]
void QGraphicsLayout::updateGeometry()
重新实现:QGraphicsLayoutItem::updateGeometry().
[virtual]
void QGraphicsLayout::widgetEvent(QEvent *e)
QGraphicsLayout 使用此事件处理程序来监听与布局相关的事件,如几何形状变化、布局变化或布局方向变化。
e 是指向事件的指针。
您可以重新实现此事件处理程序,为自己的自定义布局跟踪类似事件。
另请参阅 QGraphicsWidget::event() 和QGraphicsItem::sceneEvent()。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.