Qt Quick Tutorial Components: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
[[Category:Developing_with_Qt::Qt Quick]]<br />[[Category:Developing_with_Qt::Qt Quick::Tutorial]]<br />[toc align_right="yes&quot; depth="3&quot;] | |||
= | = Qt Quick Tutorial: Module 2 - Components = | ||
== Creating a Custom Component == | |||
A '''component''' is always defined in a file that has the | 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&gt;Photo&lt;/code&gt;, 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. | ||
<br />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&gt;Photo&lt;/code&gt; 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. | |||
<br />We perform the following steps to create the <code&gt;Photo&lt;/code&gt; component.<br />* We copy the QML file [[BasicSteps_4 | BasicSteps_4.qml]] into the file ''Components.qml''.<br />* We create a new QML file ''Photo.qml'' in the same directory as ''Components.qml''.<br />* We copy the <code&gt;Rectangle&lt;/code&gt; for photo 1 into ''Photo.qml''. | |||
<br />We are fairly close to the final <code&gt;Photo&lt;/code&gt; component. We only have to introduce properties for the variable parameters of the <code&gt;Photo&lt;/code&gt; component: the x-position, image file and image title. We will assign concrete values to these properties in the instantiations of the <code&gt;Photo&lt;/code&gt; component in ''Components.qml''. | |||
<br />We don't have to do anything for the x-position, because a <code&gt;Rectangle&lt;/code&gt; already has a property <code&gt;x&lt;/code&gt;. We simply remove the code fragment <code&gt;x: 0;</code&gt;. While we are at it, we also remove the code fragment <code&gt;y: 0&lt;/code&gt;, because the default value for the y-position is 0 anyway. | |||
<br />For the image file and title, we introduce two properties <code&gt;imageFile&lt;/code&gt; and <code&gt;imageTitle&lt;/code&gt; at the beginning of the <code&gt;Rectangle&lt;/code&gt;. Finally, we replace the value of <code&gt;source&lt;/code&gt; in <code&gt;Image&lt;/code&gt; by <code&gt;imageFile&lt;/code&gt; and the value of <code&gt;text&lt;/code&gt; in <code&gt;Text&lt;/code&gt; by <code&gt;imageTitle&lt;/code&gt;. With all these changes, the <code&gt;Photo&lt;/code&gt; component looks as follows. | |||
<br /><code><br />// File: Photo.qml<br />import QtQuick 1.0 | |||
<br />Rectangle {<br /> property url imageFile<br /> property string imageTitle | |||
<br /> width: frameSize; height: frameSize<br /> color: frameColor | |||
<br /> Image {<br /> x: leftMargin; y: topMargin<br /> source: imageFile<br /> } | |||
<br /> Text {<br /> x: 0; y: frameSize - bottomMargin<br /> text: imageTitle<br /> font.pixelSize: fontSize<br /> width: frameSize; horizontalAlignment: Text.AlignHCenter<br /> height: bottomMargin; verticalAlignment: Text.AlignVCenter<br /> }<br />}<br /></code> | |||
<br />We can now use our brand new <code&gt;Photo&lt;/code&gt; 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. | |||
<br /><code><br />// File: Components.qml<br />import QtQuick 1.0 | |||
<br />Rectangle {<br /> property int frameSize: 300<br /> property int leftMargin: 10<br /> property int topMargin: 25<br /> property int bottomMargin: 65<br /> property int fontSize: 20<br /> property color frameColor: "#FFF8DC&quot; // cornsilk | |||
<br /> width: 3 * frameSize; height: frameSize | |||
<br /> Photo {<br /> x: 0<br /> imageFile: "voringsfossen1.jpg&quot;<br /> imageTitle: "Voringsfossen&quot;<br /> } | |||
<br /> Photo {<br /> x: frameSize<br /> imageFile: "bergen.jpg&quot;<br /> imageTitle: "Bergen&quot;<br /> } | |||
<br /> Photo {<br /> x: 2 * frameSize<br /> imageFile: "cotton_grass.jpg&quot;<br /> imageTitle: "Cotton Grass&quot;<br /> }<br />}<br /></code> | |||
<br />In the three instances of the <code&gt;Photo&lt;/code&gt; 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&gt;frameSize&lt;/code&gt; or <code&gt;leftMargin&lt;/code&gt; are propagated from the root <code&gt;Rectangle&lt;/code&gt; instance to the <code&gt;Photo&lt;/code&gt; instances and to their child instances <code&gt;Image&lt;/code&gt; and <code&gt;Text&lt;/code&gt;. | |||
<br />We can now admire our work by running QML viewer in the directory of ''Components.qml'' and ''Photo.qml'':<br /><code>qmlviewer Components.qml &#38;<code> | |||
<br />How does QML viewer know where to find the <code&gt;Photo&lt;/code&gt; 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. | |||
<br />h2. Property Aliases and Property id | |||
<br />We can still improve the code of the <code&gt;Photo&lt;/code&gt; 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&gt;imageFile&lt;/code&gt; and in the property <code&gt;source&lt;/code&gt; of <code&gt;Image&lt;/code&gt;. Similarly, the image title is stored in <code&gt;imageTitle&lt;/code&gt; and in <code&gt;text&lt;/code&gt; of <code&gt;Text&lt;/code&gt;. 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. | |||
<br />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<br /></code><br /> property alias property1: property2<br /><code><br />where <code&gt;property1&lt;/code&gt; is the newly introduced alias and <code&gt;property2&lt;/code&gt; is the already existing property to be aliased. | |||
In our <code&gt;Photo&lt;/code&gt; component, we want to define <code&gt;imageFile&lt;/code&gt; as an alias for the property <code&gt;source&lt;/code&gt; of <code&gt;Image&lt;/code&gt; and <code&gt;imageTitle&lt;/code&gt; as an alias for the property <code&gt;text&lt;/code&gt; of <code&gt;Text&lt;/code&gt;. There is only one little problem: How can we uniquely address the properties <code&gt;source&lt;/code&gt; and <code&gt;text&lt;/code&gt;? If there were several <code&gt;Image&lt;/code&gt; or <code&gt;Text&lt;/code&gt; components in the <code&gt;Photo&lt;/code&gt; component (a fairly usual scenario, by the way), we would have no way distinguish them. | |||
The special QML '''property <code&gt;id&lt;/code&gt;''' solves this problem. The property <code&gt;id&lt;/code&gt; is a unique name or identifier for a component instance. Using the notation <code&gt;instName.propName&lt;/code&gt; we can access the property <code&gt;propertyName&lt;/code&gt; of the instance, whose <code&gt;id&lt;/code&gt; property has the value <code&gt;instName&lt;/code&gt;. | |||
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<br /></code><br /> property alias imageFile: picture.source<br /> property alias imageTitle: title.text<br /><code> | |||
We | We assign the identifier <code&gt;photo&lt;/code&gt; to the <code&gt;Image&lt;/code&gt; component and remove the line for the <code&gt;source&lt;/code&gt; property. Then, <code&gt;Image&lt;/code&gt; looks as follows:<br /></code><br /> Image {<br /> id: picture<br /> x: leftMargin; y: topMargin<br /> }<br /><code> | ||
Similarly, we assign the identifier <code&gt;title&lt;/code&gt; to the <code&gt;Text&lt;/code&gt; component and remove the line for the <code&gt;text&lt;/code&gt; property. Then, <code&gt;Text&lt;/code&gt; looks as follows:<br /></code><br /> Text {<br /> id: title<br /> x: 0; y: frameSize - bottomMargin<br /> font.pixelSize: fontSize<br /> width: frameSize; horizontalAlignment: Text.AlignHCenter<br /> height: bottomMargin; verticalAlignment: Text.AlignVCenter<br /> }<br /><code> | |||
The complete code for the modified <code&gt;Photo&lt;/code&gt; component can be found in [[PhotoQml | ''Photo.qml'']]. | |||
It is important to note that the value of <code&gt;id&lt;/code&gt; 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&quot;:http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial_Basics | |||
"Tutorial Main Page&quot;:http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial | |||
Revision as of 08:56, 24 February 2015
[toc align_right="yes" depth="3"]
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 <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.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.
<br />// File: Photo.qml<br />import QtQuick 1.0
<br />Rectangle {<br /> property url imageFile<br /> property string imageTitle
<br /> width: frameSize; height: frameSize<br /> color: frameColor
<br /> Image {<br /> x: leftMargin; y: topMargin<br /> source: imageFile<br /> }
<br /> Text {<br /> x: 0; y: frameSize - bottomMargin<br /> text: imageTitle<br /> font.pixelSize: fontSize<br /> width: frameSize; horizontalAlignment: Text.AlignHCenter<br /> height: bottomMargin; verticalAlignment: Text.AlignVCenter<br /> }<br />}<br />
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.
<br />// File: Components.qml<br />import QtQuick 1.0
<br />Rectangle {<br /> property int frameSize: 300<br /> property int leftMargin: 10<br /> property int topMargin: 25<br /> property int bottomMargin: 65<br /> property int fontSize: 20<br /> property color frameColor: "#FFF8DC&quot; // cornsilk
<br /> width: 3 * frameSize; height: frameSize
<br /> Photo {<br /> x: 0<br /> imageFile: "voringsfossen1.jpg&quot;<br /> imageTitle: "Voringsfossen&quot;<br /> }
<br /> Photo {<br /> x: frameSize<br /> imageFile: "bergen.jpg&quot;<br /> imageTitle: "Bergen&quot;<br /> }
<br /> Photo {<br /> x: 2 * frameSize<br /> imageFile: "cotton_grass.jpg&quot;<br /> imageTitle: "Cotton Grass&quot;<br /> }<br />}<br />
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:
qmlviewer Components.qml &#38;<code>
<br />How does QML viewer know where to find the <code&gt;Photo&lt;/code&gt; 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.
<br />h2. Property Aliases and Property id
<br />We can still improve the code of the <code&gt;Photo&lt;/code&gt; 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&gt;imageFile&lt;/code&gt; and in the property <code&gt;source&lt;/code&gt; of <code&gt;Image&lt;/code&gt;. Similarly, the image title is stored in <code&gt;imageTitle&lt;/code&gt; and in <code&gt;text&lt;/code&gt; of <code&gt;Text&lt;/code&gt;. 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.
<br />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<br />
property alias property1: property2
<br />where <code&gt;property1&lt;/code&gt; is the newly introduced alias and <code&gt;property2&lt;/code&gt; is the already existing property to be aliased.
In our <code&gt;Photo&lt;/code&gt; component, we want to define <code&gt;imageFile&lt;/code&gt; as an alias for the property <code&gt;source&lt;/code&gt; of <code&gt;Image&lt;/code&gt; and <code&gt;imageTitle&lt;/code&gt; as an alias for the property <code&gt;text&lt;/code&gt; of <code&gt;Text&lt;/code&gt;. There is only one little problem: How can we uniquely address the properties <code&gt;source&lt;/code&gt; and <code&gt;text&lt;/code&gt;? If there were several <code&gt;Image&lt;/code&gt; or <code&gt;Text&lt;/code&gt; components in the <code&gt;Photo&lt;/code&gt; component (a fairly usual scenario, by the way), we would have no way distinguish them.
The special QML '''property <code&gt;id&lt;/code&gt;''' solves this problem. The property <code&gt;id&lt;/code&gt; is a unique name or identifier for a component instance. Using the notation <code&gt;instName.propName&lt;/code&gt; we can access the property <code&gt;propertyName&lt;/code&gt; of the instance, whose <code&gt;id&lt;/code&gt; property has the value <code&gt;instName&lt;/code&gt;.
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<br />
property alias imageFile: picture.source
property alias imageTitle: title.text
We assign the identifier <code&gt;photo&lt;/code&gt; to the <code&gt;Image&lt;/code&gt; component and remove the line for the <code&gt;source&lt;/code&gt; property. Then, <code&gt;Image&lt;/code&gt; looks as follows:<br />
Image {
id: picture
x: leftMargin; y: topMargin
}
Similarly, we assign the identifier <code&gt;title&lt;/code&gt; to the <code&gt;Text&lt;/code&gt; component and remove the line for the <code&gt;text&lt;/code&gt; property. Then, <code&gt;Text&lt;/code&gt; looks as follows:<br />
Text {
id: title
x: 0; y: frameSize - bottomMargin
font.pixelSize: fontSize
width: frameSize; horizontalAlignment: Text.AlignHCenter
height: bottomMargin; verticalAlignment: Text.AlignVCenter
}
The complete code for the modified <code>Photo</code> component can be found in 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 "Module 1 - Basics":http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial_Basics
"Tutorial Main Page":http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial