Build your very first Ubuntu SDK app

The Ubuntu SDK contains a full development environment, complete with IDE and support for running apps on your desktop as well as on Ubuntu phone and tablet devices.

With the SDK, you can write apps using a number of different frameworks:

• QML – Based on the Qt project, QML is a neat, high-level declarative language that makes writing beautiful, slick, animated apps simple and easy.
• HTML5 – You can write two types of HTML5 applications with the Ubuntu SDK: a plain HTML5 app or an app using the Apache Cordova (also known as Phonegap) support that is included. Either way, you can use Ubuntu toolkit components so your HTML5 app looks and feels like a real Ubuntu app.
• Scopes – Scopes are ways of searching for and presenting content in the Ubuntu dash, and you can create them easily with the SDK.
• OpenGL – If you have an OpenGL game or other project, you can run this across the Ubuntu platform.

In this article, I will write an application using QML, which the majority of new Ubuntu app developers are using to write their apps.

I'll begin by looking at what QML is, how it works, and then I will show you how to write an app that I wrote and uploaded to the Ubuntu Software Center called Sleepy Time, that plays soothing sounds for helping babies, children, and adults to sleep.

Creating a Project

To get started, load the Ubuntu SDK and create a new QML project. To do this click File | New File or Project… . Next, ensure that Ubuntu is selected in the left pane and click Simple Touch UI , then Create .

In the next dialog, name the project sleepy and select a place where the project will be created. From the Add to the version control combo box, select Bazaar so you can automatically version your project and then click Finish . (See the box "Installing the Ubuntu SDK" for more information.)

Figure 1: Clicking the API link on the left provides API information for using Ubuntu Components.

A series of files has now been created, and these files are shown in the left side panel. Double-clicking on a file loads the file into the editor. Double-click on sleepy.qml if it is not already loaded, and you will see code shown in Listing 1 in the editor (I have removed comments shown with /* */ and // to be concise).

01 import QtQuick 2.0
02     import Ubuntu.Components 0.1
03     import "components"
04
05     MainView {
06         objectName: "mainView"
07
08         applicationName: "uutest"
09
10         width: units.gu(100)
11         height: units.gu(75)
12
13         Page {
14         title: i18n.tr("Simple")
15
16         Column {
17             spacing: units.gu(1)
18             anchors {
19                 margins: units.gu(2)
20                 fill: parent
21             }
22
23             HelloComponent {
24                 id: label
25                 objectName: "label"
26
27                 text: i18n.tr("Hello..")
28             }
29
30             Button {
31                 objectName: "button"
32                 width: parent.width
33
34                 text: i18n.tr("Tap me!")
35
36                 onClicked: {
37                     label.text = i18n.tr("..world!")
38                 }
39             }
40         }
41         }
42     }

You can now run the project by clicking the green arrow in the left side panel near the bottom of the window. Running the app displays a Tap Me button that, when tapped, changes the text in the box above.

At the top of this code snippet, I import some libraries of functionality, much like other programming languages.

One key library here is Ubuntu.Components , which is a collection of user interface controls used to build apps. To see the range of components available, click Tools | Ubuntu Touch | Ubuntu Touch Showcase Gallery .

If you do this, a new project is loaded and you can press the green arrow to display the components and also browse the code. When you are finished poking around with the showcase gallery, right-click the top sleepy entry in the sidebar (with the blue folder and arrow to the left) and select Set "sleepy" as Active Project , so you are working on that project (this ensures that, when you run the app, it will run sleepy and not the components gallery).

In QML, you see a series of nested user interface components, each nested within curly braces ({} ). The MainView project is the root container used in all apps, and nested inside is a Page , which is an area that you can fill with the content of your app.

Within the Page is a Column element, which simply organizes its children vertically. And, within Column , you have something called HelloComponent .

This component is defined elsewhere (in the components sub-directory). You will notice that I use the same file name as the component name (HelloComponent is components/hellocomponent.qml ). This method of embedded components provides a handy way to share code across your app and re-use it. I will discuss this component more a little later.

Beneath the HelloComponent is a Button , which is another Ubuntu component that simply displays the button you click to change the text of the HelloComponent .

Within each component are settings that you can configure. As an example, in Button , you set the name for the object that you can reference (objectName ) and set the text displayed on the button (text: ).

Note that, when setting the text, you wrap it in i18n.tr() , which will mark the string as a translatable string that you can translate with gettext .

A key feature of the Ubuntu user interface toolkit is the ability to scale to all form factors in a world defined by users with multiple devices.

The approach taken has been to define a new unit type, the grid unit (gu for short). Grid units translate to a pixel value depending on the type of screen and device that the application is running on. Check out Table 1 for some examples.

In the previous code, you can see that I set the spacing in between children in the Column to 1gu and set the margins as part of the anchors (the margins are anchored to the parent component, the Page ). I also set the size of the app itself with the "width" and "height" lines in the MainView.

Components and Signals

Before I move on, I'll quickly cover the HelloComponent . In components/hellocomponent.qml , the code looks like what is shown in Listing 2.

01 import QtQuick 2.0
02     import Ubuntu.Components 0.1
03
04     UbuntuShape {
05         width: 200
06         height: width
07
08         property alias text : myText.text
09
10         Label {
11         id: myText
12         anchors.centerIn: parent
13         }
14     }

Here, I use an UbuntuShape component (a nice rounded square) and then embed a Label component, which has an id of 'myText' , and I center the text. You may also notice that I don't actually set what the text is. This is where properties come in.

The Label component has a 'text' property that can be used to set the text of the label, but I really want to set this value outside of the HelloComponent and in my other source file.

That's why I have the following line:

property alias text : myText.text

It creates an alias for the myText.text property that is available outside of the component with the alias text .

To see this in action, go back to sleepy.qml , where you can see:

onClicked: {
    label.text = i18n.tr("..world!")
}

This block appears within the Button component and is how you deal with interactions in QML.

Essentially, every component has a range of different signals – that is, types of interaction with that component that when triggered can run some code.

In this case, you see a clicked signal in Button , and when I use the onClicked block (adding on before the signal creates a block to respond to a signal), the code inside it is executed when the button is clicked. It just so happens that this code references the label object (HelloComponent ), and you can set the label.text property – the alias to the text that you want to appear when the button is clicked.