qskinny/doc/classes/QskControl.dox

/*!
    \class QskControl QskControl.h
    \ingroup Framework Controls

    \brief Base class of all controls

    QskControl combines the themeability implemented in QskSkinnable with
    what is needed to support a layout system, that is on par with what
    is known from Qt/Widgets.

    \todo Explain: QskQuickItem::geometry(), QskQuickItem::rect(),
                   QQuickItem::boundingRect(), layoutRect(), contentsRect(),
                   subControlRect(), focusIndicatorRect(), QQuickItem::clipRect(),
                   QQuickItem::contains() 

    \states QskControl::Disabled, QskControl::Hovered, QskControl::Focused
*/

/*!
    \var QskControl::Disabled

        A state bit that is set, when QQuickItem::isEnabled() == false.

    \extends QskAspect::State
    \sa   QskQuickItem::setDisabled()
    \saqt QQuickItem::enabled

    \var QskControl::Hovered

        A state bit that is set, when the item is hovered
        It allows to define a specific representation in the skin,
        when being hovered.

    \saqt QQuickItem::acceptHoverEvents(), QQuickItem::hoverEnterEvent(),
          QQuickItem::hoverLeaveEvent()

    \var QskControl::Focused

        A state bit that is set, when the item is the active focus item

    \sa   focusPolicy
    \saqt QQuickItem::acceptHoverEvents(), QQuickItem::focusInEvent()
          QQuickItem::focusOutEvent()
*/

/*!
    \enum QskControl::LayoutHint

    Hints, that can be used by the layout code

    \sa setLayoutHint(), testLayoutHint(), setLayoutHints(), layoutHints()
        setAutoLayoutChildren(), QskLinearBox, QskGridBox, QskStackBox

    \var QskControl::RetainSizeWhenHidden

        When being enabled the layout code should retain the necessary space
        for the control even when it is hidden.

    \saqt QSizePolicy::retainSizeWhenHidden()

    \var QskControl::LayoutWhenHidden

        When being enabled the layout code should set the geometry
        to the control - even if it is not visible.
*/

/*!
    \property QLocale QskControl::locale

    \accessors locale(), setLocale(), resetLocale(), localeChanged()
*/

/*!
    \property bool QskControl::autoFillBackground

    This property holds whether the background is filled automatically
    with the background gradient.

    \accessors autoFillBackground(), setAutoFillBackground()

    \sa background()
    \saqt QWidget::autoFillBackground

*/

/*!
    \property bool QskControl::autoLayoutChildren

    \accessors autoLayoutChildren(), setAutoLayoutChildren()
*/

/*!
    \property Qt::FocusPolicy QskControl::focusPolicy

    \accessors focusPolicy(), setFocusPolicy(), focusPolicyChanged()
*/

/*!
    \property bool QskControl::wheelEnabled

    \accessors isWheelEnabled(), setWheelEnabled(), wheelEnabledChanged()
*/

/*!
    \property bool QskControl::visibleToLayout

    \accessors isVisibleToLayout()
*/

/*!
    \property QskMargins QskControl::margins

    \accessors margins(), setMargins(), resetMargins(), marginsChanged()
*/

/*!
    \property QskGradient QskControl::background

    \accessors background(), setBackground(), resetBackground(), backgroundChanged()
*/

/*!
    \property QskSizePolicy QskControl::sizePolicy

    \accessors sizePolicy(), setSizePolicy()
*/

/*!
    \property bool QskControl::autoLayoutChildren

    \accessors autoLayoutChildren(), setAutoLayoutChildren()
*/

/*!
    \property QSizeF QskControl::minimumSize

    \accessors minimumSize(), setMinimumSize()
    \sa effectiveSizeHint(), setExplicitSizeHint()
        setMinimumWidth(), setMinimumHeight()
*/

/*!
    \property QSizeF QskControl::maximumSize
    
    \accessors maximumSize(), setMaximumSize()
    \sa effectiveSizeHint(), setExplicitSizeHint()
        setMaximumWidth(), setMaximumHeight()
*/

