qskinny/doc/classes/QskLinearBox.dox

/*!
    \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()
*/