Revision control
Copy as Markdown
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include <QtQuickLayouts/private/qquickflexboxlayout_p.h>
#include <QtQuickLayouts/private/qquickflexboxlayoutengine_p.h>
#include <QtQml/qqmlinfo.h>
/*!
\qmltype FlexboxLayout
//! \nativetype QQuickFlexboxLayout
\inherits Item
\inqmlmodule QtQuick.Layouts
\ingroup layouts
\since 6.10
\preliminary
\brief The FlexboxLayout QML construct provides a flex layout for the
quick items.
The FlexboxLayout enables to layout the quick items in a flexible way as
similar to that of
Internally Qt FlexboxLayout uses the \l{qtquick-attribution-yoga.html}{yoga engine}
to derive the geometry of
subset of the
FlexboxLayout can be limited to the feature as supported in the
\note The FlexboxLayout adheres to yoga library version 2.0 for its
features.
The items within the FlexboxLayout can be configured with preferred,
minimum and maximum sizes through the existing layout attached properties.
For instance, if the item within the FlexboxLayout need to be stretched,
the layout attached property \l{Layout.fillWidth} or \l{Layout.fillHeight}
can be set.
Items in a FlexboxLayout support these attached properties:
\list
\li \l{FlexboxLayout.alignSelf}
\li \l{Layout.minimumWidth}
\li \l{Layout.minimumHeight}
\li \l{Layout.preferredWidth}
\li \l{Layout.preferredHeight}
\li \l{Layout.maximumWidth}
\li \l{Layout.maximumHeight}
\li \l{Layout.fillWidth}
\li \l{Layout.fillHeight}
\li \l{Layout.margins}
\li \l{Layout.leftMargin}
\li \l{Layout.rightMargin}
\li \l{Layout.topMargin}
\li \l{Layout.bottomMargin}
\endlist
Read more about attached properties \l{QML Object Attributes}{here}.
\sa ColumnLayout
\sa GridLayout
\sa RowLayout
\sa {QtQuick.Controls::StackView}{StackView}
\sa {Qt Quick Layouts Overview}
To be able to use this type more efficiently, it is recommended that you
understand the general mechanism of the Qt Quick Layouts module. Refer to
\l{Qt Quick Layouts Overview} for more information.
\section1 Example Usage
The following snippet shows the minimalistic example of using QML
FlexboxLayout to arrange the rectangle items in more flexible way
\snippet layouts/simpleFlexboxLayout.qml layout-definition
\note This API is considered tech preview and may change or be removed in
future versions of Qt.
*/
QT_BEGIN_NAMESPACE
class QQuickFlexboxLayoutPrivate : public QQuickLayoutPrivate
{
Q_DECLARE_PUBLIC(QQuickFlexboxLayout)
public:
QQuickFlexboxLayoutPrivate() : QQuickLayoutPrivate() {}
const QQuickFlexboxLayoutEngine& getFlexEngine() const { return m_flexEngine; }
private:
QQuickFlexboxLayoutEngine m_flexEngine;
QQuickFlexboxLayout::FlexboxDirection m_direction = QQuickFlexboxLayout::Row;
QQuickFlexboxLayout::FlexboxWrap m_wrap = QQuickFlexboxLayout::NoWrap;
QQuickFlexboxLayout::FlexboxAlignment m_alignItems = QQuickFlexboxLayout::AlignStart;
// Align items within the layout in the multi-line containter (i.e. with
// wrap enabled) and its aligned to the cross axis of the flexbox layout
QQuickFlexboxLayout::FlexboxAlignment m_alignContent = QQuickFlexboxLayout::AlignStretch;
// Align content item in the multi-line containter and its aligned to the
// main axis of the flexbox layout
QQuickFlexboxLayout::FlexboxJustify m_justifyContent = QQuickFlexboxLayout::JustifyStart;
qreal m_gap = 0.;
qreal m_rowGap = 0.;
qreal m_columnGap = 0.;
std::bitset<QQuickFlexboxLayout::GapMax> m_gapBitSet;
};
static QQuickFlexboxLayoutAttached *attachedFlexboxLayoutObject(QQuickItem *item, bool create = false)
{
return static_cast<QQuickFlexboxLayoutAttached*>(
qmlAttachedPropertiesObject<QQuickFlexboxLayout>(item, create));
}
QQuickFlexboxLayout::QQuickFlexboxLayout(QQuickItem *parent) :
QQuickLayout(*new QQuickFlexboxLayoutPrivate, parent)
{
Q_D(QQuickFlexboxLayout);
d->m_flexEngine.setFlexboxParentItem(new QQuickFlexboxLayoutItem(this));
}
QQuickFlexboxLayout::~QQuickFlexboxLayout()
{
Q_D(QQuickFlexboxLayout);
d->m_flexEngine.clearItems();
}
/*!
\qmlproperty enumeration FlexboxLayout::direction
This property holds the item layout direction within the flex box layout
and it defines the
Possible values:
\value FlexboxLayout.Row (default) Items are laid out from
left to right.
\value FlexboxLayout.RowReversed Items are laid out from right to
left.
\value FlexboxLayout.Column Items are laid out from top to
bottom.
\value FlexboxLayout.ColumnReversed Items are laid out from bottom to
top.
The default value is \c FlexboxLayout.Row.
*/
QQuickFlexboxLayout::FlexboxDirection QQuickFlexboxLayout::direction() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_direction;
}
void QQuickFlexboxLayout::setDirection(QQuickFlexboxLayout::FlexboxDirection direction)
{
Q_D(QQuickFlexboxLayout);
if (d->m_direction == direction)
return;
d->m_direction = direction;
invalidate();
emit directionChanged();
}
/*!
\qmlproperty enumeration FlexboxLayout::wrap
This property specifies that the items within the flex box layout can wrap
or not and it happens when the children overflow the size of the flex box
layout. If the items are wrapped, it will be placed in multiple lines
depending on overflow condition as stated. Each line takes up the
maximum size of the item along the
Possible values:
\value FlexboxLayout.Wrap Items are wrapped into multiple lines
within the flex box layout.
\value FlexboxLayout.NoWrap (default) Items are not wrapped and
laid out in single line within the
flex box layout.
\value FlexboxLayout.WrapReverse Items are wrapped into multiple lines
within the flex box layout in the
reverse direction.
The default value is \c FlexboxLayout.NoWrap.
*/
QQuickFlexboxLayout::FlexboxWrap QQuickFlexboxLayout::wrap() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_wrap;
}
void QQuickFlexboxLayout::setWrap(QQuickFlexboxLayout::FlexboxWrap wrapMode)
{
Q_D(QQuickFlexboxLayout);
if (d->m_wrap == wrapMode)
return;
d->m_wrap = wrapMode;
invalidate();
emit wrapChanged();
}
/*!
\qmlproperty enumeration FlexboxLayout::alignItems
This property specifies the alignment of the items within the
flex box layout and its aligned along the
(which is orthogonal to the main-axis, as defined by the property
\l {direction}). This property can be overridden by the
items within the flex box layout through the attached property
\l {FlexboxLayout.alignSelf}.
Possible values:
\value FlexboxLayout.AlignStart (default) Items are aligned to the
start of the flex box layout
cross-axis.
\value FlexboxLayout.AlignCenter Items are aligned along the center
of the flex box layout cross-axis.
\value FlexboxLayout.AlignEnd Items are aligned to the end of the
flex box layout cross-axis.
\note The alignments mentioned in possible values are only applicable for
the \l{alignItems} property
The default value is \c FlexboxLayout.AlignStart.
*/
QQuickFlexboxLayout::FlexboxAlignment QQuickFlexboxLayout::alignItems() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_alignItems;
}
void QQuickFlexboxLayout::setAlignItems(QQuickFlexboxLayout::FlexboxAlignment alignment)
{
Q_D(QQuickFlexboxLayout);
if (alignment >= QQuickFlexboxLayout::AlignStretch || alignment <= QQuickFlexboxLayout::AlignAuto) {
qWarning("Not applicable for Flexbox layout container");
return;
}
if (d->m_alignItems == alignment)
return;
d->m_alignItems = alignment;
invalidate();
emit alignItemsChanged();
}
/*!
\qmlproperty enumeration FlexboxLayout::alignContent
This property specifies the distribution of the
flex box layout.
Possible values:
\value FlexboxLayout.AlignStart Flex lines are aligned to
the start of the flex box layout.
\value FlexboxLayout.AlignCenter Flex lines are aligned along the
center of the flex box layout.
\value FlexboxLayout.AlignEnd Flex lines are aligned to the end
of the flex box layout.
\value FlexboxLayout.AlignStretch (default) Flex lines are stretched
according to the height of the flex
box layout.
\value FlexboxLayout.AlignSpaceBetween The spaces are evenly distributed
between the lines and no space
along the edge of the flex box
layout.
\value FlexboxLayout.AlignSpaceAround The spaces are evenly distributed
between the lines and half-size
space on the edges of the flex box
layout.
\value FlexboxLayout.AlignSpaceEvenly The spaces are evenly distributed
between the lines and the edges of
the flex box layout. Not supported
in Qt 6.10.
The default value is \c FlexboxLayout.AlignStart.
*/
QQuickFlexboxLayout::FlexboxAlignment QQuickFlexboxLayout::alignContent() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_alignContent;
}
void QQuickFlexboxLayout::setAlignContent(QQuickFlexboxLayout::FlexboxAlignment alignment)
{
Q_D(QQuickFlexboxLayout);
if (alignment == QQuickFlexboxLayout::AlignSpaceEvenly) {
qmlWarning(this) << "Currently not supported for Flexbox layout container";
return;
}
if (d->m_alignContent == alignment)
return;
d->m_alignContent = alignment;
invalidate();
emit alignContentChanged();
}
/*!
\qmlproperty enumeration FlexboxLayout::justifyContent
This property specifies the distribution of the items along the
flex box layout.
Possible values:
\value FlexboxLayout.JustifyStart (default) Items are aligned to
the start of the flex box
layout.
\value FlexboxLayout.JustifyCenter Items are aligned along the
center of the flex box layout.
\value FlexboxLayout.JustifyEnd Items are aligned to the end of
the flex box layout.
\value FlexboxLayout.JustifySpaceBetween The spaces are evenly
distributed between the items
and no space along the edges
of the flex box layout.
\value FlexboxLayout.JustifySpaceAround The spaces are evenly
distributed between the items
and half-size space on the
edges of the flex box layout.
\value FlexboxLayout.JustiftSpaceEvenly The spaces are evenly
distributed between the items
and edges of the flex
box layout.
The default value is \c FlexboxLayout.JustifyStart.
*/
QQuickFlexboxLayout::FlexboxJustify QQuickFlexboxLayout::justifyContent() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_justifyContent;
}
void QQuickFlexboxLayout::setJustifyContent(QQuickFlexboxLayout::FlexboxJustify justifyContent)
{
Q_D(QQuickFlexboxLayout);
if (d->m_justifyContent == justifyContent)
return;
d->m_justifyContent = justifyContent;
invalidate();
emit justifyContentChanged();
}
/*!
\qmlproperty real FlexboxLayout::gap
This property holds the amount of space that need to be applied
to the \l {FlexboxLayout} both along the
The default value is \c 0.
*/
qreal QQuickFlexboxLayout::gap() const
{
Q_D(const QQuickFlexboxLayout);
return d->m_gap;
}
void QQuickFlexboxLayout::setGap(qreal gap)
{
Q_D(QQuickFlexboxLayout);
if (d->m_gap == gap)
return;
d->m_gap = gap;
d->m_gapBitSet.set(GapAll);
invalidate();
emit gapChanged();
if (!isGapBitSet(GapRow))
emit rowGapChanged();
if (!isGapBitSet(GapColumn))
emit columnGapChanged();
}
void QQuickFlexboxLayout::resetGap()
{
Q_D(QQuickFlexboxLayout);
d->m_gap = 0;
d->m_gapBitSet.reset(GapAll);
emit gapChanged();
if (!isGapBitSet(GapRow))
emit rowGapChanged();
if (!isGapBitSet(GapColumn))
emit columnGapChanged();
}
/*!
\qmlproperty real FlexboxLayout::rowGap
This property holds the amount of space that need to be applied to the
\l {FlexboxLayout} along the
property overrides the \l{gap} value affecting the
The default value is \c 0.
*/
qreal QQuickFlexboxLayout::rowGap() const
{
Q_D(const QQuickFlexboxLayout);
if (!isGapBitSet(GapRow))
return d->m_gap;
return d->m_rowGap;
}
void QQuickFlexboxLayout::setRowGap(qreal gap)
{
Q_D(QQuickFlexboxLayout);
if (d->m_rowGap == gap)
return;
d->m_rowGap = gap;
d->m_gapBitSet.set(QQuickFlexboxLayout::GapRow);
invalidate();
emit rowGapChanged();
}
void QQuickFlexboxLayout::resetRowGap()
{
Q_D(QQuickFlexboxLayout);
d->m_rowGap = 0;
d->m_gapBitSet.reset(GapRow);
emit rowGapChanged();
}
/*!
\qmlproperty real FlexboxLayout::columnGap
This property holds the amount of space that need to be applied
to the \l {FlexboxLayout} along the
property override the \l{gap} value affecting the
The default value is \c 0.
*/
qreal QQuickFlexboxLayout::columnGap() const
{
Q_D(const QQuickFlexboxLayout);
if (!isGapBitSet(GapColumn))
return d->m_gap;
return d->m_columnGap;
}
void QQuickFlexboxLayout::setColumnGap(qreal gap)
{
Q_D(QQuickFlexboxLayout);
if (d->m_columnGap == gap)
return;
d->m_columnGap = gap;
d->m_gapBitSet.set(QQuickFlexboxLayout::GapColumn);
invalidate();
emit columnGapChanged();
}
void QQuickFlexboxLayout::resetColumnGap()
{
Q_D(QQuickFlexboxLayout);
d->m_columnGap = 0;
d->m_gapBitSet.reset(GapColumn);
emit columnGapChanged();
}
void QQuickFlexboxLayout::updateLayoutItems()
{
Q_D(QQuickFlexboxLayout);
// Clean all the items in the layout
d->m_flexEngine.clearItems();
// Update the parent item properties
if (auto *flexParentItem = d->m_flexEngine.getFlexboxParentItem()) {
flexParentItem->setFlexDirection(d->m_direction);
flexParentItem->setFlexWrap(d->m_wrap);
flexParentItem->setFlexAlignItemsProperty(d->m_alignItems);
flexParentItem->setFlexAlignContentProperty(d->m_alignContent);
flexParentItem->setFlexJustifyContentProperty(d->m_justifyContent);
if (isGapBitSet(QQuickFlexboxLayout::GapAll))
flexParentItem->setFlexGap(QQuickFlexboxLayout::GapAll, d->m_gap);
if (isGapBitSet(QQuickFlexboxLayout::GapRow))
flexParentItem->setFlexGap(QQuickFlexboxLayout::GapRow, d->m_rowGap);
if (isGapBitSet(QQuickFlexboxLayout::GapColumn))
flexParentItem->setFlexGap(QQuickFlexboxLayout::GapColumn, d->m_columnGap);
}
// Insert the items in the layout
const QList<QQuickItem *> items = childItems();
for (auto *childItem : items) {
Q_ASSERT(childItem);
checkAnchors(childItem);
if (shouldIgnoreItem(childItem))
continue;
// Create and set the attached properties of the flex item and add it as child
auto *flexLayoutItem = new QQuickFlexboxLayoutItem(childItem);
if (auto *flexItemAttachedProperties = attachedFlexboxLayoutObject(childItem))
flexLayoutItem->setFlexAlignSelfProperty(flexItemAttachedProperties->alignSelf());
d->m_flexEngine.insertItem(flexLayoutItem);
}
}
void QQuickFlexboxLayout::checkAnchors(QQuickItem *item) const
{
QQuickAnchors *anchors = QQuickItemPrivate::get(item)->_anchors;
if (anchors && anchors->activeDirections())
qmlWarning(item) << "Detected anchors on an item that is managed by a layout. This is undefined behavior; use FlexboxLayout alignment properties instead.";
}
void QQuickFlexboxLayout::componentComplete()
{
QQuickLayout::componentComplete();
ensureLayoutItemsUpdated(ApplySizeHints);
if (qobject_cast<QQuickLayout*>(parentItem()))
return;
rearrange(QSizeF(width(), height()));
}
void QQuickFlexboxLayout::itemVisibilityChanged(QQuickItem *item)
{
if (!isReady())
return;
invalidate(item);
}
QSizeF QQuickFlexboxLayout::sizeHint(Qt::SizeHint whichSizeHint) const
{
Q_D(const QQuickFlexboxLayout);
QSizeF sizeHint = d->m_flexEngine.sizeHint(whichSizeHint);
d->m_dirty = false;
return sizeHint;
}
QQuickFlexboxLayoutAttached *QQuickFlexboxLayout::qmlAttachedProperties(QObject *object)
{
return new QQuickFlexboxLayoutAttached(object);
}
bool QQuickFlexboxLayout::isGapBitSet(QQuickFlexboxLayout::FlexboxGap gap) const
{
Q_D(const QQuickFlexboxLayout);
if (gap < QQuickFlexboxLayout::GapRow || gap > QQuickFlexboxLayout::GapAll)
return false;
return d->m_gapBitSet[gap];
}
QQuickItem *QQuickFlexboxLayout::itemAt(int index) const
{
const auto items = childItems();
for (QQuickItem *item : items) {
if (shouldIgnoreItem(item))
continue;
if (index == 0)
return item;
--index;
}
return nullptr;
}
int QQuickFlexboxLayout::itemCount() const
{
int count = 0;
const auto items = childItems();
for (QQuickItem *item : items) {
if (shouldIgnoreItem(item))
continue;
++count;
}
return count;
}
void QQuickFlexboxLayout::invalidate(QQuickItem *childItem)
{
Q_D(QQuickFlexboxLayout);
d->m_flexEngine.invalidateItemSizeHint(childItem);
QQuickLayout::invalidate(this);
if (QQuickLayout *parentLayout = qobject_cast<QQuickLayout *>(parentItem()))
parentLayout->invalidate(this);
}
void QQuickFlexboxLayout::childItemsChanged()
{
const int count = itemCount();
for (int i = 0; i < count; ++i) {
QQuickItem *child = itemAt(i);
checkAnchors(child);
}
}
void QQuickFlexboxLayout::rearrange(const QSizeF &newSize)
{
Q_D(QQuickFlexboxLayout);
if (newSize.isNull() || !newSize.isValid())
return;
d->m_flexEngine.setGeometries(newSize);
QQuickLayout::rearrange(newSize);
}
void QQuickFlexboxLayout::itemSiblingOrderChanged(QQuickItem *)
{
if (!isReady())
return;
invalidate();
}
QQuickFlexboxLayoutAttached::QQuickFlexboxLayoutAttached(QObject *object)
{
auto item = qobject_cast<QQuickItem*>(object);
if (!item) {
qmlWarning(object) << "FlexboxLayout attached property must be attached to an object deriving from Item";
return;
}
setParent(object);
if (auto flexboxLayout = qobject_cast<QQuickFlexboxLayout*>(item->parentItem())) {
if (!flexboxLayout->isComponentComplete()) {
// Don't try to get the index if the FlexboxLayout itself hasn't
// loaded yet.
return;
}
// In case of lazy loading in loader, attachedProperties are created
// and updated for the object after adding the child object to the
// stack layout, which leads to entries with same index. Triggering
// childItemsChanged() resets to right index in the stack layout.
flexboxLayout->childItemsChanged();
}
}
/*!
\qmlattachedproperty enumeration FlexboxLayout::alignSelf
This attached property allows to align this item in the flex box layout
and it overrides the parent flex box layout property
\l{alignItems}.
By default, the child item inherit the alignment from the parent and it can
override the parent flex box layout
\l{alignItems} property with the values
\c {FlexboxLayout.AlignStart}, \c {FlexboxLayout.AlignCenter}
and \c {FlexboxLayout.AlignEnd}.
The default value is \c {FlexboxLayout.AlignAuto}.
*/
QQuickFlexboxLayout::FlexboxAlignment QQuickFlexboxLayoutAttached::alignSelf() const
{
return m_alignSelf;
}
void QQuickFlexboxLayoutAttached::setAlignSelf(QQuickFlexboxLayout::FlexboxAlignment alignment)
{
if (m_alignSelf == alignment)
return;
m_alignSelf = alignment;
const auto *item = qobject_cast<QQuickItem*>(parent());
if (auto *flexLayout = qobject_cast<QQuickFlexboxLayout *>(item->parent())) {
auto *priv = dynamic_cast<QQuickFlexboxLayoutPrivate *>(QQuickLayoutPrivate::get(flexLayout));
auto &flexEngine = priv->getFlexEngine();
auto *item = qobject_cast<QQuickItem *>(parent());
if (auto *flexLayoutItem = flexEngine.findFlexboxLayoutItem(item)) {
flexLayoutItem->setFlexAlignSelfProperty(alignment);
flexLayout->invalidate();
}
}
emit alignSelfChanged();
}
QT_END_NAMESPACE
#include "moc_qquickflexboxlayout_p.cpp"