471 lines
12 KiB
Plaintext
471 lines
12 KiB
Plaintext
/*!
|
|
\headerfile 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
|
|
*/
|
|
|
|
class QskLinearBox
|
|
{
|
|
public:
|
|
|
|
/*!
|
|
\property Qt::Orientation 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 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 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( QQuickItem * parent );
|
|
|
|
\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( 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( Qt::Orientation orientation,
|
|
int dimension, QQuickItem * parent );
|
|
|
|
\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();
|
|
|
|
Destructor
|
|
*/
|
|
|
|
/*!
|
|
\fn void setOrientation( Qt::Orientation orientation );
|
|
|
|
\brief Set the orientation of the layout
|
|
\param orientation Qt::Vertical or Qt::Horizontal
|
|
\sa orientation
|
|
*/
|
|
|
|
/*!
|
|
\fn Qt::Orientation orientation(void) const;
|
|
\return Value of the \ref orientation property
|
|
*/
|
|
|
|
/*!
|
|
\fn void transpose()
|
|
|
|
\brief Invert the orientation of the layout
|
|
|
|
Qt::Horizontal becomes to Qt::Vertical and v.v.
|
|
\sa setOrientation(), orientation(), orientationChanged()
|
|
*/
|
|
|
|
/*!
|
|
\fn void orientationChanged()
|
|
|
|
The orientation of the layout has changed
|
|
\sa orientation
|
|
*/
|
|
|
|
/*!
|
|
\fn void 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 dimension(void);
|
|
\return Value of the \ref dimension property const
|
|
*/
|
|
|
|
/*!
|
|
\fn void dimensionChanged()
|
|
|
|
The dimension of the layout has changed
|
|
\sa setDimension(), dimension()
|
|
*/
|
|
|
|
/*!
|
|
\fn void spacingChanged()
|
|
|
|
The spacing of the layout has changed
|
|
\sa setSpacing(), spacing(), setRowSpacing(), setColumnSpacing()
|
|
*/
|
|
|
|
/*!
|
|
\fn void setSpacing( qreal spacing )
|
|
|
|
\brief Set the global spacing of the layout
|
|
\param spacing Distance between each cell and row
|
|
\sa spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn void resetSpacing()
|
|
|
|
\brief Reset the global spacing to its initial value
|
|
\sa spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn qreal spacing(void) const
|
|
\return Value of the \ref spacing property
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn void 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 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 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 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 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 stretchFactor( int index ) const
|
|
|
|
\param index Position of the inserted element
|
|
\return Stretch factor of a layout element
|
|
|
|
\sa setStretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn void 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 stretchFactor( const QQuickItem * item ) const
|
|
|
|
\param item Inserted item
|
|
\return Stretch factor of a layout element
|
|
|
|
\sa setStretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn void setRetainSizeWhenHidden( int index, bool on )
|
|
|
|
\brief Modify the effect of an element on the layout, when being hidden
|
|
|
|
The retainSizeWhenHidden() flag controls how the layout will treat
|
|
an item, when being explicitely hidden.
|
|
|
|
When being enabled the corresponding cell will be resized like in the visible
|
|
state ( showing a blank space ). Otherwise the cell will disappear and all
|
|
following cells will be shifted down.
|
|
|
|
\param index Position of the inserted element
|
|
\param on En/Disable the retainSizeWhenHidden() flag
|
|
|
|
\sa QQuickItem::isVisible()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool retainSizeWhenHidden( int index ) const
|
|
|
|
\param index Position of the inserted element
|
|
\return True, when the retainSizeWhenHidden() flag is enabled
|
|
*/
|
|
|
|
/*!
|
|
\fn void setRetainSizeWhenHidden( const QQuickItem * item, bool on )
|
|
|
|
\brief Modify the effect of an element on the layout, when being hidden
|
|
|
|
The retainSizeWhenHidden() flag controls how the layout will treat
|
|
an item, when being explicitely hidden.
|
|
|
|
When being enabled the corresponding cell will be resized like in the visible
|
|
state ( showing a blank space ). Otherwise the cell will disappear and all
|
|
following cells will be shifted down.
|
|
|
|
\param item Inserted item
|
|
\param on En/Disable the retainSizeWhenHidden() flag
|
|
|
|
\sa QQuickItem::isVisible()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool retainSizeWhenHidden( const QQuickItem * item ) const
|
|
|
|
\param item Inserted item
|
|
\return True, when the retainSizeWhenHidden() flag is enabled
|
|
*/
|
|
|
|
/*!
|
|
\fn void setRowSpacing( int row, qreal spacing )
|
|
|
|
\brief Add an extra spacing at the end of a row
|
|
|
|
\param row Row index
|
|
\param spacing Extra space at the end of a row
|
|
|
|
\note The spacing has no effect for the last row
|
|
\sa rowSpacing(), setColumnSpacing(), spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn qreal rowSpacing( int row ) const
|
|
|
|
\param row Row index
|
|
\return Extra space at the end of a row
|
|
\sa setRowSpacing(), spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn void setColumnSpacing( int column, qreal spacing )
|
|
|
|
\brief Add an extra spacing at the end of a column
|
|
|
|
\param column Column index
|
|
\param spacing Extra space at the end of a column
|
|
|
|
\note The spacing has no effect for the last column
|
|
\sa columnSpacing(), setRowSpacing(), spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn qreal columnSpacing( int column ) const
|
|
|
|
\param column Column index
|
|
\return Extra space at the end of a column
|
|
\sa setColumnSpacing(), rowSpacing(), spacing
|
|
*/
|
|
|
|
/*!
|
|
\fn void setRowStretchFactor( int row, int stretchFactor )
|
|
|
|
\brief Modify the stretch factor of a row
|
|
|
|
\param row Index of the row
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\note Having a stretch factor for the row and for an item of the same row
|
|
might lead to confusing results
|
|
|
|
\sa rowStretchFactor(), stretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn int rowStretchFactor( int row ) const
|
|
|
|
\param row Index of the row
|
|
\return Stretch factor of the row
|
|
\sa setRowStretchFactor(), colulnStretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn void setColumnStretchFactor( int column, int stretchFactor )
|
|
|
|
\brief Modify the stretch factor of a column
|
|
|
|
\param column Index of the column
|
|
\param stretchFactor A value between [0..10].
|
|
The ratio of the stretch factors of expandable
|
|
candidates decides about how to distribute extra space.
|
|
|
|
\note Having a stretch factor for the column and for an item of the same column
|
|
might lead to confusing results
|
|
|
|
\sa rowStretchFactor(), stretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn int QskLinearBox::columnStretchFactor( int column ) const
|
|
|
|
\param column Index of the column
|
|
\return Stretch factor of the column
|
|
\sa setColumnStretchFactor(), rowStretchFactor()
|
|
*/
|
|
|
|
/*!
|
|
\fn QSizeF QskLinearBox::contentsSizeHint() const
|
|
|
|
\return Preferred size without the contents margins
|
|
\note The calculation of the hint depends ob the hints
|
|
of the items inserted to the layout.
|
|
*/
|
|
};
|