QskLinearBox

Layout stringing items in rows and columns. More…

#include <QskLinearBox.h>

Inherits from QskIndexedLayoutBox, QskBox

Public Slots

Public Signals

Public Functions

Protected Functions

Public Properties

Additional inherited members

Public Signals inherited from QskIndexedLayoutBox

Public Functions inherited from QskIndexedLayoutBox

Protected Functions inherited from QskIndexedLayoutBox

Public Properties inherited from QskIndexedLayoutBox

Detailed Description

class QskLinearBox;

Layout stringing items in rows and columns.

See: QskGridBox, QskStackBox

Note: All available Qsk layouts are thin layers on top of the same grid based workhorse ( = QGridLayoutEngine ). QskLinearBox offers a reasonable subset of features, tailored for an index based point of view.

QskLinearBox organizes layout items in vertical or horizontal order ( orientation ). When the number of items for a row/column has reached an upper limit ( dimension ) the following items will be added to a new row/column.

When having the dimension being set to unlimited ( or 1 with the inverted orientation ) the string layout behaves similar to QBoxLayout, RowLayout/ColumnLayout ( QML ) or what is sometimes called a linear layout.

When not restricting the layout to one row/column only the layout can be used to set up simple grid formations.

Layout items may be QQuickItem *s or spacers - both having a stretch factor in the range of [0..10];

Public Slots Documentation

slot transpose

void transpose()

Invert the orientation of the layout.

See: setOrientation(), orientation(), orientationChanged()

Qt::Horizontal becomes to Qt::Vertical and v.v.

slot activate

void activate()

slot invalidate

void invalidate()

slot clear

void clear(
    bool autoDelete =false
)

Public Signals Documentation

signal orientationChanged

void orientationChanged()

See: orientation

The orientation of the layout has changed

signal dimensionChanged

void dimensionChanged()

See: setDimension(), dimension()

The dimension of the layout has changed

signal defaultAlignmentChanged

void defaultAlignmentChanged()

signal spacingChanged

void spacingChanged()

See: setSpacing(), spacing(), setRowSpacing(), setColumnSpacing()

The spacing of the layout has changed

signal extraSpacingAtChanged

void extraSpacingAtChanged()

Public Functions Documentation

function QskLinearBox

explicit QskLinearBox(
    QQuickItem * parent =nullptr
)

Create a row layout.

Parameters:

• parent Parent item

See: orientation, dimension

The orientation is set to Qt::Horizontal orientation having an unlimited dimension.

function QskLinearBox

explicit QskLinearBox(
    Qt::Orientation orientation,
    QQuickItem * parent =nullptr
)

Create a row or column layout.

Parameters:

• orientation Qt::Horizontal or Qt::Vertical
• parent Parent item

See: orientation, dimension

The dimension is unlimited.

function QskLinearBox

QskLinearBox(
    Qt::Orientation orientation,
    uint dimension,
    QQuickItem * parent =nullptr
)

Constructor.

Parameters:

• orientation Qt::Horizontal or Qt::Vertical
• dimension Upper limit for the number of elements in a row or column
• parent Parent item

See: orientation, dimension

function ~QskLinearBox

~QskLinearBox() override

Destructor

function isEmpty

inline bool isEmpty() const

function elementCount

int elementCount() const

function spacingAtIndex

qreal spacingAtIndex(
    int index
) const

function itemAtIndex

QQuickItem * itemAtIndex(
    int index
) const

function indexOf

int indexOf(
    const QQuickItem * item
) const

function removeItem

void removeItem(
    const QQuickItem * item
)

function removeAt

void removeAt(
    int index
)

function orientation

Qt::Orientation orientation() const

Return: Value of the orientation property

function setOrientation

void setOrientation(
    Qt::Orientation orientation
)

Set the orientation of the layout.

Parameters:

• orientation Qt::Vertical or Qt::Horizontal

See: orientation

function setDimension

void setDimension(
    uint dimension
)

Set the dimension of the layout.

Parameters:

• dimension Upper limit for the number of elements in a row or column

See: dimension

Warning: A value of 0 is invalid and will be set to 1

function dimension

uint dimension() const

function setExtraSpacingAt

void setExtraSpacingAt(
    Qt::Edges edges
)

function extraSpacingAt

Qt::Edges extraSpacingAt() const

function setDefaultAlignment

void setDefaultAlignment(
    Qt::Alignment alignment
)

function defaultAlignment

Qt::Alignment defaultAlignment() const

function setSpacing

void setSpacing(
    qreal spacing
)

Set the global spacing of the layout.

Parameters:

• spacing Distance between each cell and row

See: spacing

function resetSpacing

void resetSpacing()

Reset the global spacing to its initial value.

See: spacing

function spacing

qreal spacing() const

function addItem

Q_INVOKABLE int addItem(
    QQuickItem * item
)

function addItem

int addItem(
    QQuickItem * item,
    Qt::Alignment alignment
)

function insertItem

Q_INVOKABLE int insertItem(
    int index,
    QQuickItem * item
)

function insertItem

int insertItem(
    int index,
    QQuickItem * item,
    Qt::Alignment alignment
)

function addSpacer

