Qt Quick Tutorial Basics 2: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Developing_with_Qt::Qt Quick]]<br />[[Category:Developing_with_Qt::Qt Quick::Tutorial]]<br />[toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;]
#REDIRECT [[Qt Quick Tutorial Basics]]
 
= Qt Quick Tutorial: Module 1 - Basics =
 
== Components and Properties ==
 
No, we don't start with a QML program printing &quot;Hello world!&quot;. We start with something much more exciting: a QML program that draws a blue rectangle of 300x300 pixels.
 
<code><br />// File: BasicSteps_1.qml
 
import QtQuick 1.0
 
Rectangle {<br /> width: 300<br /> height: 300<br /> color: &quot;blue&amp;quot;<br />}<br /></code>
 
We run QML viewer to see the result of our work:
 
<code>&gt; qmlviewer BasicSteps_1.qml &amp;amp;<code>
 
Yes, the above QML code, indeed, produces a blue rectangle. A self-contained piece of QML code as the one above is called a '''QML document''' (see also &quot;QML Documents&amp;quot;:http://doc.qt.nokia.com/4.7-snapshot/qdeclarativedocuments.html). A QML document is a piece of QML code that contains at least one &lt;code&amp;gt;import&amp;lt;/code&amp;gt; statement and exactly one top-level component. In our example, &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; is the single top-level component. Generally, a QML document corresponds to a file, but it could also be text stored in a string or a URL pointing to QML document stored on a remote server.
 
The statement &lt;code&amp;gt;import Qt 4.7&amp;lt;/code&amp;gt; makes all the QML components of Qt 4.7 available to our QML document. Qt 4.7 comes with built-in components like Rectangle, Text, ListView, WebView, Flipable, Animation and many more (see &quot;QML Elements&amp;quot;:http://doc.qt.nokia.com/4.7-snapshot/qdeclarativeelements.html for a complete list).
 
'''Components''' are the QML equivalents of C++ classes. They have properties, methods (member functions), signals and slots. The occurrence of &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; in lines 5-9 is an instance of a &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; component: a blue 300x300 pixel instance of a &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; component. In the Qt documentation, '''element''' is often used as a synonym for component. Components with a visual representation like a Rectangle or Text are called '''items'''. Component names always start with an uppercase letter followed by zero or more letters, digits and underscores.
 
A instance of a component is characterised by its '''properties''', which are name-value pairs. The &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; instance above has three properties &lt;code&amp;gt;width&amp;lt;/code&amp;gt;, &lt;code&amp;gt;height&amp;lt;/code&amp;gt; and &lt;code&amp;gt;color&amp;lt;/code&amp;gt; with the values &lt;code&amp;gt;300&amp;lt;/code&amp;gt;, &lt;code&amp;gt;300&amp;lt;/code&amp;gt; and &lt;code&amp;gt;blue&amp;lt;/code&amp;gt;, respectively. Property names always start with a lowercase letter followed by zero or more letters, digits and underscores. Properties are type-safe. Hence, the line
 
</code>width: &quot;Oslo&amp;quot;</code>
 
would be illegal, because the property &lt;code&amp;gt;width&amp;lt;/code&amp;gt; expects a number of type real. QML supports the following basic types: bool, color, date, font, int, list, point, real, rect, size, string, time, url.
 
Several properties can be written in one line separated by semicolon:
 
<code><br />width: 300; height: 300<br />color: &quot;blue&amp;quot;<br /></code>
 
The order of properties is irrelevant. We could rewrite the &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; as
 
<code><br />// File: BlueRectangle.qml<br />Rectangle {<br /> height: 300<br /> width: 300<br /> color: &quot;blue&amp;quot;<br />}<br /></code>
 
and the result would be the same.
 
'''Comments''' are marked in QML in the same way as in C++. Comments to the end of the line start with &lt;code&amp;gt;//&amp;lt;/code&amp;gt;. Line 1 of our example contains such a comment. Multi-line comments start with &lt;code&amp;gt;/*&lt;/code&amp;gt; and end with &lt;code&amp;gt;'''/&amp;lt;/code&amp;gt;.
<br />h2. Composition of Components
<br />The excitement about our blue rectangle is wearing off by now, isn't it? So, let us turn the blue rectangle into a photo frame with a photo in the center, a tag line below the photo and a oldlace colored background. We position a QML &lt;code&amp;gt;Image&amp;lt;/code&amp;gt; component for the photo and a &lt;code&amp;gt;Text&amp;lt;/code&amp;gt; component for the title on the &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; component and change the color to &quot;oldlace&amp;quot;. We can use the SVG color names directly in QML.
<br /><code><br />// File: PlacingElements.qml<br />import QtQuick 1.0
<br />Rectangle {<br /> width: 180<br /> height: 135<br /> color: &quot;oldlace&amp;quot;<br /> Image {<br /> x: 10; y: 10<br /> width: 160<br /> height: 100<br /> fillMode: Image.PreserveAspectCrop<br /> source: &quot;images/image01.jpg&amp;quot;<br /> }<br /> Text {<br /> x: 10; y: 115<br /> width: 100<br /> text: &quot;temple&amp;quot;<br /> }<br />}<br /></code>
<br />We have chosen a &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; element as the root of our element hierarchy. We place an &lt;code&amp;gt;Image&amp;lt;/code&amp;gt; and &lt;code&amp;gt;Text&amp;lt;/code&amp;gt; element inside. Children in a QML element tree are always placed relative to its parents. The &lt;code&amp;gt;x&amp;lt;/code&amp;gt; and &lt;code&amp;gt;y&amp;lt;/code&amp;gt; coordinate refers to the top-left … etc
<br />As the image is 280x210 pixels, this position centers the image horizontally and vertically within the rectangle. The &lt;code&amp;gt;source&amp;lt;/code&amp;gt; property tells the QML runtime where to look for the image, which is stored in the file &lt;code&amp;gt;&quot;voringsfossen1.jpg&amp;quot;&lt;/code&amp;gt;. The image file is located in the same directory as the QML file &lt;code&amp;gt;BasicSteps.qml&amp;lt;/code&amp;gt;. In general, the &lt;code&amp;gt;source&amp;lt;/code&amp;gt; property takes a URL. The image could be located anywhere in the Internet or our local file system.
<br />The &lt;code&amp;gt;Text&amp;lt;/code&amp;gt; is positioned at 10 pixels to the right and 265 pixels down from the top left corner of the rectangle. The displayed text is &quot;Voringsfossen&amp;quot;, which is the name of Norway's most famous and highest waterfall. Again, &lt;code&amp;gt;Text&amp;lt;/code&amp;gt; is a child of &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; .
<br />This simple example of a photo frame shows how to compose basic components into a more complex components. The components or strictly speaking the component instances are arranged in a tree. In our example, the &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; is the root of the tree and &lt;code&amp;gt;Image&amp;lt;/code&amp;gt; and &lt;code&amp;gt;Text&amp;lt;/code&amp;gt; are the root's children. The children could again have children of their own and so on. These instance trees mirror the instance trees of Qt's graphics items or widgets.
<br />The result won't win us a design prize, but it is a good first shot. Let us improve it step by step. As the title shouldn't look crammed into the frame below the photo, we move the photo 20 pixels up. We just change &lt;code&amp;gt;Image&amp;lt;/code&amp;gt;'s property &lt;code&amp;gt;y&amp;lt;/code&amp;gt; to &lt;code&amp;gt;25&amp;lt;/code&amp;gt;.
<br /><code><br /> Image {<br /> x: 10; y: 25<br /> source: &quot;voringsfossen1.jpg&amp;quot;<br /> }<br /></code>
<br />We want the title to be a bit bigger, say 20 pixels (line 4), and want it to be centered both horizontally (line 5) and vertically (line 6) in the area below the photo.
<br /><code><br /> Text {<br /> x: 0; y: 235<br /> text: &quot;Voringsfossen&amp;quot;<br /> font.pixelSize: 20<br /> width: 300; horizontalAlignment: Text.AlignHCenter<br /> height: 65; verticalAlignment: Text.AlignVCenter<br /> }<br /></code>
<br />It is important to note that the property &lt;code&amp;gt;horizontalAlignment&amp;lt;/code&amp;gt; only has an effect if a width is specified. Without a width, the QML runtime wouldn't know where to position the text (just try it out). The same is true for the property &lt;code&amp;gt;verticalAlignment&amp;lt;/code&amp;gt;. So, whenever we use &lt;code&amp;gt;horizontalAlignment&amp;lt;/code&amp;gt; and &lt;code&amp;gt;verticalAlignment&amp;lt;/code&amp;gt;, we must give &lt;code&amp;gt;width&amp;lt;/code&amp;gt; and &lt;code&amp;gt;height&amp;lt;/code&amp;gt;, respectively.
<br />h2. Custom Properties
<br />Before we create our own properties, we create a real need for them. Our next goal is to show three photos side by side. We achieve this by simply instantiating the photo from &lt;code&amp;gt;BasicSteps_2.qml&amp;lt;/code&amp;gt; three times and by enclosing these three rectangles by a big rectangle (see [[BasicSteps_3 | BasicSteps_3.qml]] for the complete source code).
<br /><code>
<br />// File: BasicSteps_3.qml<br />import QtQuick 1.0
<br />Rectangle {<br /> width: 3''' 300; height: 300
 
// Photo 1<br /> Rectangle {<br /> x: 0; y: 0<br /> …<br /> }
 
// Photo 2<br /> Rectangle {<br /> x: 300; y: 0<br /> …<br /> }
 
// Photo 3<br /> Rectangle {<br /> x: 2 * 300; y: 0<br /> …<br /> }<br />}<br /></code>
 
Photo 1, 2 and 3 are identical copies of the &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt; from &lt;code&amp;gt;BasicSteps_2.qml&amp;lt;/code&amp;gt; - except for the properties &lt;code&amp;gt;x&amp;lt;/code&amp;gt; and &lt;code&amp;gt;y&amp;lt;/code&amp;gt;. The position of the photo rectangles are relative to the enclosing rectangle, which has three times the width of a single photo rectangle and the same height. The photos are placed at the x-positions 0, 300 and 600 and at y-position 0 such that they appear side by side. As we see in lines 5 and 21, we can use arbitrary JavaScript expressions for the property values. In the example, we use the expressions &lt;code&amp;gt;3 * 300&amp;lt;/code&amp;gt; and &lt;code&amp;gt;2 * 300&amp;lt;/code&amp;gt;.
 
With these changes, we see the same photo three times. By changing the properties &lt;code&amp;gt;source&amp;lt;/code&amp;gt; and &lt;code&amp;gt;text&amp;lt;/code&amp;gt;, we can easily change the image and the title of the photos.
 
The code isn't well written and smells of heavy code duplication. We'll fix the duplication from the three almost identical photo rectangles in the next module [[Qt_Quick_Tutorial_Components | Components]]. We'll fix the duplication from the magical numbers like 300, 25, 65 or 20 right way - by introducing properties.
 
The worst offender is the magic number 300, which occurs 13 times. So, if we want to change the size of our photo frames to, say, 400, we must perform 13 changes - and will typically forget to change at least one occurrence. The solution is to introduce a property &lt;code&amp;gt;frameSize&amp;lt;/code&amp;gt; at the beginning of the big rectangle and replace every occurrence of 300 by &lt;code&amp;gt;frameSize&amp;lt;/code&amp;gt;. Similarly, we eliminate the magic numbers 10, 25 and 65 by introducing the properties &lt;code&amp;gt;leftMargin&amp;lt;/code&amp;gt;, &lt;code&amp;gt;topMargin&amp;lt;/code&amp;gt; and &lt;code&amp;gt;bottomMargin&amp;lt;/code&amp;gt;, respectively, and by replacing every occurrence of these magic numbers by its properties. We also spot that &lt;code&amp;gt;235 = 300 - 65 = frameSize - bottomMargin&amp;lt;/code&amp;gt; and replace every occurrence of 235 by the expression &lt;code&amp;gt;frameSize - bottomMargin&amp;lt;/code&amp;gt;. While we are on a roll, we also replace the RGB value &lt;code&amp;gt;&quot;#FFF8DC&amp;quot;&lt;/code&amp;gt; by the property &lt;code&amp;gt;frameColor&amp;lt;/code&amp;gt;. After all these modifications, the code for the enclosing rectangle and photo 3 looks as follows (see [[BasicSteps_4 | BasicSteps_4.qml]] for the complete code):
 
<code><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: &quot;#FFF8DC&amp;quot; // cornsilk
 
width: 3 * frameSize; height: frameSize
 
…
 
// Photo 3<br /> Rectangle {<br /> x: 2 * frameSize; y: 0<br /> width: frameSize; height: frameSize<br /> color: frameColor
 
Image {<br /> x: leftMargin; y: topMargin<br /> source: &quot;cotton_grass.jpg&amp;quot;<br /> }
 
Text {<br /> x: 0; y: frameSize - bottomMargin<br /> text: &quot;Cotton Grass&amp;quot;<br /> font.pixelSize: fontSize<br /> width: frameSize; horizontalAlignment: Text.AlignHCenter<br /> height: bottomMargin; verticalAlignment: Text.AlignVCenter<br /> }<br /> }<br /></code>
 
The general syntax for a '''custom property''' is<br /><code><br /> property &lt;type&amp;gt; &lt;name&amp;gt;[: &lt;value&amp;gt;]<br /></code><br />The keyword &lt;code&amp;gt;property&amp;lt;/code&amp;gt; is followed by the name of the type, &lt;code&amp;gt;&amp;#60;type&amp;amp;#62;&lt;/code&amp;gt;, and the name of the property, &lt;code&amp;gt;&amp;#60;name&amp;amp;#62;&lt;/code&amp;gt;. The default value, &lt;code&amp;gt;&amp;#60;value&amp;amp;#62;&lt;/code&amp;gt;, for the property is optional. For example, the line<br /><code><br /> property int frameSize: 300<br /></code><br />defines a property with name &lt;code&amp;gt;frameSize&amp;lt;/code&amp;gt;, which is of integer type and which has the default value 300.
 
So far, we glossed over the '''scoping rules''' for properties, because they worked as expected. The properties of a parent instance are accessible by the child instances, the grandchild instances and so on all the way down the instance tree. This is why, for example, the property &lt;code&amp;gt;leftMargin&amp;lt;/code&amp;gt; can be used in the grandchild &lt;code&amp;gt;Image&amp;lt;/code&amp;gt; of the outermost &lt;code&amp;gt;Rectangle&amp;lt;/code&amp;gt;, where it is defined. For the moment, we can live with this scoping rule, which we'll amend when needed.
 
&quot;Module 2 - Components&amp;quot;:http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial_Components
 
&quot;Tutorial Main Page&amp;quot;:http://developer.qt.nokia.com/wiki/Qt_Quick_Tutorial

Latest revision as of 07:05, 29 August 2017

Redirect to:

Retrieved from "https://wiki.qt.io/index.php?title=Qt_Quick_Tutorial_Basics_2&oldid=31432"