qskinny/doc/classes/QskQuickItem.dox
2021-12-14 08:45:49 +01:00

737 lines
21 KiB
Plaintext

/*!
\class QskQuickItem QskQuickItem.h
\ingroup Framework
QskQuickItem completes the C++ API of QQuickItem and re-establishs basic
concepts like events. It also offers better control over the operations
happening in the update cycle.
*/
/*!
\enum QskQuickItem::UpdateFlag
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.
\sa updateFlags(), resetUpdateFlags()
testUpdateFlag(), setUpdateFlag(), resetUpdateFlag()
\var QskQuickItem::UpdateFlag QskQuickItem::DeferredUpdate
Creating of scene 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.
\saqt 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::UpdateFlag QskQuickItem::DeferredPolish
Polishing an item is blocked when being invisible.
F.e for all items being derived from QskControl the layout calculations
happen during polishing.
\saqt QQuickItem::updatePolish(), QQuickItem::polish()
\var QskQuickItem::UpdateFlag QskQuickItem::DeferredLayout
Recalculations of the implicitSize are blocked until being explicitly requested.
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()
\saqt QQuickItem::implicitSize()
\var QskQuickItem::UpdateFlag QskQuickItem::CleanupOnVisibility
Delete scene graph nodes, when the item becomes hidden.
Enabling this mode will reduce the memory footprint, but comes at the cost
of having to recreate nodes once the item gets shown again.
\saqt QQuickItem::isVisible()
\var QskQuickItem::UpdateFlag QskQuickItem::PreferRasterForTextures
When creating textures from QskGraphic, prefer the raster paint
engine over the OpenGL paint engine.
\var QskQuickItem::UpdateFlag QskQuickItem::DebugForceBackground
Always fill the background of the item with a random color.
\note This flag is useful when analyzing layouts.
*/
/*!
\property 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
*/
/*!
\property 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()
*/
/*!
\property 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
\saqt QQuickItem::ItemIsFocusScope
*/
/*!
\property 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()
\saqt QQuickItem::setVisible()
*/
/*!
\property QskQuickItem::polishOnResize
When polishOnResize is set QQuickItem::polish() will be called automatically
whenever 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
*/
/*!
\property 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()
*/
/*!
\property QskQuickItem::hasChildItems
A property indicating if the item has child items.
\saqt QQuickItem::childItems(), QQuickItem::parentItem()
*/
/*!
\property QskQuickItem::updateFlags
QskQuickItem offers several tweaks to the Qt/Quick update cycle,
that can be en/disabled individually.
The flags are a combination from bits that have been explicitly set
by setUpdateFlag() and those being derived from the aapplication
wide default settings, that can be set with QskSetup.
\sa QskQuickItem::UpdateFlag, QskQuickItem::updateFlags(), QskSetup::itemUpdateFlags()
*/
/*!
\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
when 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 setVisible( false ) has been called
\sa visibleToParent
\saqt 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()
\saqt QQuickItem::size(), QQuickItem::position()
*/
/*!
\fn QskQuickItem::setGeometry( const QPointF &, const QSizeF & )
Set the position and the size of an item
\param pos Position relative to the parent item
\param size Size of the item
*/
/*!
\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()
\saqt 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 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 QskControl::preferredSize(), QskControl::sizeHint()
\saqt QQuickItem::implicitWidth(), QQuickItem::implicitHeight()
*/
/*!
\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 laid 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::resetUpdateFlags
Reset all flags to the default settings
\sa QskSetup::itemUpdateFlags(), updateFlags(), updateFlags
*/
/*!
\fn QskQuickItem::updateFlags() const
\return Flags affecting the item update process
\sa testUpdateFlag(), setUpdateFlag(), updateFlags
*/
/*!
\fn QskQuickItem::setUpdateFlag
QskQuickItem offers several tweaks to the Qt/Quick update cycle,
that can be en/disables individually.
The default settings for these flags are taken from QskSetup::itemUpdateFlags()
When calling setUpdateFlag() the value for the particular flag is decoupled
from the corresponding default bit - even if both bits have the same value.
This can be reverted by calling resetUpdateFlag()
\param flag Flag affecting the item update process
\param on En/Disable the behaviour related to the flag
\sa QskSetup::itemUpdateFlags(), testUpdateFlag(). updateFlags
*/
/*!
\fn QskQuickItem::resetUpdateFlag
Reset the value for flag to the default settings from QskSetup. Future
changes of the corresponding bit with QskSetup::setItemUpdateFlag() will affect
the behaviour of this item.
\param flag Flag affecting the item update process
\sa QskSetup::itemUpdateFlags(), updateFlags(), testUpdateFlag(), updateFlags
*/
/*!
\fn QskQuickItem::testUpdateFlag
\param Flag affecting the item update process
\return true, when the corresponding bit is effective
\sa setUpdateFlag(), QskSetup::itemUpdateFlag(), updateFlags
*/
/*!
\fn QskQuickItem::updateFlagsChanged
Signal indicating, that the effective update flags have changed
\param flags Effective flags, might be derived in parts from QskSetup::itemUpdateFlags()
\sa updateFlags
*/
/*!
\fn QskQuickItem::classBegin
The QML engine initializes an item as being incomplete by
explicitly calling 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()
\saqt QQuickItem::classBegin, QQuickItem::isComponentComplete()
*/
/*!
\fn QskQuickItem::componentComplete
The QML engine initilizes an item as being incomplete by
explicitly 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()
\saqt QQuickItem::isComponentComplete(), QQuickItem::componentComplete
*/
/*!
\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 isUpdateNodeScheduled()
\saqt QQuickItem::polish()
*/
/*!
\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 property
\sa initiallyPainted
*/
/*!
\fn QskQuickItem::maybeUnresized
Flag indicating a potential state, where the item is waiting to be
sized by the layout system.
Unfortunately the list of items to-be-polished is not processed
in top/down order and a container might be requested to calculate
the geometries for its children before having a proper size itself.
Some of these situations can be avoided by ignoring these requests
depending on the maybeUnresized flag.
*/
/*!
\fn QskQuickItem::itemFlagsChanged
Signal indicating that at least one if the following attributes has changed:
- transparentForPositioners
- tabFence
- polishOnResize
*/
/*!
\fn QskQuickItem::show
An alternative way to call setVisible( true ).
Useful for signal/slot connections
\sa hide()
\saqt QQuickItem::setVisible()
*/
/*!
\fn QskQuickItem::hide
An alternative way to call setVisible( false ).
Useful for signal/slot connections
\sa show()
\saqt QQuickItem::setVisible()
*/
/*!
\fn QskQuickItem::setHidden
Convenience function, equivalent to setVisible( !on ).
\saqt QQuickItem::setVisible()
*/
/*!
\fn QskQuickItem::setDisabled
Convenience function, equivalent to setEnabled( !on ).
\saqt QQuickItem::setEnabled()
*/
/*!
\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
QskQuickItem handles the additional type of events.
For some reason the QQuick classes introduced proprietory notfier hooks
instead of using the well established and powerful concept of events.
QskQuickItem tries to revert this decision by mapping notifications
to events, when possible.
The following notification events are added by QSkinny - usually with a
very similar to how they are used known for Qt/Widgets:
- QEvent::ContentsRectChange
- QEvent::LocaleChange
- QEvent::ParentChange
- QEvent::EnabledChange
- QEvent::ReadOnlyChange
- QEvent::LayoutDirectionChange
- QEvent::LayoutRequest
Furthermore events derived from QskEvent are used.
\param event Qt event
*/
/*!
\fn QskQuickItem::changeEvent
This event handler can be reimplemented to handle certain state changes:
- QEvent::StyleChange
- QEvent::ContentsRectChange
- QEvent::FontChange
- QEvent::PaletteChange
- QEvent::ReadOnlyChange
- QEvent::EnabledChange
- QEvent::LocaleChange
- QEvent::ParentChange
- QEvent::LayoutDirectionChange
\param event Qt event
\note QEvent::PaletteChange, QEvent::FontChange are handled, but both event types
do not fit to the themeing concept of QSkinny and are not posted. However
it is possible to post them if an application has a concept, where they
make sense.
*/
/*!
\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 geometryChange()
\saqt QObject::installEventFilter()
*/
/*!
\fn QskQuickItem::windowChangeEvent
This event handler can be reimplemented to handle situations, where
an item is added, removed or transferred between windows. It corresponds
to the QQuickItem::ItemSceneChange notification, but is more convenient:
- being an event it can be processed by event filtering
- the previous window is available
\param event Event with the old/new windows
*/
/*!
\fn QskQuickItem::itemChange
For no obvious reason Qt/Quick has introduced an additional callback
mechanism beside events and signals.
\param change Indicator, to identify what has changed
\param changeData Extra information relating to the change
\note It is recommended to avoid using this type of notifications where possible.
Netter rely on overloading the corresponding event handlers, what allows
application code to make use of convenient and well established concepts
like event filtering ( QObject::installEventFilter() ).
\note If you re-implement this method in a subclass, be sure to call
the overloaded method of the base class.
\sa event()
\saqt QQuickItem::itemChange()
*/
/*!
\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 visible.
The default implementation is a no operation.
\sa initiallyPainted
\saqt QQuickItem::setVisible()
*/
/*!
\fn QskQuickItem::mouseUngrabEvent
Notification, that is overloaded for debuging purposes, without
doing anything beside calling the base class.
\saqt QQuickItem::mouseUngrabEvent
*/
/*!
\fn QskQuickItem::touchUngrabEvent
Notification, that is overloaded for debuging purposes, without
doing anything beside calling the base class.
\saqt QQuickItem::touchUngrabEvent
*/