qskinny/doc/classes/QskQuickItem.dox

/*!
    \class QskQuickItem QskQuickItem.h

    \ingroup Framework

    QskQuickItem completes the C++ API of QQuickItem and reestablishs basic
    concepts like events. It also offers better control over the operations
    happening in the update cycle.
 */

/*!
    \enum QskQuickItem::Flag

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

    \var QskQuickItem::Flag QskQuickItem::DeferredUpdate

        Creating of sceme graph nodes is blocked when being invisible.

        The default implementation of Qt/Quick creates scene graph nodes for all items
        in the scene what might become a significant factor for the startup performance
        ( and memory footprint ) of large user interfaces.

        Instead of trying to work around these problems by asynchrounous instantiation
        strategies ( QQmlIncubator ) the DeferredUpdate flag offers a much simpler
        and obvious solution: don't instantiate before really needed.

    \sa 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 QskQuickItem::Flag QskQuickItem::DeferredPolish

        Polishing an item ( QQuickItem::polish() ) is blocked when being invisible.
        F.e for all items being derived from QskControl the layout calculations
        happen during polishing.

    \sa QQuickItem::updatePolish()

    \var QskQuickItem::Flag QskQuickItem::DeferredLayout

        Recalculations of the implicitSize are blocked until being explicitely requested by
        QQuickItem::implicitSize().

		When being enabled the item indicates layout relevant changes by
        sending a QEvent::LayoutRequest ( similar to QWidget ) to its parent item
		without recalculating the actual size hints ( f.e the implicitSize ).

        When having layout code that relies on binding the implicit width/height
        the QskQuickItem::DeferredLayout flag needs to be disabled.

    \note All layout classes offered by the Qt/Quick modules of the Qt Company
          ( f.e anchors ) do require immediate updates of the implicit size. 

    \sa QskQuickItem::resetImplicitSize()

    \var QskQuickItem::Flag QskQuickItem::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 once the item gets shown again.

    \var QskQuickItem::Flag QskQuickItem::PreferRasterForTextures

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

    \var QskQuickItem::Flag QskQuickItem::DebugForceBackground

        Always fill the background of the item with a random color.

    \note This flag is useful when analyzing layouts.

    \sa controlFlags(), setControlFlags(), resetControlFlags()
        testControlFlag(), setControlFlag(), resetControlFlag()
*/

/*!
    \var QskQuickItem::geometry

    This property holds the geometry of the item relative to its parent item.
	When changing the geometry, the item receives a QskEvent::GeometryChange event.

    \sa geometryChangeEvent(), geometryChange(), rect
*/

/*!
    \var QskQuickItem::rect

	This property returns the internal geometry of the item.
	It equals QRect(0, 0, width(), height() ).

    \sa geometryChangeEvent(), geometryChange(), geometry
*/

/*!
    \var QskQuickItem::transparentForPositioners

    When transparentForPositioners is set the item indicates, that it should be excluded
    from any layout calculations. This flag is actually a concept of QQuickItem, that
    has not been exposed to its public API.

    \sa isTransparentForPositioner()
*/

/*!
    \var QskQuickItem::tabFence

    The tabFence flag can be used to create local tab focus chains. It is usually
    used in combination with QQuickItem::ItemIsFocusScope.

    QskPopup is an example where the focus tab chain is expected to continue
    with the first child instead of leaving the popup, when reaching its end.

    \sa isTabFence(), QQuickItem::ItemIsFocusScope
*/

/*!
    \var QskQuickItem::visibleToParent

	Flag indicating if an item would become visible if its parentItem() is shown.
    The implementation relies on the internal explicitVisible flag, that has not
    been exposed by the public API of QQuickItem.

    In many situations it is important to know if an item has been explicitly hidden
    because of a setVisible( false ) or it is a child of an item, that is in
    an invisible state. F,e for calculating the size hint for a hidden container
    it is necessary to know which children would stay hidden when the container
    becomes visible.

    \sa isVisibleToParent(), QQuickItem::setVisible()
*/

/*!
    \var QskQuickItem::polishOnResize

    When polishOnResize is set QQuickItem::polish() will be called automatically
    whenevent the size of the item has been changed. This is usually necessary
    when the item is a container and the layout of its children depends on the
    size of the container.

    \sa QskControl::updateLayout(), QskControl::autoLayoutChildren
*/

/*!
    \var QskQuickItem::initiallyPainted

    Status flag indicating that there has already been a call
    of QQuickItem::updatePaintNode() since the item has become visible.

    Before each initial call of updatePaintNode() the specific
    hook aboutToShow() is called, that is intended to be overloaded.

    \sa isInitiallyPainted(), aboutToShow()
*/

/*!
    \var QskQuickItem::hasChildItems

    A property indicating if the item has child items.

    \sa QQuickItem::childItems(), QQuickItem::parentItem()
*/

