QQuickItem Class

All visual QML items are rendered using the scene graph, the default implementation of which is a low-level, high-performance rendering stack, closely tied to accelerated graphics APIs, such as OpenGL, Vulkan, Metal, or Direct 3D. It is possible for subclasses of QQuickItem to add their own custom content into the scene graph by setting the QQuickItem::ItemHasContents flag and reimplementing the QQuickItem::updatePaintNode() function.

Graphics Resource Handling▲

The QQuickItem provides a subclass, QQuickPaintedItem, which allows the users to render content using QPainter.

If your Item uses the Behavior type to define animations for property changes, you should always use either QObject::setProperty(), QQmlProperty(), or QMetaProperty::write() when you need to modify those properties from C++. This ensures that the QML engine knows about the property change. Otherwise, the engine won't be able to carry out your requested animation. Note that these functions incur a slight performance penalty. For more details, see Accessing Members of a QML Object Type from C++.

See also QQuickWindow, QQuickPaintedItem

flags QQuickItem::Flags

This enum type is used to specify various item properties.

The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.

See Also▲

Used in conjunction with QQuickItem::itemChange() to notify the item about certain types of changes.

Controls the point about which simple transforms like scale apply.

See Also▲

implicitWidth : qreal

Defines the preferred width or height of the Item.

If width or height is not specified, an item's effective size will be determined by its implicitWidth or implicitHeight.

However, if an item is the child of a layout, the layout will determine the item's preferred size using its implicit size. In such a scenario, the explicit width or height will be ignored.

The default implicit size for most items is 0x0, however some items have an inherent implicit size which cannot be overridden, for example, Image and Text.

Setting the implicit size is useful for defining components that have a preferred size based on their content, for example:

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

This read-only property indicates whether the item has active focus.

If activeFocus is true, either this item is the one that currently receives keyboard input, or it is a FocusScope ancestor of the item that currently receives keyboard input.

Usually, activeFocus is gained by setting focus on an item and its enclosing FocusScope objects. In the following example, the input and focusScope objects will have active focus, while the root rectangle object will not.

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

Access functions:

• bool hasActiveFocus() const

Notifier signal:

• void activeFocusChanged(bool)

See Also▲

This property holds whether the item wants to be in the tab focus chain. By default, this is set to false.

Access functions:

• bool activeFocusOnTab() const

• void setActiveFocusOnTab(bool)

Notifier signal:

• void activeFocusOnTabChanged(bool)

Specifies whether the item is antialiased or not

Used by visual elements to decide if the item should use antialiasing or not. In some cases items with antialiasing require more memory and are potentially slower to render (see Antialiasing for more details).

The default is false, but may be overridden by derived elements.

Access functions:

• bool antialiasing() const

• void setAntialiasing(bool)

• void resetAntialiasing()

Notifier signal:

• void antialiasingChanged(bool)

Specifies the position of the item's baseline in local coordinates.

The baseline of a Text item is the imaginary line on which the text sits. Controls containing text usually set their baseline to the baseline of their text.

For non-text items, a default baseline offset of 0 is used.

Access functions:

• baselineOffset() const

• void setBaselineOffset(qreal)

Notifier signal:

• void baselineOffsetChanged(qreal)

This property holds the collective position and size of the item's children.

This property is useful if you need to access the collective geometry of an item's children in order to correctly size the item.

The geometry that is returned is local to the item. For example:

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

Access functions:

• childrenRect()

Notifier signal:

• void childrenRectChanged(const QRectF &)

This property holds whether clipping is enabled. The default clip value is false.

If clipping is enabled, an item will clip its own painting, as well as the painting of its children, to its bounding rectangle. If you set clipping during an item's paint operation, remember to re-set it to prevent clipping the rest of your scene.

Access functions:

• bool clip() const

• void setClip(bool)

Notifier signal:

• void clipChanged(bool)

This property holds an optional mask to be used in the contains() method, which is mainly used for hit-testing each QPointerEvent.

By default, contains() will return true for any point within the Item's bounding box. But any QQuickItem, or any QObject that implements a function of the form

Q_INVOKABLE bool contains(const QPointF &point) const;

can be used as a mask, to defer hit-testing to that object.

This property was introduced in Qt 5.11.

Access functions:

• *containmentMask() const

• void setContainmentMask( *mask)

Notifier signal:

• void containmentMaskChanged()

See Also▲

This property holds whether the item receives mouse and keyboard events. By default this is true.

Setting this property directly affects the enabled value of child items. When set to false, the enabled values of all child items also become false. When set to true, the enabled values of child items are returned to true, unless they have explicitly been set to false.

Setting this property to false automatically causes activeFocus to be set to false, and this item will longer receive keyboard events.

Access functions:

• bool isEnabled() const

• void setEnabled(bool)

Notifier signal:

• void enabledChanged()

See Also▲

This property holds whether the item has focus within the enclosing FocusScope. If true, this item will gain active focus when the enclosing FocusScope gains active focus.

In the following example, input will be given active focus when scope gains active focus:

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

For the purposes of this property, the scene as a whole is assumed to act like a focus scope. On a practical level, that means the following QML will give active focus to input on startup.

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

