~mhall119/developer-ubuntu-com/currency_tutorial

« back to all changes in this revision

Viewing changes to currency_tutorial.html

  • Committer: mhall119
  • Date: 2013-04-09 19:30:58 UTC
  • Revision ID: mhall119@ubuntu.com-20130409193058-rveo1bwri48l2g77
Update 'The main view' section

Show diffs side-by-side

added added

removed removed

Lines of Context:
43
43
 
44
44
<ol>
45
45
        <li>In Qt Creator, press <strong>Ctrl+N</strong> to create a new project</li>
46
 
        <li>Select the<strong> Projects &gt; Application &gt; Qt Quick UI</strong> template and click <strong>Choose...</strong></li>
 
46
        <li>Select the<strong> Projects &gt; Ubuntu &gt; Ubuntu UI - Simple</strong> template and click <strong>Choose...</strong></li>
47
47
        <li>Give the project <strong>CurrencyConverter</strong> as a <strong>Name</strong>. You can leave the <strong>Create in:</strong> field as the default and then click <strong>Next</strong>.</li>
48
48
        <li>You can optionally set up a revision control system such as Bazaar in the final step, but that’s outside the scope of this tutorial. Click on <strong>Finish</strong>.</li>
49
 
        <li>Once the project is created, <strong>delete the contents</strong> of the <em>CurrencyConverter.qml</em> file, <strong>add</strong> the following code to it, and then <strong>save</strong> it with <strong>Ctrl+S</strong>:</li>
 
49
        <li>Replace the <strong>Column</strong> component and all of it's chidren, and replace them with the <strong>Page</strong> as shown below, and then <strong>save</strong> it with <strong>Ctrl+S</strong>:</li>
50
50
</ol>
51
51
[sourcecode language="javascript"]
52
52
import QtQuick 2.0
53
53
import Ubuntu.Components 0.1
54
54
 
 
55
/*!
 
56
    \brief MainView with a Label and Button elements.
 
57
*/
 
58
 
