/*!
	\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.
	*/
};