/*!
    \property QSizeF QskControl::preferredSize

    \accessors preferredSize(), setPreferredSize()
    \sa effectiveSizeHint(), setExplicitSizeHint(),
        setPreferredWidth(), setPreferredHeight()
*/

/*!
    \property QSizeF QskControl::sizeConstraint

    \accessors sizeConstraint()
*/

/*!
    \fn QskControl::QskControl

    Initializes the focusPolicy() to Qt::NoFocus and disables
    processing of wheel events. The default sizePolicy is
    QskSizePolicy::Preferred in vertical and horizontal direction.
*/

/*!
    \fn QskControl::~QskControl

    Destructor
*/

/*!
    \fn QskControl::setMargins( qreal )

    Sets the margins around the contents of the control 

    The value is stored in the local hint table for the aspect:
         QskControl::Control | QskAspect::Metric | QskAspect::Margin

    \param margin Margin for all sides
    \aspect QskControl::Control | QskAspect::Metric | QskAspect::Margin

    \sa contentsRect(), margins(), QskSkinnable::setMarginHint()
*/

/*!
    \fn QskControl::setMargins( const QMarginsF& )

    Sets the margins around the contents of the control 

    \param margins Margins
    \aspect QskControl::Control | QskAspect::Metric | QskAspect::Margin

    \sa contentsRect(), margins()
    \saqt QEvent::ContentsRectChange
*/

/*!
    \fn QskControl::resetMargins

    Reset the margins to the default value provided from the skin

    \aspect QskControl::Control | QskAspect::Metric | QskAspect::Margin

    \sa contentsRect(), setMargins(), margins()
    \saqt QEvent::ContentsRectChange
*/

/*!
    \fn QskControl::margins() const

    \return margins around the contents of the control
    \aspect QskControl::Control | QskAspect::Metric | QskAspect::Margin

    \sa contentsRect(), setMargins()
    \saqt QEvent::ContentsRectChange
*/

/*!
    \fn QskControl::setBackgroundColor

    A conveninece method that enables the autoFillBackground property
    and sets a solid color as background. Usually used for debugging
    layout problems.

    \sa setBackground(), setAutoFillBackground()
    \sa QskQuickItem::DebugForceBackground
*/

/*!
    \fn QskControl::setBackground

    Set the gradient that is used to fill the background,
    when autoFillBackground is enabled.

    \aspect QskControl::Control | QskAspect::Color
    \sa resetBackground(), background(), autoFillBackground()
*/

/*!
    \fn QskControl::resetBackground

    Reset the background gradient to the default colors from the skin 

    \aspect QskControl::Control | QskAspect::Color
    \sa setBackground(), background(), autoFillBackground()
*/

/*!
    \fn QskControl::background() const

    \return Gradient that is used to fill the background,
            when autoFillBackground is enabled.

    \aspect QskControl::Control | QskAspect::Color
    \sa setBackground(), resetBackground(), autoFillBackground()
*/

/*!
    \fn QskControl::contentsRect

    Returns the area inside the controls's margins.

    contentsRect() is a rectangle being used for laying out scene graph nodes,
    while layoutRect() is used for child items.

    \sa margins(), setMargins(), layoutRect()
*/

/*!
    \fn QskControl::layoutRect

    Returns the area for laying out child items

    layoutRect() is a rectangle being used for laying out child items,
    while contentsRect() is used for scene graph nodes. 

    F.e QskBox::layoutRect() returns an area that fits inside the ( maybe rounded )
    borders, while the borders itself are rendered into the contentsRect().

    The implementation relies on layoutRectForSize()

    \sa layoutRectForSize(), contentsRect()
*/

/*!
    \fn QskControl::layoutRectForSize

    Returns the geometry where to lay out child items for a given size.

    layoutRectForSize() is intended to be overloaded, when layoutRect()
    is supposed differ from contentsRect()

    \param size Size Bounding size for the control
    \return Area, where to lay out the child items
*/

/*!
    \fn QskControl::gestureRect

    Returns the area where to accept gestures.
    The default implementation returns QskQuickItem::rect().

    \sa gestureFilter(), gestureEvent()
*/

/*!
    \fn QskControl::focusIndicatorRect

    Returns the rectangle where to draw the focus indicator

    For controls, that implement some sort of internal focus chain
    ( list boxes, sliders with more handles ... ) the rectangle might
    change according to the state of the control.

    The default implementation return contentsRect()

    \sa QskFocusIndicator, focusIndicatorClipRect(), focusIndicatorRectChanged()
*/

/*!
    \fn QskControl::focusIndicatorClipRect

    This is a specific rectangle, that can be returned to clip the focus
    indicator being displayed for a child item.

    The default implementation return QQuickItem::contentsRect()
*/

/*!
    \fn QskControl::subControlRect( QskAspect::Subcontrol ) const

    Calculates the rectangle for a subcontrol from contentsRect().

    \param subControl Subcontrol
    \return Bounding rectangle for the subControl

    \sa QskSkinnable::subControlRect
*/

/*!
    \fn QskControl::subControlRect( const QSizeF&, QskAspect::Subcontrol ) const

    Calculates the rectangle for a subcontrol inside a rectangle at the position
    0, 0 for the given size

    \param subControl Subcontrol
    \param size Size for the control
    \return Bounding rectangle for the subControl

    \sa QskSkinnable::subControlRect
*/

/*!
    \fn QskControl::subControlContentsRect( QskAspect::Subcontrol ) const

    Calculate the inner rectangle for subControl calculated from contentsRect.

    \param subControl Subcontrol
    \return Inner rectangle of the subControl

    \sa QskSkinnable::subControlContentsRect
*/

/*!
    \fn QskControl::subControlContentsRect( const QSizeF&, QskAspect::Subcontrol ) const

    Calculate the inner rectangle for subControl for a rectangle at the position
    0, 0 for the given size

    \param subControl Subcontrol
    \param size Size for the control
    \return Inner rectangle of the subControl

    \sa QskSkinnable::subControlContentsRect
*/

/*!
    \fn QskControl::setAutoFillBackground

    Set or clear the autoFillBackground property
    \sa autoFillBackground()
*/

/*!
    \fn QskControl::autoFillBackground() const

    \return Value of the autoFillBackground property
    \sa setAutoFillBackground()
*/

/*!
    \fn QskControl::setAutoLayoutChildren

    Set or clear the autoLayoutChildren property
    \sa autoFillBackground()
*/

/*!
    \fn QskControl::autoLayoutChildren() const

    \return Value of the autoLayoutChildren property
    \sa autoLayoutChildren()
*/

/*!
    \fn QskControl::setWheelEnabled

    Set or clear the wheelEnabled property
    \sa wheelEnabled isWheelEnabled
*/

/*!
    \fn QskControl::isWheelEnabled

    \return Value of the wheelEnabled property
    \sa wheelEnabled
*/

/*!
    \fn QskControl::setFocusPolicy

    Set the value for the focusPolicy property
    \sa focusPolicy()
*/

/*!
    \fn QskControl::focusPolicy() const

    \return Value of the focusPolicy property
    \sa focusPolicy(), setFocusPolicy()
*/

/*!
    \fn QskControl::setSizePolicy( QskSizePolicy )

*/

/*!
    \fn QskControl::setSizePolicy( QskSizePolicy::Policy, QskSizePolicy::Policy )

*/

/*!
    \fn QskControl::setSizePolicy( Qt::Orientation, QskSizePolicy::Policy )

*/

/*!
    \fn QskControl::sizePolicy() const

*/

/*!
    \fn QskControl::sizePolicy( Qt::Orientation ) const

*/

/*!
    \fn QskControl::setLayoutAlignmentHint

*/

/*!
    \fn QskControl::layoutAlignmentHint

*/

/*!
    \fn QskControl::setLayoutHint

*/

/*!
    \fn QskControl::testLayoutHint

*/

/*!
    \fn QskControl::setLayoutHints

*/

/*!
    \fn QskControl::layoutHints

*/