55
59
MainView {
 
60
    // objectName for functional testing purposes (autopilot-qt5)
56
61
    objectName: "mainView"
57
62
    applicationName: "CurrencyConverter"
58
 
    id: root
59
 
 
60
 
    width: units.gu(60)
61
 
    height: units.gu(80)
62
 
 
63
 
    property real margins: units.gu(2)
64
 
    property real buttonWidth: units.gu(9)
65
 
 
66
 
    Label {
67
 
       id: title
68
 
       ItemStyle.class: "title"
69
 
       text: i18n.tr("Currency Converter")
70
 
       height: contentHeight + root.margins
71
 
       anchors {
72
 
           left: parent.left
73
 
           right: parent.right
74
 
           top: parent.top
75
 
       }
 
63
 
 
64
    width: units.gu(100)
 
65
    height: units.gu(75)
 
66
    
 
67
    Page {
 
68
        anchors.fill: parent
 
69
        title: i18n.tr("Currency Converter")
 
70
 
 
71
        property real margins: units.gu(2)
 
72
        property real buttonWidth: units.gu(9)
76
73
    }
77
74
}
78
75
[/sourcecode]
88
85
</ol>
89
86
<code>qmlscene ~/CurrencyConverter/CurrencyConverter.qml</code>
90
87
 
91
 
<img class="aligncenter size-full wp-image-3736" title="Currency Converter MainView" src="http://developer.ubuntu.com/wp-content/uploads/2012/12/Currency-Converter-Rectangle.png" alt="" width="482" height="177" />
 
88
<img class="aligncenter size-full wp-image-3736" title="Currency Converter MainView" src="currency_header.png" alt="" width="482" />
92
89
 
93
90
Hooray! Your first Ubuntu app for the phone is up and running. Nothing very exciting yet, but notice how simple it was to bootstrap it. You can close your app for now.
94
91
 
103
100
 
104
101
We now move on to declaring our objects. In QML, a user interface is specified as a tree of objects with properties. JavaScript can be embedded as a scripting language in QML as well, but we’ll see this later on.
105
102
 
106
 
[sourcecode language="javascript" firstline="4"]
 
103
[sourcecode language="javascript" firstline="8"]
107
104
MainView {
 
105
    // objectName for functional testing purposes (autopilot-qt5)
108
106
    objectName: "mainView"
109
107
    applicationName: "CurrencyConverter"
110
 
    id: root
111
 
 
112
 
    width: units.gu(60)
113
 
    height: units.gu(80)
114
 
 
115
 
    property real margins: units.gu(2)
116
 
    property real buttonWidth: units.gu(9)
117
 
 
118
 
    Label {
119
 
       id: title
120
 
       ItemStyle.class: "title"
121
 
       text: i18n.tr("Currency Converter")
122
 
       height: contentHeight + root.margins
123
 
       anchors {
124
 
           left: parent.left
125
 
           right: parent.right
126
 
           top: parent.top
127
 
       }
 
108
 
 
109
    width: units.gu(100)
 
110
    height: units.gu(75)
 
111
    
 
112
    Page {
 
113
        anchors.fill: parent
 
114
        title: i18n.tr("Currency Converter")
 
115
 
 
116
        property real margins: units.gu(2)
 
117
        property real buttonWidth: units.gu(9)
128
118
    }
129
119
}
130
120
[/sourcecode]
131
121
 
132
 
Secondly, we create a <a href="http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/qml-ubuntu-components0-mainview.html">MainView</a>, the most essential SDK component, which acts as the root container for our application. It also provides the standard <a href="http://design.ubuntu.com/apps/building-blocks/toolbar">Toolbar</a> and (in the very near future) <a href="http://design.ubuntu.com/apps/building-blocks/header">Header</a>.
 
122
Secondly, we create a <a href="http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/qml-ubuntu-components0-mainview.html">MainView</a>, the most essential SDK component, which acts as the root container for our application. It also provides the standard <a href="http://design.ubuntu.com/apps/building-blocks/toolbar">Toolbar</a> and <a href="http://design.ubuntu.com/apps/building-blocks/header">Header</a>.
133
123
 
134
124
With a syntax similar to JSON, we define its <a href="http://qt-project.org/doc/qt-4.8/propertybinding.html#properties">properties</a> by giving it an id we can refer it to (<em>root</em>), and then we define some visual properties (<em>width</em>, <em>height</em>, <em>color</em>). Notice how in QML properties are bound to values with the ‘<em>property: value</em>’ syntax. We also define a custom property called <em>margins</em>, of <a href="http://qt-project.org/doc/qt-5.0/qtqml/qtqml-typesystem-basictypes.html">type</a> <a href="http://qt-project.org/doc/qt-5.0/qtqml/qml-real.html">real</a> (a number with decimal point). Don’t worry about the <em>buttonWidth</em> property for now, we’ll use it later on. The rest of the properties available in the MainView we leave at their default values by not declaring them.
135
125
 
136
126
Notice how we specify units as <em>units.gu</em>. These are <strong>grid units</strong>, which we are going to talk about in a minute. For now, you can consider them as a form-factor-agnostic way to specify measurements. They return a pixel value that’s dependent on the device the application is running on.
137
127
 
138
 
Inside our main view, we add a child Ubuntu <a href="http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/qml-ubuntu-components0-label.html">Label</a> named <em>title</em>, which we’re going to style as an Ubuntu title. We select the style through a <em>class</em> property, similarly as you would do with CSS (you can have a peek at class names <a href="file:///usr/share/themes/Ambiance/qmltheme/default.qmltheme">here</a> or <a href="http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/theming-components.html#theming-engine-theming-components">learn more about theming</a>).
139
 
 
140
 
We also added some text to the label, ensuring it is enclosed with the <em>i18n.tr()</em> function, which will make it translatable. We also set the size through <a href="http://doc-snapshot.qt-project.org/5.0/qtquick/qml-qtquick2-text.html#contentHeight-prop">contentHeight</a>, a property that returns the height of the text.
141
 
 
142
 
Anchors allow us to specify the layout and position the label relative to its parent’s anchors (the Rectangle), based on the <a href="http://doc.qt.digia.com/qt/qml-anchor-layout.html#anchor-layout">QML anchoring system</a>
143
 
<p style="text-align: center;"><img class="aligncenter  wp-image-3740" title="anchoring" src="http://developer.ubuntu.com/wp-content/uploads/2012/12/anchoring.png" alt="" width="210" height="142" /></p>
144
 
 
145
 
Let's add some margins to our header label. Add the following code for anchors.leftMargin and anchors.topMargin around line 25 of our code:
146
 
 
147
 
[sourcecode language="javascript" firstline="20" highlight="25,26"]
148
 
       height: contentHeight + root.margins
149
 
       anchors {
150
 
           left: parent.left
151
 
           right: parent.right
152
 
           top: parent.top
153
 
           leftMargin: root.margins
154
 
           topMargin: root.margins / 2
155
 
       }
156
 
[/sourcecode]
157
 
 
158
 
<img src="http://developer.ubuntu.com/wp-content/uploads/2012/12/Label-margins1.png" alt="" title="Label margins" width="379" height="101" class="aligncenter size-full wp-image-4092" />
159
 
 
160
 
Now our header label looks much better with margins.
 
128
Inside our main view, we add a child Ubuntu <a href="http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/qml-ubuntu-components0-page.html">Page</a>, which will contain the rest of our components as well as provide an Ubuntu title.  We title text to the page, ensuring it is enclosed with the <em>i18n.tr()</em> function, which will make it translatable.
161
129
 
162
130
<div class="clearfix"></div>
163
131
<h3 id="resolution-independence">Resolution independence</h3>