QskQuickItem

More…

#include <QskQuickItem.h>

Inherits from QQuickItem

Inherited by QskControl

Public Types

Public Slots

Public Signals

Public Functions

Protected Functions

Public Properties

Detailed Description

class QskQuickItem;

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.

Public Types Documentation

enum UpdateFlag

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.

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

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.
``` |
| CleanupOnVisibility |  1 << 3|  

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()  |
| PreferRasterForTextures |  1 << 4|  

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

| DebugForceBackground |  1 << 7|  

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

**See**: [updateFlags()](/docs/classes/classQskQuickItem/#property-updateflags), [resetUpdateFlags()](/docs/classes/classQskQuickItem/#function-resetupdateflags)[testUpdateFlag()](/docs/classes/classQskQuickItem/#function-testupdateflag), [setUpdateFlag()](/docs/classes/classQskQuickItem/#function-setupdateflag), [resetUpdateFlag()](/docs/classes/classQskQuickItem/#function-resetupdateflag)

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


## Public Slots Documentation

### slot setGeometry

```cpp
inline void setGeometry(
    const QRectF & rect
)

Parameters:

• rect Geometry relative to the parent item

See: geometry(), geometryChange() \saqt QQuickItem::size(), QQuickItem::position()

Set the position and the size of an item

slot show

void show()

See: hide() \saqt QQuickItem::setVisible()

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

slot hide

void hide()

See: show() \saqt QQuickItem::setVisible()

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

slot setHidden

void setHidden(
    bool on
)

Convenience function, equivalent to setVisible( !on ).
\saqt QQuickItem::setVisible()

slot setDisabled

void setDisabled(
    bool on
)

Convenience function, equivalent to setEnabled( !on ). \saqt QQuickItem::setEnabled()

slot resetImplicitSize

void 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.

Public Signals Documentation

signal itemFlagsChanged

void itemFlagsChanged()

Signal indicating that at least one if the following attributes has changed:

• transparentForPositioners
• tabFence
• polishOnResize

signal updateFlagsChanged

void updateFlagsChanged(
    UpdateFlags 
)

Parameters:

• flags Effective flags, might be derived in parts from QskSetup::itemUpdateFlags()

See: updateFlags

Signal indicating, that the effective update flags have changed

Public Functions Documentation

function ~QskQuickItem

~QskQuickItem() override

function className

const char * className() const

Return: Class name

A convenience wrapper for metaObject()->className()

function isVisibleTo

bool isVisibleTo(
    const QQuickItem * ancestor
) const

Parameters:

• ancestor Ancestor is the parentItem() hierarchy

See: visibleToParent

Return: true if this item would become visible if ancestor is shown; otherwise returns false.

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

function isVisibleToParent

bool isVisibleToParent() const

See: visibleToParent \saqt QQuickItem::setVisible()

Return: true once setVisible( false ) has been called

An item might be invisible because it has been explicitly hidden or one of its ancestors has been hidden. isVisibleToParent() indicates the first situation.

function hasChildItems

inline bool hasChildItems() const

See: hasChildItems

Return: true, if the item has child items

function rect

QRectF rect() const

See: geometry

Return: Internal geometry of the item, where the position is always at ( 0, 0 )

function implicitSize

inline QSizeF implicitSize() const

See: QskControl::preferredSize(), QskControl::sizeHint() \saqt QQuickItem::implicitWidth(), QQuickItem::implicitHeight()

Return: Implicit size,

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

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.

function setGeometry

void setGeometry(
    qreal x,
    qreal y,
    qreal width,
    qreal height
)

Parameters:

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

See: geometry(), geometryChange() \saqt QQuickItem::size(), QQuickItem::position()

Set the position and the size of an item

function setGeometry

inline void setGeometry(
    const QPointF & pos,
    const QSizeF & size
)

function geometry

QRectF geometry() const

See: geometry, setGeometry()

Return: Position and size relative to the parent item

function setPosition

inline void setPosition(
    qreal x,
    qreal y
)

function setSize

inline void setSize(
    qreal width,
    qreal height
)

function setPolishOnResize

void setPolishOnResize(
    bool on
)

See: polishOnResize

Set or clear the polishOnResize flag.

function polishOnResize

bool polishOnResize() const

See: setPolishOnResize()

Return: Value of the polishOnResize flag

function setTransparentForPositioner

void setTransparentForPositioner(
    bool on
)

See: isTransparentForPositioner()

Set or clear the transparentForPositioner flag

function isTransparentForPositioner

bool isTransparentForPositioner() const

See: transparentForPositioner

Return: Value of the transparentForPositioner flag

function setTabFence

void setTabFence(
    bool on
)

See: isTabFence()

Set or clear the tabFence property

function isTabFence

bool isTabFence() const

See: setTransparentForPositioner()

Return: Value of the tabFence property

function setLayoutMirroring

void setLayoutMirroring(
    bool on,
    bool childrenInherit =false
)

Parameters:

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

See: layoutMirroring, resetLayoutMirroring(), changeEvent()

Note: In Qml the parameters are routed through the attached LayoutMirroring property to have something declarative

Change the direction how the content is laid out horizontally.

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

function resetLayoutMirroring

void resetLayoutMirroring()

See: setLayoutMirroring(), layoutMirroring

Clear the layoutMirroring property

function layoutMirroring

bool layoutMirroring() const

See:

• setLayoutMirroring(), layoutMirroring()
• setLayoutMirroring(), resetLayoutMirroring()

