QQuickItem Class

Property Documentation

Defines the natural width or height of the Item if no width or height is specified.

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
     }
 }

activeFocus : const bool

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:

Notifier signal:

See also focus and Keyboard Focus in Qt Quick.

activeFocusOnTab : bool

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

Access functions:

Notifier signal:

antialiasing : 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:

Notifier signal:

baselineOffset : qreal

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:

Notifier signal:

childrenRect : const QRectF

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:

Notifier signal:

clip : bool

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:

Notifier signal:

containmentMask : QObject*

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:

Notifier signal:

See also contains().

enabled : bool

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:

Notifier signal:

See also visible.

focus : bool

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:

Notifier signal:

See also activeFocus and Keyboard Focus in Qt Quick.

height : qreal

This property holds the height of this item.

Access functions:

Notifier signal:

opacity : qreal

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.

 Item {
     Rectangle {
         color: "red"
         width: 100; height: 100
         Rectangle {
             color: "blue"
             x: 50; y: 50; width: 100; height: 100
         }
     }
 }

 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:

Notifier signal:

See also visible.

parent : QQuickItem*

This property holds the visual parent of the item.

Access functions:

Notifier signal:

rotation : qreal

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

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

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

Access functions:

Notifier signal:

See also Transform and Rotation.

scale : qreal

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.

 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:

Notifier signal:

See also Transform and Scale.

smooth : bool

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:

Notifier signal:

state : QString

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:

Notifier signal:

See also Qt Quick States.

transformOrigin : TransformOrigin

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:

Notifier signal:

visible : bool

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:

Notifier signal:

See also opacity and enabled.

width : qreal

This property holds the width of this item.

Access functions:

Notifier signal:

x : qreal

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

Access functions:

Notifier signal:

y : qreal

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

Access functions:

Notifier signal:

z : qreal

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.

 Item {
     Rectangle {
         color: "red"
         width: 100; height: 100
     }
     Rectangle {
         color: "blue"
         x: 50; y: 50; width: 100; height: 100
     }
 }

 Item {
     Rectangle {
         z: 1
         color: "red"
         width: 100; height: 100
     }
     Rectangle {
         color: "blue"
         x: 50; y: 50; width: 100; height: 100
     }
 }

 Item {
     Rectangle {
         color: "red"
         width: 100; height: 100
         Rectangle {
             color: "blue"
             x: 50; y: 50; width: 100; height: 100
         }
     }
 }

 Item {
     Rectangle {
         color: "red"
         width: 100; height: 100
         Rectangle {
             z: -1
             color: "blue"
             x: 50; y: 50; width: 100; height: 100
         }
     }
 }

Access functions:

Notifier signal: