QLayout Class

成员函数文档

[explicit] QLayout::QLayout(QWidget *parent = nullptr)

构建一个新的顶级 QLayout，其父布局为parent 。

该布局被直接设置为parent 的顶级布局。一个小部件只能有一个顶级布局。它由QWidget::layout()方法返回。

如果 `parent ` 是 `nullptr`，则必须将此布局插入到另一个布局中，或者使用 `QWidget::setLayout()` 将其设置为小部件的布局。

另请参阅 QWidget::setLayout()。

bool QLayout::activate()

如有必要，重新执行parentWidget()的布局。

通常您无需调用此方法，因为它会在最合适的时候自动被调用。如果布局已被重置，则返回 true。

另请参阅 update() 和QWidget::updateGeometry()。

[protected] void QLayout::addChildLayout(QLayout *childLayout)

该函数由子类中的addLayout() 或insertLayout() 函数调用，用于将布局childLayout 添加为子布局。

唯一需要直接调用该函数的情况是，当您实现一个支持嵌套布局的自定义布局时。

另请参阅 QBoxLayout::addLayout()、QBoxLayout::insertLayout() 和QGridLayout::addLayout()。

[protected] void QLayout::addChildWidget(QWidget *w)

该函数由子类的addWidget() 函数调用，用于将w 作为布局的受管理小部件添加进去。

w 如果w 已被某个布局管理，此函数将发出警告，并将其从该布局中移除。因此，必须在将w 添加到布局的数据结构之前调用此函数。

[pure virtual] void QLayout::addItem(QLayoutItem *item)

在子类中实现，用于添加一个item 。具体如何添加取决于每个子类。

该函数通常不会在应用程序代码中被调用。若要将小部件添加到布局中，请使用addWidget()函数；若要添加子布局，请使用相关QLayout 子类提供的addLayout()函数。

注意： item 的所有权将转移给布局，删除该控件是布局的责任。

另请参阅 addWidget()、QBoxLayout::addLayout() 和QGridLayout::addLayout()。

void QLayout::addWidget(QWidget *w)

以该布局特有的方式将小部件w 添加到此布局中。此函数使用addItem()。

[protected] QRect QLayout::alignmentRect(const QRect &r) const

返回当此布局的几何属性设置为r 时应被覆盖的矩形，前提是该布局支持setAlignment()。

该结果由sizeHint()和expandingDirections()推导得出。其大小绝不会超过r 。

[override virtual protected] void QLayout::childEvent(QChildEvent *e)

重写了：QObject::childEvent(QChildEvent *event)。

[static] QSize QLayout::closestAcceptableSize(const QWidget *widget, const QSize &size)

返回一个满足widget 上所有大小约束（包括heightForWidth()）且尽可能接近size 的大小。

QMargins QLayout::contentsMargins() const

返回布局周围使用的边距。

默认情况下，QLayout 使用样式中指定的值。在大多数平台上，各方向的边距均为 11 像素。

另请参阅 setContentsMargins()。

QRect QLayout::contentsRect() const

返回布局的geometry()矩形，但会考虑内容边距。

另请参阅 setContentsMargins()和getContentsMargins()。

[override virtual] QSizePolicy::ControlTypes QLayout::controlTypes() const

重新实现了：QLayoutItem::controlTypes() const。

[pure virtual] int QLayout::count() const

必须在子类中实现该方法，以返回布局中的项目数量。

另请参阅 itemAt()。

[override virtual] Qt::Orientations QLayout::expandingDirections() const

重写了：QLayoutItem::expandingDirections() const。

返回此布局是否可以使用比 `sizeHint()` 更多的空间。值为 `Qt::Vertical ` 或 `Qt::Horizontal ` 表示它仅希望在一个维度上扩展，而 `Qt::Vertical ` | `Qt::Horizontal ` 表示它希望在两个维度上同时扩展。

默认实现返回Qt::Horizontal |Qt::Vertical 。子类会重写该方法，根据其子控件的size policies 返回有意义的值。

另请参阅 sizeHint()。

[override virtual] QRect QLayout::geometry() const

重新实现了：QLayoutItem::geometry() const。

另请参见 setGeometry()。

void QLayout::getContentsMargins(int *left, int *top, int *right, int *bottom) const

对于left 、top 、right 和bottom 中的每一项（不包括nullptr ），会在指针所指向的位置存储该边距的大小。

默认情况下，QLayout 使用样式中提供的值。在大多数平台上，各方向的边距均为 11 像素。

另请参阅 setContentsMargins()、QStyle::pixelMetric()、PM_LayoutLeftMargin 、PM_LayoutTopMargin 、PM_LayoutRightMargin 以及PM_LayoutBottomMargin 。

[virtual] int QLayout::indexOf(const QLayoutItem *layoutItem) const

在此布局中（不包括子布局）搜索布局项layoutItem 。

返回layoutItem 的索引；若未找到layoutItem ，则返回 -1。

[virtual] int QLayout::indexOf(const QWidget *widget) const

在此布局中（不包括子布局）搜索名为widget 的小部件。

返回widget 的索引；若未找到widget ，则返回 -1。

默认实现会使用itemAt() 遍历所有项目。

[override virtual] void QLayout::invalidate()

重写了：QLayoutItem::invalidate()。

[override virtual] bool QLayout::isEmpty() const

重新实现了：QLayoutItem::isEmpty() const。

bool QLayout::isEnabled() const

如果布局已启用，则返回true ；否则返回false 。

另请参阅 setEnabled()。

[pure virtual] QLayoutItem *QLayout::itemAt(int index) const

必须在子类中实现该函数，以返回位于index 的布局项。如果不存在该布局项，则该函数必须返回nullptr 。布局项从 0 开始连续编号。如果删除某个布局项，其他布局项的编号将相应调整。

该函数可用于遍历布局。以下代码将为控件布局结构中的每个布局项绘制一个矩形。

static void paintLayout(QPainter *painter, QLayoutItem *item)
{
    QLayout *layout = item->layout();
    if (layout) {
        for (int i = 0; i < layout->count(); ++i)
            paintLayout(painter, layout->itemAt(i));
    }
    painter->drawRect(item->geometry());
}

void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    if (layout())
        paintLayout(&painter, layout());
}

另请参阅 count() 和takeAt()。

[override virtual] QLayout *QLayout::layout()

重写了：QLayoutItem::layout()。

[override virtual] QSize QLayout::maximumSize() const

重新实现了：QLayoutItem::maximumSize() const。

返回此布局的最大尺寸。这是该布局在符合规范的前提下所能达到的最大尺寸。

返回值不包含QWidget::setContentsMargins() 或menuBar() 所需的空间。

默认实现允许无限调整大小。

QWidget *QLayout::menuBar() const

返回此布局设置的菜单栏，如果未设置菜单栏，则返回nullptr 。

另请参阅 setMenuBar()。

[override virtual] QSize QLayout::minimumSize() const

重新实现了：QLayoutItem::minimumSize() const。

返回此布局的最小尺寸。这是该布局在仍符合规范要求时所能达到的最小尺寸。

返回值不包含QWidget::setContentsMargins()或menuBar()所需的空间。

默认实现允许无限制地调整大小。

QWidget *QLayout::parentWidget() const

返回此布局的父控件；如果此布局未安装在任何控件上，则返回nullptr 。

如果该布局是一个子布局，则此函数返回父布局的父控件。

另请参阅 parent()。

void QLayout::removeItem(QLayoutItem *item)

从布局中移除布局项item 。删除该项是调用方的责任。

请注意，item 本身也可以是一个布局（因为 `QLayout ` 继承自 `QLayoutItem`）。

另请参阅 removeWidget() 和addItem()。

void QLayout::removeWidget(QWidget *widget)

从布局中移除小部件widget 。调用此方法后，调用方有责任为该小部件设置合理的几何尺寸，将其放回布局中，或在必要时显式将其隐藏。

注意： widget 的所有权仍与添加时相同。

另请参阅 removeItem()、QWidget::setGeometry() 和addWidget()。

