View source for Qt Quick Tutorial Components

{{Cleanup | reason=Auto-imported from ExpressionEngine.}}

[[Category:Developing_with_Qt::Qt Quick]]
[[Category:Developing_with_Qt::Qt Quick::Tutorial]]

= Qt Quick Tutorial: Module 2 - Components =

== Creating a Custom Component ==

We still have some work left to do from [[Qt_Quick_Tutorial_Basics | Module 1]]. If we look at our final QML document [[BasicSteps_4 | ''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 <code>Photo</code>, 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 <code>Photo</code> 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 <code>Photo</code> component.
* We copy the QML file [[BasicSteps_4 | 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 <code>Rectangle</code> for photo 1 into ''Photo.qml''.

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

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

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

<code>
// File: Photo.qml
import QtQuick 1.0

Rectangle {
 property url imageFile
 property string imageTitle

 width: frameSize; height: frameSize
 color: frameColor

 Image {
 x: leftMargin; y: topMargin
 source: imageFile
 }

 Text {
 x: 0; y: frameSize - bottomMargin
 text: imageTitle
 font.pixelSize: fontSize
 width: frameSize; horizontalAlignment: Text.AlignHCenter
 height: bottomMargin; verticalAlignment: Text.AlignVCenter
 }
}
</code>

We can now use our brand new <code>Photo</code> 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.

<code>
// File: Components.qml
import QtQuick 1.0

Rectangle {
 property int frameSize: 300
 property int leftMargin: 10
 property int topMargin: 25
 property int bottomMargin: 65
 property int fontSize: 20
 property color frameColor: "#FFF8DC" // cornsilk

 width: 3 * frameSize; height: frameSize

 Photo {
 x: 0
 imageFile: "voringsfossen1.jpg"
 imageTitle: "Voringsfossen"
 }

 Photo {
 x: frameSize
 imageFile: "bergen.jpg"
 imageTitle: "Bergen"
 }

 Photo {
 x: 2 * frameSize
 imageFile: "cotton_grass.jpg"
 imageTitle: "Cotton Grass"
 }
}
</code>

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

We can now admire our work by running QML viewer in the directory of ''Components.qml'' and ''Photo.qml'':
<code>qmlviewer Components.qml &<code>

How does QML viewer know where to find the <code>Photo</code> 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 [[Qt_Quick_Tutorial_Modules | 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 <code>Photo</code> 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 <code>imageFile</code> and in the property <code>source</code> of <code>Image</code>. Similarly, the image title is stored in <code>imageTitle</code> and in <code>text</code> of <code>Text</code>. 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
</code>
 property alias property1: property2
<code>
where <code>property1</code> is the newly introduced alias and <code>property2</code> is the already existing property to be aliased.

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

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

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
</code>
 property alias imageFile: picture.source
 property alias imageTitle: title.text
<code>

We assign the identifier <code>photo</code> to the <code>Image</code> component and remove the line for the <code>source</code> property. Then, <code>Image</code> looks as follows:
</code>
 Image {
 id: picture
 x: leftMargin; y: topMargin
 }
<code>

Similarly, we assign the identifier <code>title</code> to the <code>Text</code> component and remove the line for the <code>text</code> property. Then, <code>Text</code> looks as follows:
</code>
 Text {
 id: title
 x: 0; y: frameSize - bottomMargin
 font.pixelSize: fontSize
 width: frameSize; horizontalAlignment: Text.AlignHCenter
 height: bottomMargin; verticalAlignment: Text.AlignVCenter
 }
<code>

The complete code for the modified <code>Photo</code> component can be found in [[PhotoQml | ''Photo.qml'']].

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

Go back to [http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial_Basics Module 1 - Basics]

[http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial Tutorial Main Page]