319 lines
8.3 KiB
Plaintext
319 lines
8.3 KiB
Plaintext
/*!
|
|
\class QskLinearBox QskLinearBox.h
|
|
|
|
\brief Layout stringing items in rows and columns
|
|
|
|
QskLinearBox organizes layout items in vertical or horizontal order
|
|
( \ref orientation ). When the number of items for a row/column has
|
|
reached an upper limit ( \ref dimension ) the following items will be
|
|
added to a new row/column.
|
|
|
|
When having the \ref dimension being set to unlimited ( or 1 with the
|
|
inverted \ref 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];
|
|
|
|
\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.
|
|
|
|
\sa QskGridBox, QskStackBox
|
|
*/
|
|
|
|
/*!
|
|
\property Qt::Orientation QskLinearBox::orientation
|
|
|
|
\brief Direction of flow for laying out the items
|
|
|
|
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 \ref 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().
|
|
|
|
\sa transpose(), dimension
|
|
\accessors orientation(), setOrientation(), orientationChanged()
|
|
*/
|
|
|
|
/*!
|
|
\property uint QskLinearBox::dimension
|
|
|
|
\brief Upper limit for the number of elements in a row or column
|
|
|
|
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.
|
|
|
|
\sa orientation
|
|
\accessors dimension(), setDimension(), dimensionChanged()
|
|
*/
|
|
|
|
/*!
|
|
\property qreal QskLinearBox::spacing
|
|
|
|
\brief Global layout spacing
|
|
|
|
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.
|
|
|
|
\note In opposite to a spacer, the global spacing does not insert elements.
|
|
|
|
\sa setRowSpacing(), setColumnSpacing(), insertSpacer(), QskControl::setMargins()
|
|
\accessors spacing(), setSpacing(), spacingChanged()
|
|
*/
|
|
|
|
/*!
|
|
\fn QskLinearBox::QskLinearBox( QQuickItem* );
|
|
|
|
\brief Create a row layout
|
|
|
|
The \ref orientation is set to Qt::Horizontal orientation having
|
|
an unlimited \ref dimension.
|
|
|
|
\param parent Parent item
|
|
\sa orientation, dimension
|
|
*/
|
|
|
|
/*!
|
|
\fn QskLinearBox::QskLinearBox( Qt::Orientation orientation, QQuickItem * parent );
|
|
|
|
\brief Create a row or column layout
|
|
|
|
The \ref dimension is unlimited.
|
|
|
|
\param orientation Qt::Horizontal or Qt::Vertical
|
|
\param parent Parent item
|
|
|
|
\sa orientation, dimension
|
|
*/
|
|
|
|
/*!
|
|
\fn QskLinearBox::QskLinearBox( Qt::Orientation, uint, QQuickItem* );
|
|
|
|
\brief Constructor
|
|
|
|
\param orientation Qt::Horizontal or Qt::Vertical
|
|
\param dimension Upper limit for the number of elements
|
|
in a row or column
|
|
|
|
\param parent Parent item
|
|
|
|
\sa orientation, dimension
|
|
*/
|
|
|
|
/*!
|
|
\fn QskLinearBox::~QskLinearBox();
|
|
|
|
Destructor
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::setOrientation( Qt::Orientation orientation );
|
|
|
|
\brief Set the orientation of the layout
|
|
\param orientation Qt::Vertical or Qt::Horizontal
|
|
\sa orientation
|
|
*/
|
|
|
|
/*!
|
|
\fn Qt::Orientation QskLinearBox::orientation() const;
|
|
\return Value of the \ref orientation property
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::transpose()
|
|
|
|
\brief Invert the orientation of the layout
|
|
|
|
Qt::Horizontal becomes to Qt::Vertical and v.v.
|
|
\sa setOrientation(), orientation(), orientationChanged()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::orientationChanged()
|
|
|
|
The orientation of the layout has changed
|
|
\sa orientation
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::setDimension( uint dimension );
|
|
|
|
\brief Set the dimension of the layout
|
|
|
|
\param dimension Upper limit for the number of elements in a row or column
|
|
|
|
\warning A value of 0 is invalid and will be set to 1
|
|
\sa dimension
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QskLinearBox::dimension(void);
|
|
\return Value of the \ref dimension property const
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::dimensionChanged()
|
|
|
|
The dimension of the layout has changed
|
|
\sa setDimension(), dimension()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::spacingChanged()
|
|
|
|
The spacing of the layout has changed
|
|
\sa setSpacing(), spacing(), setRowSpacing(), setColumnSpacing()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::setSpacing( qreal spacing )
|
|
|
|
\brief Set the global spacing of the layout
|
|
\param spacing Distance between each cell and row
|
|
\sa spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::resetSpacing()
|
|
|
|
\brief Reset the global spacing to its initial value
|
|
\sa spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn qreal QskLinearBox::spacing(void) const
|
|
\return Value of the \ref spacing property
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::addSpacer( qreal spacing, int stretchFactor )
|
|
|
|
\brief Append a spacer to the layout
|
|
|
|
The same as \ref insertSpacer( -1, spacing, stretchFactor );
|
|
|
|
\param spacing Spacing
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
\sa insertSpacer()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::insertSpacer( int index, qreal spacing, int stretchFactor )
|
|
|
|
\brief Insert a spacer at a specific position
|
|
|
|
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.
|
|
|
|
\param index Position, where to insert the spacer. If index is < 0
|
|
or beyond QskLayout::itemCount() the spacer will be appended.
|
|
|
|
\param spacing Spacing Minimum for width/height
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\note Calling QskLayout::itemAtIndex( index ) will return a nullptr.
|
|
\sa insertItem(), QskLayout::itemAtIndex()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::addStretch( int stretchFactor )
|
|
|
|
\brief Append a stretch to the layout
|
|
|
|
The same as \ref insertStretch( -1, stretchFactor );
|
|
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\sa insertStretch(), addSpacer()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::insertStretch( int index, int stretchFactor )
|
|
|
|
\brief Insert a stretch at a specific position
|
|
|
|
A stretch is simply a spacer with a spacing of 0
|
|
|
|
\param index Position, where to insert the stretch. If index is < 0
|
|
or beyond QskLayout::itemCount() the stretch will be appended.
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\note Calling QskLayout::itemAtIndex( index ) will return a nullptr.
|
|
\sa insertSpacer(), QskLayout::itemAtIndex()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::setStretchFactor( int index, int stretchFactor )
|
|
|
|
\brief Modify the stretch factor of a layout element
|
|
|
|
\param index Position of the element
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\sa stretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn int QskLinearBox::stretchFactor( int index ) const
|
|
|
|
\param index Position of the inserted element
|
|
\return Stretch factor of a layout element
|
|
|
|
\sa setStretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QskLinearBox::setStretchFactor( const QQuickItem * item, int stretchFactor )
|
|
|
|
\brief Modify the stretch factor of an inserted item
|
|
|
|
\param item Inserted item
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\sa stretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn int QskLinearBox::stretchFactor( const QQuickItem * item ) const
|
|
|
|
\param item Inserted item
|
|
\return Stretch factor of a layout element
|
|
|
|
\sa setStretchFactor()
|
|
*/
|