The wiki is in the process of moving to Please make your edits there.

Qt_Quick_Tutorial_Components | Qt Wiki | Qt Project

Qt Quick Tutorial: Module 2 – Components

Creating a Custom Component

We still have some work left to do from Module 1. If we look at our final QML document BasicSteps_4.qml, we still see too much code duplication. The code for the three photo rectangles is nearly identical. It only differs in the x-position, the image file and the title. In C++, we would introduce a class Photo, instantiate it three times and initialize it with the different values of the x-position, image file and title. And, this is actually what we do in QML, too – except that a class is called a component in QML.

A component is always defined in a file that has the component’s name as its base name and that has the extension .qml. For example, our Photo component will be defined in the file Photo.qml. A component name always starts with an uppercase letter and is continued by zero or more letters (uppercase or lowercase), digits or underscores.

We perform the following steps to create the Photo component.

  • We copy the QML file BasicSteps_4.qml into the file Components.qml.
  • We create a new QML file Photo.qml in the same directory as Components.qml.
  • We copy the Rectangle for photo 1 into Photo.qml.

We are fairly close to the final Photo component. We only have to introduce properties for the variable parameters of the Photo component: the x-position, image file and image title. We will assign concrete values to these properties in the instantiations of the Photo component in Components.qml.

We don’t have to do anything for the x-position, because a Rectangle already has a property x. We simply remove the code fragment x: 0;. While we are at it, we also remove the code fragment y: 0, because the default value for the y-position is 0 anyway.

For the image file and title, we introduce two properties imageFile and imageTitle at the beginning of the Rectangle. Finally, we replace the value of source in Image by imageFile and the value of text in Text by imageTitle. With all these changes, the Photo component looks as follows.

  1. // File: Photo.qml
  2. import QtQuick 1.0
  4. Rectangle {
  5.     property url imageFile
  6.     property string imageTitle
  8.     width: frameSize; height: frameSize
  9.     color: frameColor
  11.     Image {
  12.         x: leftMargin; y: topMargin
  13.         source: imageFile
  14.     }
  16.     Text {
  17.         x: 0; y: frameSize - bottomMargin
  18.         text: imageTitle
  19.         font.pixelSize: fontSize
  20.         width: frameSize; horizontalAlignment: Text.AlignHCenter
  21.         height: bottomMargin; verticalAlignment: Text.AlignVCenter
  22.     }
  23. }

We can now use our brand new Photo component in the main QML document Components.qml (formerly BasicSteps_4.qml), which shows three photos side by side. The resulting code looks as follows.

  1. // File: Components.qml
  2. import QtQuick 1.0
  4. Rectangle {
  5.     property int frameSize: 300
  6.     property int leftMargin: 10
  7.     property int topMargin: 25
  8.     property int bottomMargin: 65
  9.     property int fontSize: 20
  10.     property color frameColor: "#FFF8DC"    // cornsilk
  12.     width: 3 * frameSize; height: frameSize
  14.     Photo {
  15.         x: 0
  16.         imageFile: "voringsfossen1.jpg"
  17.         imageTitle: "Voringsfossen"
  18.     }
  20.     Photo {
  21.         x: frameSize
  22.         imageFile: "bergen.jpg"
  23.         imageTitle: "Bergen"
  24.     }
  26.     Photo {
  27.         x: 2 * frameSize
  28.         imageFile: "cotton_grass.jpg"
  29.         imageTitle: "Cotton Grass"
  30.     }
  31. }

In the three instances of the Photo component, we only assign values to the three variable parameters: x-position, image file and image title. The values of the other properties like frameSize or leftMargin are propagated from the root Rectangle instance to the Photo instances and to their child instances Image and Text.

We can now admire our work by running QML viewer in the directory of Components.qml and Photo.qml:

  1. qmlviewer Components.qml &

How does QML viewer know where to find the Photo component? By default, QML viewer looks for a QML file with the same base name as the component and with the extension .qml in the directory, where it is started. In our case, it finds the file Photo.qml. We’ll show in the module Modules how to place components in other directories than the current one.

Property Aliases and Property id

We can still improve the code of the Photo component a little bit. The URL of the image file and the image title are stored in two places each. The image file is stored in the newly introduced property imageFile and in the property source of Image. Similarly, the image title is stored in imageTitle and in text of Text. This means that memory is allocated twice for the image file and twice for the image title. It is not a big problem in this example. If, however, the duplicated objects are bigger, it becomes a problem. The other problem is that the we must make sure that the two occurrences of image file and of image title are in sync with each other. Again, it is fairly simple for our little program but it becomes trickier for bigger programs.

Fortunately, property aliases come to our rescue. A property alias says that two properties share the same value and store it at one memory location. The C++ equivalent would be a reference to an existing variable. The syntax of a property alias is

  1.     property alias property1: property2

where property1 is the newly introduced alias and property2 is the already existing property to be aliased.

In our Photo component, we want to define imageFile as an alias for the property source of Image and imageTitle as an alias for the property text of Text. There is only one little problem: How can we uniquely address the properties source and text? If there were several Image or Text components in the Photo component (a fairly usual scenario, by the way), we would have no way distinguish them.

The special QML property id solves this problem. The property id is a unique name or identifier for a component instance. Using the notation instName.propName we can access the property propertyName of the instance, whose id property has the value instName.

Now, we can finally introduce the two property aliases and use them. In Photo.qml, we replace the two property definitions in lines 5 and 6 by

  1.     property alias imageFile: picture.source
  2.     property alias imageTitle: title.text

We assign the identifier photo to the Image component and remove the line for the source property. Then, Image looks as follows:

  1.     Image {
  2.         id: picture
  3.         x: leftMargin; y: topMargin
  4.     }

Similarly, we assign the identifier title to the Text component and remove the line for the text property. Then, Text looks as follows:

  1.     Text {
  2.         id: title
  3.         x: 0; y: frameSize - bottomMargin
  4.         font.pixelSize: fontSize
  5.         width: frameSize; horizontalAlignment: Text.AlignHCenter
  6.         height: bottomMargin; verticalAlignment: Text.AlignVCenter
  7.     }

The complete code for the modified Photo component can be found in Photo.qml.

It is important to note that the value of id is not enclosed in double quotes. It is not quoted at all because it is an identifier, not a string.

Go back to Module 1 – Basics []

Tutorial Main Page []