Property contentItem in Qml

Question

The following Qml code gives the following output (expected):

import QtQuick 2.7
import QtQuick.Controls 2.0
import QtQuick.Window 2.11

Window {
    height: 200
    width: 200
    visible: true

    Button {
        id: root
        text: "Text"
        anchors.centerIn: parent

        Item {
            anchors.fill: parent
            Text {
                text: "Item.Text"
                color: "red"
            }
        }
    }
}

The following code (using contentItem) produces a different output:

import QtQuick 2.7
import QtQuick.Controls 2.0
import QtQuick.Window 2.11

Window {
    height: 200
    width: 200
    visible: true

    Button {
        id: root
        text: "Text"
        anchors.centerIn: parent

        contentItem: Item {
            anchors.fill: parent
            Text {
                text: "Item.Text"
                color: "red"
            }
        }
    }
}

The Qt documentation is not very clear, at least for me. The question is what does the property contentItem do? When it should be used?

Answer 1

Short answer: The contentItem is meant for customizing the control and replaces the existing implementation of the visual foreground element by your text.

---

Long answer:

A Quick Item has a so called "default property" - the data property. By definition, if you add an item as child of another item, it is instead assigned to the default property. Which means the following example:

Item {
    Text { text: "test1"} 
}

Is actually identical to:

Item {
    data: [
        Text { text: "test2"}
    ]
}

If you know look at your example, in the first variant, you simply append a child item to the root button. Since no further information is given, it is placed at the coordinates (0,0) within it's parent.

The contentItem property however is defined in the documentation as follows:

This property holds the visual content item.

In case of a Button it is an internally used Label to display the text property of the button. It exists to modify the appereance of the button.

In your second example, you "customize" the button by replacing the internal label with your custom Text - but without any code to properly position or fill the item. The correct way to declare a content item can be found in the customization guide:

Button {
    id: control
    text: qsTr("Button")

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    // ...
}

You could either define it as part of a custom style, or create a MyButton.qml where do exactly this and can then use MyButton in other QML files, giving you a custom styled button whilest keeping the API intact (like beeing able to set the text via the text property etc.)

I hope this was sufficient enough to help you understand how it works.