Access functions:

• bool hasFocus() const

• void setFocus(bool)

• void setFocus(bool focus, reason)

Notifier signal:

• void focusChanged(bool)

See Also▲

This property supports QProperty bindings.

This property holds the height of this item.

This property holds the opacity of the item. Opacity is specified as a number between 0.0 (fully transparent) and 1.0 (fully opaque). The default value is 1.0.

When this property is set, the specified opacity is also applied individually to child items. This may have an unintended effect in some circumstances. For example in the second set of rectangles below, the red rectangle has specified an opacity of 0.5, which affects the opacity of its blue child rectangle even though the child has not specified an opacity.

Values outside the range of 0 to 1 will be clamped.

	Sélectionnez Item { Rectangle { color: "red" width: 100; height: 100 Rectangle { color: "blue" x: 50; y: 50; width: 100; height: 100 } } }
	Sélectionnez Item { Rectangle { opacity: 0.5 color: "red" width: 100; height: 100 Rectangle { color: "blue" x: 50; y: 50; width: 100; height: 100 } } }

Changing an item's opacity does not affect whether the item receives user input events. (In contrast, setting visible property to false stops mouse events, and setting the enabled property to false stops mouse and keyboard events, and also removes active focus from the item.)

Access functions:

• opacity() const

• void setOpacity(qreal)

Notifier signal:

• void opacityChanged()

See Also▲

This property holds the visual parent of the item.

Access functions:

• *parentItem() const

• void setParentItem( *parent)

Notifier signal:

• void parentChanged(QQuickItem *)

This property holds the rotation of the item in degrees clockwise around its transformOrigin.

The default value is 0 degrees (that is, no rotation).

Sélectionnez Rectangle { color: "blue" width: 100; height: 100 Rectangle { color: "red" x: 25; y: 25; width: 50; height: 50 rotation: 30 } }

Access functions:

• rotation() const

• void setRotation(qreal)

Notifier signal:

• void rotationChanged()

See Also▲

This property holds the scale factor for this item.

A scale of less than 1.0 causes the item to be rendered at a smaller size, and a scale greater than 1.0 renders the item at a larger size. A negative scale causes the item to be mirrored when rendered.

The default value is 1.0.

Scaling is applied from the transformOrigin.

Sélectionnez import QtQuick 2.0 Rectangle { color: "blue" width: 100; height: 100 Rectangle { color: "green" width: 25; height: 25 } Rectangle { color: "red" x: 25; y: 25; width: 50; height: 50 scale: 1.4 } }

Access functions:

• scale() const

• void setScale(qreal)

Notifier signal:

• void scaleChanged()

See Also▲

Specifies whether the item is smoothed or not

Primarily used in image based items to decide if the item should use smooth sampling or not. Smooth sampling is performed using linear interpolation, while non-smooth is performed using nearest neighbor.

In Qt Quick 2.0, this property has minimal impact on performance.

By default, this property is set to true.

Access functions:

• bool smooth() const

• void setSmooth(bool)

Notifier signal:

• void smoothChanged(bool)

This property holds the name of the current state of the item.

If the item is in its default state, that is, no explicit state has been set, then this property holds an empty string. Likewise, you can return an item to its default state by setting this property to an empty string.

Access functions:

• state() const

• void setState(const QString &)

Notifier signal:

• void stateChanged(const QString &)

See Also▲

This property holds the origin point around which scale and rotation transform.

Nine transform origins are available, as shown in the image below. The default transform origin is Item.Center.

Access functions:

• transformOrigin() const

• void setTransformOrigin(QQuickItem::TransformOrigin)

Notifier signal:

• void transformOriginChanged(QQuickItem::TransformOrigin)

This property holds whether the item is visible. By default this is true.

Setting this property directly affects the visible value of child items. When set to false, the visible values of all child items also become false. When set to true, the visible values of child items are returned to true, unless they have explicitly been set to false.

(Because of this flow-on behavior, using the visible property may not have the intended effect if a property binding should only respond to explicit property changes. In such cases it may be better to use the opacity property instead.)

If this property is set to false, the item will no longer receive mouse events, but will continue to receive key events and will retain the keyboard focus if it has been set. (In contrast, setting the enabled property to false stops both mouse and keyboard events, and also removes focus from the item.)

Access functions:

• bool isVisible() const

• void setVisible(bool)

Notifier signal:

• void visibleChanged()

See Also▲

This property supports QProperty bindings.

This property holds the width of this item.

This property supports QProperty bindings.

Defines the item's x position relative to its parent.

This property supports QProperty bindings.

Defines the item's y position relative to its parent.

Sets the stacking order of sibling items. By default the stacking order is 0.

Items with a higher stacking value are drawn on top of siblings with a lower stacking order. Items with the same stacking value are drawn bottom up in the order they appear. Items with a negative stacking value are drawn under their parent's content.

