Pfthb

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?

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.