Qt Quick Tutorial Components

From Qt Wiki
Revision as of 16:54, 14 January 2015 by Maintenance script (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

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

We assign the identifier
photo
to the
Image
component and remove the line for the
source
property. Then,
Image
looks as follows:
Similarly, we assign the identifier
title
to the
Text
component and remove the line for the
text
property. Then,
Text
looks as follows:
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 [developer.qt.nokia.com]

Tutorial Main Page [developer.qt.nokia.com]

Categories: