INTERFACE
    CLASS: QskControl
    BASE: QQuickItem

    QMLCLASS: Control
    QMLBASE: Item

    HEADER: QskControl.h

    DESCRIPTION
        \brief Base class of all Qsk controls

        QskControl is the base class for most visible Qsk controls.

        It re-establishes several concepts known from QWidget, that got lost
        with QQuickItem:

        - contentsRect()
        - autoFillBackground()
        - support of layout rules: sizeHint(), sizePolicy()
        - font, palette, locale and their propagation on the item tree

        Even if QQuickItem is part of the public C++ API it has obviously been
        designed for implementing custom items, but not for using them in C++
        code. To support this use case a lot of trivial methods have been added.

        For some reason the QQuick classes introduced proprietory notfier hooks
        instead of using the well established and powerful concept of events.
        QskControl tries to revert this decision by mapping notifications
        to events, when possible.

        The following events are currently implemented:

        - QEvent::FontChange
        - QEvent::PaletteChange
        - QEvent::LocaleChange
        - QEvent::LayoutDirectionChange
        - QEvent::ContentsRectChange
        - QEvent::LayoutRequest
    END

    ENUM
        CLASS: Flag
        QMLCLASS: Flag

        DESCRIPTION
            QQuick classes have a tendency to update items too early
            and too often. To avoid processing of unwanted operations
            QskControl implements a couple of modifications, that
            can be en/disabled individually.

            The default setting enables all attributes.

            \var ClipBoundary

                 If ClipBoundary is enabled the control initially sets a
                 clip for its bounding rectangle.

                 \sa QQuickItem::setClip()

            \var DeferredUpdate

                Creating of paint nodes is blocked for all invisible nodes
                ( QQuickItem::isVisible() ).

                \note Some more advanced algorithms have not yet been implemented,
                such as viewport frustrum culling (i.e. hiding items outside of the
                window geometry).

            \var DeferredPolish

                Calculation of layouts ( updateLayout() ) is blocked for all invisible
                nodes ( QQuickItem::isVisible() ).

            \var DeferredLayout

                Updates of the implicit size is blocked until effectiveConstraint() or sizeHint()
                is explicitly called. When being enabled the implicit size is not recalculated before
                being requested - usually by a QskLayout.

            \var CleanupOnVisibility

                Delete scene graph nodes, when the item becomes hidden ( QQuickItem::isVisible() ).
                Enabling this mode will reduce the memory footprint, but comes at the cost
                of having to recreate nodes later.

            \var PreferRasterForTextures

                When creating textures from QskGraphic, prefer the raster paint
                engine over the OpenGL paint engine.

            \var DebugForceBackground

                Always fill the background of thecontrol with a random color.
                \note This flag is useful when analyzing layouts.
        END
    END

    INVOKABLE
        SIGNATURE: void setControlFlag( Flag, bool on = true );
        DESCRIPTION
        END
    END

    INVOKABLE
        SIGNATURE: void resetControlFlag( Flag );
        DESCRIPTION
        END
    END

    INVOKABLE
        SIGNATURE: bool testControlFlag( Flag ) const;
        DESCRIPTION
        END
    END

    FUNCTION
        SIGNATURE: void setColor( QskAspect::Aspect aspect, const QColor &color )
        DESCRIPTION: Sets the color (as a QColor) for the given QskSkinHint.
    END

    FUNCTION
        SIGNATURE: void setColor( QskAspect::Aspect aspect, Qt::GlobalColor color )
        DESCRIPTION: Sets the color (as a Qt::GlobalColor) for the given QskSkinHint.
    END

    FUNCTION
        SIGNATURE: void setColor( QskAspect::Aspect aspect, QRgb color )
        DESCRIPTION: Sets the color (as a QRgb value) for the given QskSkinHint.
    END

    FUNCTION
        SIGNATURE: QRgb color( QskAspect::Aspect aspect ) const
        DESCRIPTION: A convenience method equivalent to QskControl::skinHint().color.
    END

    FUNCTION
        SIGNATURE: void setMetric( QskAspect::Aspect aspect, float metric )
        DESCRIPTION: Sets the metric for the given QskSkinHint.
    END

    FUNCTION
        SIGNATURE: float metric( QskAspect::Aspect aspect ) const
        DESCRIPTION
            A convenience method equivalent to skinHint( aspect ).metric. The
            QskSkinHint::TypeMask is set to QskSkinHint::Metric.
        END
    END

    FUNCTION
        SIGNATURE: void setSkinlet( QskSkinlet* skinlet )
        DESCRIPTION
            Allows overriding the QskControl::Skin used by this control to render its
            contents.
        END
    END

    FUNCTION
        SIGNATURE: const QskSkinlet* skinlet() const;
        DESCRIPTION
            \return Skinlet assigned by setSkinlet().
            \sa effectiveSkinlet()
        END
    END

    FUNCTION
        SIGNATURE: QskSkinHint skinHint( QskAspect::Aspect aspect ) const
        DESCRIPTION
            Returns the QskSkinHint value for a QskAspect::Aspect. If none is set for
            this control, the value for QskSkin::skinHint() is returned.

            \note If a QskSkinHintProvider is animating the color when called, the returned
                  value will be the current value, not the target value, unless a state mask
                  is requested as part of the aspect.

            \param aspect Aspect
        END
    END

    FUNCTION
        SIGNATURE: void updateNode( QSGNode* parentNode )
        DESCRIPTION
            This method replaces the QQuickItem::updatePaintNode method as the
            preferred paint method to override when subclassing QskControl. This allows
            QskControl to perform some additional steps before calling updateNode(),
            and provides a consistent parent node which subclasses can rely on.

            Subclasses should call their Skin's updateNode() method inside this
            method.

            \param parentNode The parent of the nodes to be added in this method.
            \return The parent node.
        END
    END
END