/*!
    \fn QskControl::isVisibleToLayout

    Return true, when the control is relevant for layout calculations

    A control has an impact on the layout calutaions, when:

    - isTransparentForPositioner() is false
    - QskQuickItem::isVisibleToParent() is true, or RetainSizeWhenHidden is set

    \sa isVisibleToParent(), RetainSizeWhenHidden
*/

/*!
    \fn QskControl::setMinimumSize( const QSizeF& )

*/

/*!
    \fn QskControl::setMinimumSize( qreal, qreal )

*/

/*!
    \fn QskControl::setMinimumWidth

*/

/*!
    \fn QskControl::setMinimumHeight

*/

/*!
    \fn QskControl::setMaximumSize( const QSizeF& )

*/

/*!
    \fn QskControl::setMaximumSize( qreal, qreal )

*/

/*!
    \fn QskControl::setMaximumWidth

*/

/*!
    \fn QskControl::setMaximumHeight

*/

/*!
    \fn QskControl::setPreferredSize( const QSizeF& )

*/

/*!
    \fn QskControl::setPreferredSize( qreal, qreal )

*/

/*!
    \fn QskControl::setPreferredWidth

*/

/*!
    \fn QskControl::setPreferredHeight

*/

/*!
    \fn QskControl::setFixedSize( const QSizeF& );

*/

/*!
    \fn QskControl::setFixedSize( qreal width, qreal height );

*/

/*!
    \fn QskControl::setFixedWidth

*/

/*!
    \fn QskControl::setFixedHeight

*/

/*!
    \fn QskControl::setExplicitSizeHint( Qt::SizeHint, const QSizeF& );

*/

/*!
    \fn QskControl::setExplicitSizeHint( Qt::SizeHint, qreal width, qreal height );

*/

/*!
    \fn QskControl::resetExplicitSizeHint

*/

/*!
    \fn QskControl::minimumSize() const;

*/

/*!
    \fn QskControl::maximumSize() const;

*/

/*!
    \fn QskControl::preferredSize() const;

*/

/*!
    \fn QskControl::explicitSizeHint

*/

/*!
    \fn QskControl::implicitSizeHint

*/

/*!
    \fn QskControl::sizeHint

*/

/*!
    \fn QskControl::heightForWidth

*/

/*!
    \fn QskControl::widthForHeight

*/

/*!
    \fn QskControl::effectiveSizeHint

*/

/*!
    \fn QskControl::sizeConstraint( Qt::SizeHint, const QSizeF& ) const

*/

/*!
    \fn QskControl::sizeConstraint() const

*/

/*!
    \fn QskControl::locale() const

*/

/*!
    \fn QskControl::resetLocale

*/

/*!
    \fn QskControl::subControls

*/

/*!
    \fn void QskControl::backgroundChanged

*/

/*!
    \fn void QskControl::marginsChanged

*/

/*!
    \fn void QskControl::focusIndicatorRectChanged

*/

/*!
    \fn void QskControl::localeChanged

*/

/*!
    \fn void QskControl::focusPolicyChanged

*/

/*!
    \fn void QskControl::wheelEnabledChanged

*/

/*!
    \fn void QskControl::setLocale

*/

/*!
    \fn bool QskControl::event

*/

/*!
    \fn virtual void QskControl::gestureEvent

*/

/*!
    \fn void QskControl::hoverEnterEvent

*/

/*!
    \fn void QskControl::hoverLeaveEvent

*/

/*!
    \fn bool QskControl::childMouseEventFilter

*/

/*!
    \fn virtual bool QskControl::gestureFilter

*/

/*!
    \fn void QskControl::itemChange

*/

/*!
    \fn void QskControl::geometryChange

*/

/*!
    \fn void QskControl::initSizePolicy

*/

/*!
    \fn virtual void QskControl::updateResources

*/

/*!
    \fn virtual void QskControl::updateLayout

*/

/*!
    \fn virtual QSizeF QskControl::contentsSizeHint

*/

/*!
    \fn virtual QSizeF QskControl::layoutSizeHint
*/