Q_INVOKABLE int addSpacer(
    qreal spacing,
    int stretchFactor =0
)

Append a spacer to the layout.

Parameters:

• spacing Spacing
• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: insertSpacer()

The same as insertSpacer( -1, spacing, stretchFactor );

function insertSpacer

Q_INVOKABLE int insertSpacer(
    int index,
    qreal spacing,
    int stretchFactor =0
)

Insert a spacer at a specific position.

Parameters:

• index Position, where to insert the spacer. If index is < 0 or beyond QskLayout::itemCount() the spacer will be appended.
• spacing Spacing Minimum for width/height
• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: insertItem(), QskLayout::itemAtIndex()

Note: Calling QskLayout::itemAtIndex( index ) will return a nullptr.

Spacers being inserted to the layout are elements having an index - like regular QQuickItem *s and participate in the calculation of the geometries.

A spacer is treated like being an item with a preferred width/height of spacing. In case of having a stretchFactor > 0 the width/height might exceed spacing.

function addStretch

Q_INVOKABLE int addStretch(
    int stretchFactor =0
)

Append a stretch to the layout.

Parameters:

• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: insertStretch(), addSpacer()

The same as insertStretch( -1, stretchFactor );

function insertStretch

Q_INVOKABLE int insertStretch(
    int index,
    int stretchFactor =0
)

Insert a stretch at a specific position.

Parameters:

• index Position, where to insert the stretch. If index is < 0 or beyond QskLayout::itemCount() the stretch will be appended.
• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: insertSpacer(), QskLayout::itemAtIndex()

Note: Calling QskLayout::itemAtIndex( index ) will return a nullptr.

A stretch is simply a spacer with a spacing of 0

function setStretchFactor

Q_INVOKABLE void setStretchFactor(
    int index,
    int stretchFactor
)

Modify the stretch factor of a layout element.

Parameters:

• index Position of the element
• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: stretchFactor()

function stretchFactor

Q_INVOKABLE int stretchFactor(
    int index
) const

Parameters:

• index Position of the inserted element

See: setStretchFactor()

Return: Stretch factor of a layout element

function setStretchFactor

void setStretchFactor(
    const QQuickItem * item,
    int stretchFactor
)

Modify the stretch factor of an inserted item.

Parameters:

• item Inserted item
• stretchFactor A value between [0..10]. The ratio of the stretch factors of expandable candidates decides about how to distribute extra space.

See: stretchFactor()

function stretchFactor

int stretchFactor(
    const QQuickItem * item
) const

Parameters:

• item Inserted item

See: setStretchFactor()

Return: Stretch factor of a layout element

function dump

void dump() const

Protected Functions Documentation

function event

bool event(
    QEvent * event
) override

function geometryChangeEvent

virtual void geometryChangeEvent(
    QskGeometryChangeEvent * 
) override

Parameters:

• event Event indicating the geometry change

See: geometryChange() \saqt QObject::installEventFilter()

Reimplements: QskQuickItem::geometryChangeEvent

For no known reason QQuickItem propagates changes of position and size by calling QQuickItem::geometryChange(), instead of using events.

QskQuickItem reestablished the more powerful concept of events by sending/posting events, that can be preprocessed by event filtering.

function itemChange

void itemChange(
    ItemChange change,
    const ItemChangeData & value
) override

function updateLayout

virtual void updateLayout() override

Reimplements: QskControl::updateLayout

function layoutSizeHint

virtual QSizeF layoutSizeHint(
    Qt::SizeHint which,
    const QSizeF & constraint
) const override

Reimplements: QskControl::layoutSizeHint

Public Property Documentation

property orientation

Qt::Orientation orientation;

Direction of flow for laying out the items.

See: transpose(), dimension

Par: Access functions:

orientation(), setOrientation(), orientationChanged()

In case of Qt::Horizontal the elements are organized horizontally increasing the column index, when appending an item. When the number of columns exceeds the dimension the next item will be in the first column of the next row ( v.v for Qt::Vertical ).

The horizontal layout direction is affected by its state of QskControl::layoutMirroring(), what might depend on the QskControl::locale().

property dimension

uint dimension;

Upper limit for the number of elements in a row or column.

See: orientation

Return: Value of the dimension property const

Par: Access functions:

dimension(), setDimension(), dimensionChanged()

According to the orientation the layout is organized in rows or columns. The dimension is an upper limit for the number of elements in a row/column.

When the number of elements exceeds the dimension the following element will be inserted in the following row/column.

property spacing

qreal spacing;

Global layout spacing.

See: setRowSpacing(), setColumnSpacing(), insertSpacer(), QskControl::setMargins()

Return: Value of the spacing property

Note: In opposite to a spacer, the global spacing does not insert elements.

Par: Access functions:

spacing(), setSpacing(), spacingChanged()

The spacing is the distance between each cell and row of the layout. Its initial value depend on the current theme.

Beside setting the global spacing it is also possible to add individual spacings at the end of each row and column.

property defaultAlignment

Qt::Alignment defaultAlignment;

property extraSpacingAt

Qt::Edges extraSpacingAt;

property elementCount

int elementCount;

property empty

bool empty;

Updated on 28 July 2023 at 14:02:28 CEST