/*!
    \fn QskQuickItem::QskQuickItem

    Sets the QQuickItem::ItemHasContents flag to true.
*/

*!
    \fn QskQuickItem::~QskQuickItem

    Sets the componentComplete to false, so that its about-to-delete state is known
    whn detaching it from parent/window.
*/

/*!
    \fn QskQuickItem::className

    A convenience wrapper for metaObject()->className()
    \return Class name
*/

/*!
    \fn QskQuickItem::isVisibleTo

    The true case occurs if neither the item itself nor any parent up to but excluding
    ancestor has been explicitly hidden.

    \param ancestor Ancestor is the parentItem() hierarchy
    \return true if this item would become visible if ancestor is shown; otherwise returns false.

    \sa visibleToParent
*/

/*!
    \fn QskQuickItem::isVisibleToParent

    An item might be invisible because it has been explicitly hidden or
    one of its ancestors has been hidden. isVisibleToParent() indicates
    the first situation.
    
    \return true once QQuickItem::setVisible( false ) has been called

	\sa visibleToParent, QQuickItem::setVisible()
*/

/*!
    \fn QskQuickItem::hasChildItems() const

    \return true, if the item has child items
    \sa hasChildItems
*/

/*!
    \fn QskQuickItem::setGeometry( qreal, qreal, qreal, qreal )

	Set the position and the size of an item

	\param x X ( = left ) coordinate relative to the parent item 
	\param y Y ( = top ) coordinate relative to the parent item 
	\param width Width
	\param height Height

	\sa geometry(), geometryChange(), QQuickItem::size(), QQuickItem::position()
*/

/*!
    \fn QskQuickItem::setGeometry( const QRectF& )

    Set the position and the size of an item

    \param rect Geometry relative to the parent item

	\sa geometry(), geometryChange(), QQuickItem::size(), QQuickItem::position()
*/

/*!
    \fn QskQuickItem::geometry() const

	\return Position and size relative to the parent item
    \sa geometry, setGeometry()
*/

/*!
    \fn QskQuickItem::geometryChange

    This overloaded notifier calls QQuickItem::polish() depending on the
    polishOnResize() flag and forwards the notification to the event queue.

    \sa geometryChangeEvent(), polishOnResize()
*/

/*!
    \fn QskQuickItem::rect() const

	\return Internal geometry of the item, where the position is always at ( 0, 0 )
    \sa geometry
*/

/*!
    \fn QskQuickItem::implicitSize

    Qt/Quick offers an oversimplified layout system of Qt/Quick that is based on the
    property bindings of implicit width and height. QSkinny restablishs a layout
    system that can compete with what is available in the Qt/Widgets or Qt/Graphics
    technologies.

    In the QSkinny layout system the implicitSize is a synonym for what is also known
    as sizeHint or preferredSize.

    \return Implicit size, 

    \note Layout code that relies on property bindings of the implicit width a height
          needs to disable the QskQuickItem::DeferredLayout flag

    \sa QQuickItem::implicitWidth(), QQuickItem::implicitHeight(),
        QskControl::preferredSize(), QskControl::sizeHint()
*/

/*!
    \fn QskQuickItem::setPolishOnResize

	Set or clear the polishOnResize flag.
    \sa polishOnResize
*/

/*!
    \fn QskQuickItem::polishOnResize() const

	\return Value of the polishOnResize flag
	\sa setPolishOnResize()
*/

/*!
    \fn QskQuickItem::setTransparentForPositioner

	Set or clear the transparentForPositioner flag
	\sa isTransparentForPositioner()
*/

/*!
    \fn QskQuickItem::isTransparentForPositioner

	\return Value of the transparentForPositioner flag
	\sa transparentForPositioner
*/

/*!
    \fn QskQuickItem::setTabFence

	Set or clear the tabFence property
	\sa isTabFence()
*/

/*!
    \fn QskQuickItem::isTabFence

	\return Value of the tabFence property
	\sa setTransparentForPositioner()
*/

/*!
    \fn QskQuickItem::setLayoutMirroring

	Change the direction how the content is layed out horizontally.

	\param on True enables layoutMirroring
    \param childrenInherit If true the mirroring behavior is propagated
                           to all child items as well. 

    Changes of this property will be indicated by a QEvent::LayoutDirectionChange.

	\sa layoutMirroring, resetLayoutMirroring(), changeEvent()
	\note In Qml the parameters are routed through the attached LayoutMirroring property
          to have something declarative
*/

/*!
    \fn QskQuickItem::resetLayoutMirroring

	Clear the layoutMirroring property

	\sa setLayoutMirroring(), layoutMirroring
*/