[virtual] QLayoutItem *QLayout::replaceWidget(QWidget *from, QWidget *to, Qt::FindChildOptions options = Qt::FindChildrenRecursively)

搜索小部件from ，若找到则将其替换为小部件to 。成功时返回包含小部件from 的布局项。否则返回nullptr 。如果options 包含Qt::FindChildrenRecursively （默认值），则会在子布局中进行替换操作。options 中的其他标志将被忽略。

请注意，因此返回的项可能不属于此布局，而是属于一个子布局。

返回的布局项不再由该布局拥有，应将其删除或插入到另一个布局中。小部件from 不再由该布局管理，可能需要将其删除或隐藏。小部件from 的父项保持不变。

此函数适用于 Qt 的内置布局，但可能不适用于自定义布局。

另请参阅 indexOf()。

bool QLayout::setAlignment(QWidget *w, Qt::Alignment alignment)

将控件w 的对齐方式设置为alignment ，如果在此布局中（不包括子布局）找到了w ，则返回true；否则返回false 。

bool QLayout::setAlignment(QLayout *l, Qt::Alignment alignment)

将布局l 的对齐方式设置为alignment ，如果在此布局中（不包括子布局）找到了l ，则返回true ；否则返回false 。

void QLayout::setContentsMargins(const QMargins &margins)

设置布局周围使用的margins 。

默认情况下，QLayout 使用样式中提供的值。在大多数平台上，各方向的边距均为 11 像素。

另请参阅 contentsMargins()。

void QLayout::setContentsMargins(int left, int top, int right, int bottom)

设置布局周围使用的left 、top 、right 和bottom 边距。

默认情况下，QLayout 使用样式中提供的值。在大多数平台上，各方向的边距均为 11 像素。

另请参阅 getContentsMargins()、QStyle::pixelMetric()、PM_LayoutLeftMargin 、PM_LayoutTopMargin 、PM_LayoutRightMargin 以及PM_LayoutBottomMargin 。

void QLayout::setEnabled(bool enable)

如果 `enable ` 为 true，则启用此布局；否则禁用它。

已启用的布局会动态适应变化；已禁用的布局则表现得仿佛不存在一样。

默认情况下，所有布局均处于启用状态。

另请参阅 isEnabled()。

[override virtual] void QLayout::setGeometry(const QRect &r)

重写了：QLayoutItem::setGeometry(const QRect &r)。

另请参阅 geometry()。

void QLayout::setMenuBar(QWidget *widget)

指示几何管理器将菜单栏widget 放置在parentWidget() 的顶部，位于QWidget::contentsMargins() 之外。所有子控件均放置在菜单栏底部边缘下方。

另请参阅 menuBar()。

[since 6.10] void QLayout::setSizeConstraints(QLayout::SizeConstraint horizontal, QLayout::SizeConstraint vertical)

同时设置horizontal 和vertical 的大小约束。

该函数在 Qt 6.10 中引入。

另请参阅 sizeConstraint()、horizontalSizeConstraint() 和verticalSizeConstraint()。

[pure virtual] QLayoutItem *QLayout::takeAt(int index)

必须在子类中实现此方法，用于从布局中移除位于index 的布局项，并返回该项。如果不存在该项，则该函数应不执行任何操作并返回0。布局项的编号从0开始连续编号。如果移除某项，其他项的编号将相应调整。

以下代码片段展示了一种安全地从布局中移除所有项的方法：

QLayoutItem *child;
while ((child = layout->takeAt(0)) != nullptr) {
    ...
    delete child->widget(); // delete the widget
    delete child;   // delete the layout item
}

另请参阅 itemAt() 和count()。

[since 6.1] void QLayout::unsetContentsMargins()

清除布局周围的所有用户自定义边距。布局将使用样式提供的默认值。

该函数在 Qt 6.1 中引入。

另请参阅 setContentsMargins()。

void QLayout::update()

更新parentWidget() 的布局。

通常您无需调用此方法，因为系统会在最合适的时候自动调用它。

另请参阅 activate() 和invalidate()。