The following example shows the various effects of stacking order.

	Same z - later children above earlier children:   Sélectionnez Item { Rectangle { color: "red" width: 100; height: 100 } Rectangle { color: "blue" x: 50; y: 50; width: 100; height: 100 } }
	Higher z on top:   Sélectionnez Item { Rectangle { z: 1 color: "red" width: 100; height: 100 } Rectangle { color: "blue" x: 50; y: 50; width: 100; height: 100 } }
	Same z - children above parents:   Sélectionnez Item { Rectangle { color: "red" width: 100; height: 100 Rectangle { color: "blue" x: 50; y: 50; width: 100; height: 100 } } }
	Lower z below:   Sélectionnez Item { Rectangle { color: "red" width: 100; height: 100 Rectangle { z: -1 color: "blue" x: 50; y: 50; width: 100; height: 100 } } }

Access functions:

• z() const

• void setZ(qreal)

Notifier signal:

• void zChanged()

Constructs a QQuickItem with the given parent.

The parent will be used as both the visual parent and the QObject parent.

Destroys the QQuickItem.

Returns whether hover events are accepted by this item.

The default value is false.

If this is false, then the item will not receive any hover events through the hoverEnterEvent(), hoverMoveEvent() and hoverLeaveEvent() functions.

See Also▲

Returns whether touch events are accepted by this item.

The default value is false.

If this is false, then the item will not receive any touch events through the touchEvent() function.

This function was introduced in Qt 5.10.

See Also▲

Returns the mouse buttons accepted by this item.

The default value is Qt::NoButton; that is, no mouse buttons are accepted.

If an item does not accept the mouse button for a particular mouse event, the mouse event will not be delivered to the item and will be delivered to the next item in the item hierarchy instead.

See Also▲

Returns the extents of the item in its own coordinate system: a rectangle from 0, 0 to width() and height().

Returns the first visible child item found at point (x, y) within the coordinate system of this item.

Returns nullptr if there is no such item.

Returns the children of this item.

Reimplement this method to filter the pointer events that are received by this item's children.

This method will only be called if filtersChildMouseEvents() is true.

Return true if the specified event should not be passed on to the specified child item, and false otherwise.

See Also▲

Reimplements: QQmlParserStatus::classBegin().

Derived classes should call the base class method before adding their own action to perform at classBegin.

Returns the rectangular area within this item that is currently visible in viewportItem(), if there is a viewport and the ItemObservesViewport flag is set; otherwise, the extents of this item in its own coordinate system: a rectangle from 0, 0 to width() and height(). This is the region intended to remain visible if clip is true. It can also be used in updatePaintNode() to limit the graphics added to the scene graph.

For example, a large drawing or a large text document might be shown in a Flickable that occupies only part of the application's Window: in that case, Flickable is the viewport item, and a custom content-rendering item may choose to omit scene graph nodes that fall outside the area that is currently visible. If the ItemObservesViewport flag is set, this area will change each time the user scrolls the content in the Flickable.

In case of nested viewport items, clipRect() is the intersection of the boundingRects of all ancestors that have the ItemIsViewport flag set, mapped to the coordinate system of this item.

See Also▲

Reimplements: QQmlParserStatus::componentComplete().

Derived classes should call the base class method before adding their own actions to perform at componentComplete.

Returns true if this item contains point, which is in local coordinates; returns false otherwise.

This function can be overridden in order to handle point collisions in items with custom shapes. The default implementation checks whether the point is inside containmentMask() if it is set, or inside the bounding box otherwise.

Returns the cursor shape for this item.

The mouse cursor will assume this shape when it is over this item, unless an override cursor is set. See the list of predefined cursor objects for a range of useful shapes.

If no cursor shape has been set this returns a cursor with the Qt::ArrowCursor shape, however another cursor shape may be displayed if an overlapping item has a valid cursor.

See Also▲

This event handler can be reimplemented in a subclass to receive drag-enter events for an item. The event information is provided by the event parameter.

Drag and drop events are only provided if the ItemAcceptsDrops flag has been set for this item.

The event is accepted by default, so it is not necessary to explicitly accept the event if you reimplement this function. If you don't accept the event, call event->ignore().

See Also▲

This event handler can be reimplemented in a subclass to receive drag-leave events for an item. The event information is provided by the event parameter.

Drag and drop events are only provided if the ItemAcceptsDrops flag has been set for this item.

The event is accepted by default, so it is not necessary to explicitly accept the event if you reimplement this function. If you don't accept the event, call event->ignore().

See Also▲

This event handler can be reimplemented in a subclass to receive drag-move events for an item. The event information is provided by the event parameter.

Drag and drop events are only provided if the ItemAcceptsDrops flag has been set for this item.

The event is accepted by default, so it is not necessary to explicitly accept the event if you reimplement this function. If you don't accept the event, call event->ignore().

See Also▲

This event handler can be reimplemented in a subclass to receive drop events for an item. The event information is provided by the event parameter.

Drag and drop events are only provided if the ItemAcceptsDrops flag has been set for this item.

The event is accepted by default, so it is not necessary to explicitly accept the event if you reimplement this function. If you don't accept the event, call event->ignore().

See Also▲

Dumps some details about the visual tree of Items starting with this item, recursively.

This function was introduced in Qt 6.3.

See Also▲