/*!
    \fn QskQuickItem::layoutMirroring() const

	Direction how the content is layed out horizontally.

    If no value has been explicitly assigned it is inherited
	from the closest ancestor, where the attribute has been
    assigned with the childrenInherit parameter. If such an ancestor
    does not exists layoutMirroring is false.

	\return Inherited or explicitly assigned value

    \sa setLayoutMirroring(), layoutMirroring()
    \todo Several controls do not respect this flag

	\sa setLayoutMirroring(), resetLayoutMirroring()
    \note Several controls do not respect this flag
	\note In Qml the parameters are routed through the attached LayoutMirroring property
          to have something declarative
*/

/*!
    \fn QskQuickItem::setControlFlags

	bla
*/

/*!
    \fn QskQuickItem::resetControlFlags

	bla
*/

/*!
    \fn QskQuickItem::controlFlags

	bla
*/

/*!
    \fn QskQuickItem::setControlFlag

	bla
*/

/*!
    \fn QskQuickItem::resetControlFlag

	bla
*/

/*!
    \fn QskQuickItem::testControlFlag

	bla
*/

/*!
    \fn QskQuickItem::controlFlagsChanged

	bla
*/

/*!
    \fn QskQuickItem::classBegin

	The QML engine initilizes an item as being incomplete by
    explicitely calling QQuickItem::classBegin(). Once the item
    has been constructed componentComplete() is called. This way
    temporary operations during the construction can be avoided.
    
    In the C++ case the item indicates being complete from
    the beginning and both hooks are never called.

	The overloaded version calls the base class and has no
    purpose beside being an entry point for debugging.
    
    \sa componentComplete(), QQuickItem::isComponentComplete()
*/

/*!
    \fn QskQuickItem::componentComplete

    The QML engine initilizes an item as being incomplete by
    explicitely calling QQuickItem::classBegin(). Once the item
    has been constructed componentComplete() is called. This way
    temporary operations during the construction can be avoided.

    In the C++ case the item indicates being complete from
    the beginning and both hooks are never called.

	The overloaded does some sanity checks in debug mode
	and calls the base class.

	\sa classBegin(), QQuickItem::isComponentComplete()
*/

/*!
    \fn QskQuickItem::releaseResources

	This specific hook is called, when the item is about to be removed
    from the window it was previously rendering to. 

	The implementation stores the values needed for the following QskWindowChangeEvent.

	\sa windowChangeEvent()
*/

/*!
    \fn QskQuickItem::isPolishScheduled

	\return True, if the item will be polished in the next
            scene graph update cycle.
	\sa QQuickItem::polish(), isUpdateNodeScheduled()
*/

/*!
    \fn QskQuickItem::isUpdateNodeScheduled

	\return True, if the item will update the paint node in
            the next scene graph update cycle
*/

/*!
    \fn QskQuickItem::isInitiallyPainted

    \return Value of the initiallyPainted propertyk
	\sa initiallyPainted
*/

/*!
    \fn QskQuickItem::maybeUnresized
*/

/*!
    \fn QskQuickItem::itemFlagsChanged
*/

/*!
    \fn QskQuickItem::show

	An alternative way to call setVisible( true ).
	Useful for signal/slot connections

	\sa hide(), setVisible()
*/

/*!
    \fn QskQuickItem::hide

	An alternative way to call setVisible( false ).
	Useful for signal/slot connections

	\sa show(), setVisible()
*/

/*!
    \fn QskQuickItem::setVisible

	QQuickItem::setVisible() has been forgotten to be declared as slot.

	\param on If true the item becomes visible if its parent is visible.
              Otherwise the item is hidden.

	\sa QQuickItem::isVisible(), visibleToParent
*/

/*!
    \fn QskQuickItem::resetImplicitSize

	Notifies the layout system that attributes affecting the layout
    system have changed.

    If the QskQuickItem::DeferredLayout flag is enabled ( = default )
    the cached implicitSize() gets invalidated and a QEvent::LayoutRequest is sent
    to the parent item ( like QWidget::updateGeometry ).

    Otherwise the implicitSize() gets recalculated and layout updates can
    be executed using property bindings.
*/

/*!
    \fn QskQuickItem::event
*/

/*!
    \fn QskQuickItem::changeEvent
*/

/*!
    \fn QskQuickItem::geometryChangeEvent

    For no known reason QQuickItem propagates changes of position and size
    by calling QQuickItem::geometryChange(), instead of using events.

    QskQuickItem reestablished the more powerful concept of events by sending/posting
    events, that can be preprocessed by event filtering.

    \param event Event indicating the geometry change

    \sa QObject::installEventFilter(), geometryChange()
*/

/*!
    \fn QskQuickItem::windowChangeEvent

*/

/*!
    \fn QskQuickItem::itemChange
*/

/*!
    void \fn QskQuickItem::aboutToShow

    A specific hook that is intended to be overloaded by controls that need
    to do some specific operations, when an item is painted the first time
    after becoming visisble.

    The default implementation is a no operation.

    \sa initiallyPainted, QQuickItem::setVisible()
*/