Return: Inherited or explicitly assigned value

Note:

• Several controls do not respect this flag
• In Qml the parameters are routed through the attached LayoutMirroring property to have something declarative

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.

function resetUpdateFlags

void resetUpdateFlags()

See: QskSetup::itemUpdateFlags(), updateFlags(), updateFlags

Reset all flags to the default settings

function updateFlags

UpdateFlags updateFlags() const

See: testUpdateFlag(), setUpdateFlag(), updateFlags

Return: Flags affecting the item update process

function setUpdateFlag

Q_INVOKABLE void setUpdateFlag(
    UpdateFlag flag,
    bool on =true
)

Parameters:

• flag Flag affecting the item update process
• on En/Disable the behaviour related to the flag

See: QskSetup::itemUpdateFlags(), testUpdateFlag(). updateFlags

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()

function resetUpdateFlag

Q_INVOKABLE void resetUpdateFlag(
    UpdateFlag flag
)

Parameters:

• flag Flag affecting the item update process

See: QskSetup::itemUpdateFlags(), updateFlags(), testUpdateFlag(), updateFlags

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.

function testUpdateFlag

Q_INVOKABLE bool testUpdateFlag(
    UpdateFlag flag
) const

Parameters:

• Flag affecting the item update process

See: setUpdateFlag(), QskSetup::itemUpdateFlag(), updateFlags

Return: true, when the corresponding bit is effective

function classBegin

void classBegin() override

See: componentComplete() \saqt QQuickItem::classBegin, QQuickItem::isComponentComplete()

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.

function componentComplete

void componentComplete() override

See: classBegin() \saqt QQuickItem::isComponentComplete(), QQuickItem::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.

function releaseResources

void releaseResources() override

See: windowChangeEvent()

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.

function isPolishScheduled

bool isPolishScheduled() const

See: isUpdateNodeScheduled() \saqt QQuickItem::polish()

Return: True, if the item will be polished in the next scene graph update cycle.

function isUpdateNodeScheduled

bool isUpdateNodeScheduled() const

Return: True, if the item will update the paint node in the next scene graph update cycle

function isInitiallyPainted

bool isInitiallyPainted() const

See: initiallyPainted

Return: Value of the initiallyPainted property

function maybeUnresized

bool maybeUnresized() const

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.

Protected Functions Documentation

function QskQuickItem

QskQuickItem(
    QskQuickItemPrivate & dd,
    QQuickItem * parent =nullptr
)

Sets the QQuickItem::ItemHasContents flag to true.

function event

bool event(
    QEvent * event
) override

Parameters:

• event Qt 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.

function changeEvent

virtual void changeEvent(
    QEvent * 
)

Parameters:

• 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.

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

function geometryChangeEvent

virtual void geometryChangeEvent(
    QskGeometryChangeEvent * 
)

Parameters:

• event Event indicating the geometry change

See: geometryChange() \saqt QObject::installEventFilter()

Reimplemented by: QskLinearBox::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.

function windowChangeEvent

virtual void windowChangeEvent(
    QskWindowChangeEvent * 
)

Parameters:

• event Event with the old/new windows

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

function mouseUngrabEvent

void mouseUngrabEvent() override

Notification, that is overloaded for debuging purposes, without doing anything beside calling the base class.

\saqt QQuickItem::mouseUngrabEvent

function touchUngrabEvent

void touchUngrabEvent() override

Notification, that is overloaded for debuging purposes, without doing anything beside calling the base class.

\saqt QQuickItem::touchUngrabEvent

function itemChange

void itemChange(
    ItemChange ,
    const ItemChangeData & 
) override

Parameters:

• change Indicator, to identify what has changed
• changeData Extra information relating to the change

See: event() \saqt QQuickItem::itemChange()

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() ).
• If you re-implement this method in a subclass, be sure to call the overloaded method of the base class.

For no obvious reason Qt/Quick has introduced an additional callback mechanism beside events and signals.

function geometryChange

void geometryChange(
    const QRectF & newGeometry,
    const QRectF & oldGeometry
) override

See: geometryChangeEvent(), polishOnResize()

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

function aboutToShow

virtual void aboutToShow()

See: initiallyPainted \saqt QQuickItem::setVisible()

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.

Public Property Documentation

property geometry

QRectF geometry;

See: geometryChangeEvent(), geometryChange(), rect

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

property rect

QRectF rect;

See: geometryChangeEvent(), geometryChange(), geometry

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

property transparentForPositioners

bool transparentForPositioners;

See: isTransparentForPositioner()

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.

property tabFence

bool tabFence;

See: isTabFence(), QQuickItem::ItemIsFocusScope \saqt QQuickItem::ItemIsFocusScope

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.

property polishOnResize

bool polishOnResize;

See: QskControl::updateLayout(), QskControl::autoLayoutChildren

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.

property visibleToParent

bool visibleToParent;

See: isVisibleToParent() \saqt QQuickItem::setVisible()

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.

property hasChildItems

bool hasChildItems;

A property indicating if the item has child items.

\saqt QQuickItem::childItems(), QQuickItem::parentItem()

property initiallyPainted

bool initiallyPainted;

See: isInitiallyPainted(), aboutToShow()

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.

property updateFlags

UpdateFlags updateFlags;

See: QskQuickItem::UpdateFlag, QskQuickItem::updateFlags(), QskSetup::itemUpdateFlags()

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.

Updated on 28 July 2023 at 14:02:28 CEST