INTERFACE
    CLASS:  QskLinearBox
    BASE:   QskIndexedLayoutBox

    QMLCLASS: LinearBox
    QMLBASE: IndexedLayoutBox

    HEADER: QskLinearBox.h

    DESCRIPTION
		\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 QUICKITEMs 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
    END

	PROPERTY
		NAME: orientation
		TYPE: Qt::Orientation

		READ: orientation()
		WRITE: setOrientation()
		NOTIFY: orientationChanged()

		DESCRIPTION
		
			\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
		END
	END

    PROPERTY
        NAME: dimension
        TYPE: uint

		READ: dimension()
        WRITE: setDimension()
        NOTIFY: dimensionChanged()

        DESCRIPTION
			\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
        END
    END

    PROPERTY
        NAME: spacing
        TYPE: qreal

        READ: spacing()
        WRITE: setSpacing()
        NOTIFY: spacingChanged()
        
        DESCRIPTION
			\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()
        END
    END 

    FUNCTION
        SIGNATURE: QskLinearBox( QUICKITEM parent );
        DESCRIPTION
			\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
        END
    END

    FUNCTION
        SIGNATURE: QskLinearBox( Qt::Orientation orientation, QUICKITEM parent );
		DESCRIPTION
			\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
		END
	END

	FUNCTION
		SIGNATURE
			QskLinearBox( Qt::Orientation orientation, 
				int dimension, QUICKITEM parent );
		END

		DESCRIPTION
			\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
		END
	END

    FUNCTION
        SIGNATURE: ~QskLinearBox();
		DESCRIPTION: Destructor
	END

	FUNCTION
		SIGNATURE: void setOrientation( Qt::Orientation orientation );
		DESCRIPTION
			\brief Set the orientation of the layout
			\param orientation Qt::Vertical or Qt::Horizontal
			\sa orientation
		END
	END

	FUNCTION
		SIGNATURE: Qt::Orientation orientation(void) const;
		DESCRIPTION: \return Value of the \ref orientation property
	END

	SLOT
		SIGNATURE: void transpose()
		DESCRIPTION
		BEGIN
			\brief Invert the orientation of the layout

			Qt::Horizontal becomes to Qt::Vertical and v.v.
			\sa setOrientation(), orientation(), orientationChanged()
		END
	END

    SIGNAL
        SIGNATURE: void orientationChanged()
        DESCRIPTION
			The orientation of the layout has changed
			\sa orientation
        END
    END

	FUNCTION
		SIGNATURE: void setDimension( uint dimension );
		DESCRIPTION
			\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
		END
	END

	FUNCTION
		SIGNATURE: uint dimension(void);
		DESCRIPTION: \return Value of the \ref dimension property const
	END

    SIGNAL
        SIGNATURE: void dimensionChanged()
        DESCRIPTION
			The dimension of the layout has changed
			\sa setDimension(), dimension()
        END 
    END 

    SIGNAL
        SIGNATURE: void spacingChanged()
        DESCRIPTION
			The spacing of the layout has changed
			\sa setSpacing(), spacing(), setRowSpacing(), setColumnSpacing()
        END
    END

	FUNCTION
		SIGNATURE: void setSpacing( qreal spacing )
		DESCRIPTION
			\brief Set the global spacing of the layout
			\param spacing Distance between each cell and row
			\sa spacing
		END
	END

	FUNCTION
		SIGNATURE: void resetSpacing()
		DESCRIPTION
			\brief Reset the global spacing to its initial value
			\sa spacing
		END
	END

	FUNCTION
		SIGNATURE: qreal spacing(void) const
		DESCRIPTION
			\return Value of the \ref spacing property
		END

	END

	INVOKABLE
		SIGNATURE: void addSpacer( qreal spacing, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: void insertSpacer( int index, qreal spacing, int stretchFactor )
		DESCRIPTION
			\brief Insert a spacer at a specific position

			Spacers being inserted to the layout are elements having
			an index - like regular QUICKITEMs 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()
		END
	END

	INVOKABLE
		SIGNATURE: void addStretch( int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: void insertStretch( int index, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: void setStretchFactor( int index, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: int stretchFactor( int index ) const
		DESCRIPTION
			\param index Position of the inserted element
			\return Stretch factor of a layout element

			\sa setStretchFactor()
		END
	END

	INVOKABLE
		SIGNATURE: void setStretchFactor( const QUICKITEM item, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: int stretchFactor( const QUICKITEM item ) const
		DESCRIPTION
			\param item Inserted item
			\return Stretch factor of a layout element

			\sa setStretchFactor()
		END
	END

	INVOKABLE
		SIGNATURE: void setRetainSizeWhenHidden( int index, bool on )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: bool retainSizeWhenHidden( int index ) const
		DESCRIPTION
			\param index Position of the inserted element
			\return True, when the retainSizeWhenHidden() flag is enabled
		END
	END
    
	INVOKABLE
		SIGNATURE: void setRetainSizeWhenHidden( const QUICKITEM item, bool on )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: bool retainSizeWhenHidden( const QUICKITEM item ) const
		DESCRIPTION
			\param item Inserted item
			\return True, when the retainSizeWhenHidden() flag is enabled
		END
	END

	INVOKABLE
		SIGNATURE: void setRowSpacing( int row, qreal spacing )
		DESCRIPTION
			\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
		END
	END

	INVOKABLE
		SIGNATURE: qreal rowSpacing( int row ) const
		DESCRIPTION
			\param row Row index
			\return Extra space at the end of a row
			\sa setRowSpacing(), spacing
		END
	END

	INVOKABLE
		SIGNATURE: void setColumnSpacing( int column, qreal spacing )
		DESCRIPTION
			\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
		END
	END

	INVOKABLE
		SIGNATURE: qreal columnSpacing( int column ) const
		DESCRIPTION
			\param column Column index
			\return Extra space at the end of a column
			\sa setColumnSpacing(), rowSpacing(), spacing
		END
	END

	INVOKABLE
		SIGNATURE: void setRowStretchFactor( int row, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: int rowStretchFactor( int row ) const
		DESCRIPTION
			\param row Index of the row
			\return Stretch factor of the row
			\sa setRowStretchFactor(), colulnStretchFactor()
		END
	END

	INVOKABLE
		SIGNATURE: void setColumnStretchFactor( int column, int stretchFactor )
		DESCRIPTION
			\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()
		END
	END

	INVOKABLE
		SIGNATURE: int QskLinearBox::columnStretchFactor( int column ) const
		DESCRIPTION
			\param column Index of the column
			\return Stretch factor of the column
			\sa setColumnStretchFactor(), rowStretchFactor()
		END
	END

	FUNCTION
		SIGNATURE: QSizeF QskLinearBox::contentsSizeHint() const
		DESCRIPTION
			\return Preferred size without the contents margins
			\note The calculation of the hint depends ob the hints
				  of the items inserted to the layout.
		END
	END
END