577 lines
15 KiB
Plaintext
577 lines
15 KiB
Plaintext
/*!
|
|
\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()
|
|
*/
|
|
|