Create a currency converter phone app

By David Planella (code by the SDK Team)

In this recipe you will learn how to write a currency converter app for Ubuntu on the phone. You will be using several components from the Ubuntu QML toolkit: i18n, units, ItemStyle for theming, Label, ActivityIndicator, Popover, Button, TextField, ListItems.Header and ListItems.Standard

The application will show you how to use the QML declarative language to create a functional user interface and its logic, and to communicate through the network and fetch data from a remote source on the Internet.

In practical terms, you will be writing an application that performs currency conversion between two selected currencies. The rates are fetched using the European Central Bank’s API. Currencies can be changed by pressing the buttons and selecting the currency required from the list.

Requirements

• Ubuntu 12.04 or later – get Ubuntu ›
• Qt 5 and the Ubuntu QML toolkit – get Qt5 and the Ubuntu toolkit ›
• Code editor (Qt Creator recommended) – install Qt Creator ›

The tools

The focus of this tutorial will be on the Ubuntu UI toolkit preview and its components, rather than on the tools. However, it is worth mentioning and giving an overview of the tools you will be using:

Development host

Ubuntu 12.04 (or later) will be used as the host machine for development. At the end of this recipe you will have created a platform-agnostic QML app that can be run on the development host machine. Subjects such as cross-compiling for a different architecture and installation on a phone are more advanced topics that will be covered at a later date when the full Ubuntu SDK is released.

Integrated Development Environment (IDE)

We will be writing declarative QML code, which does not need to be compiled to be executed, so you can use your favourite text editor to write the actual code, which will consist of a single QML file.

For this tutorial, we recommend using Qt Creator. Qt Creator is a powerful IDE to develop applications based on the Qt framework.

QML viewer

To start QML applications, either during the prototyping or final stages, we will use Qt Creator and the Ctrl+R shortcut.

However, as an alternative for quick app viewing with QML Scene, it is worth noting that you can also use QML Scene without Qt Creator. QML Scene is a command-line application that interprets and runs QML code.

To run a QML application with QML Scene, open up a terminal with the Ctrl+Alt+T key combination, and execute the qmlscene command, followed by the path to the application:

$ qmlscene /path/to/application.qml

Learn more about QML Scene ›

Getting started

To start Qt creator, simply open the Dash, start typing “qt creator”, and click on the Qt Creator icon that appears on the search results.

Next stop: putting our developer hat on.

The main view

We’ll start off with a minimum QML canvas with our first Ubuntu component: a label inside the main view.

1. In Qt Creator, press Ctrl+N to create a new project
2. Select the Projects > Ubuntu > Ubuntu UI – Simple template and click Choose…
3. Give the project CurrencyConverter as a Name. You can leave the Create in: field as the default and then click Next.
4. 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 Finish.
5. Replace the Column component and all of its children, and replace them with the Page as shown below, and then save it with Ctrl+S:

import QtQuick 2.0
import Ubuntu.Components 0.1

/*!
    \brief MainView with a Label and Button elements.
*/

MainView {
    id: root
    // objectName for functional testing purposes (autopilot-qt5)
    objectName: "mainView"
    applicationName: "CurrencyConverter"

    width: units.gu(100)
    height: units.gu(75)
    
    property real margins: units.gu(2)
    property real buttonWidth: units.gu(9)

    Page {
        title: i18n.tr("Currency Converter")

    }
}

Try to run it now to see the results:

1. Inside Qt Creator, press the Ctrl+R key combination. It is a shortcut to the Build > Run menu entry

Or alternatively, from the terminal:

1. Open a terminal with Ctrl+Alt+T
2. Run the following command:

qmlscene ~/CurrencyConverter/CurrencyConverter.qml

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.

Now starting from the top of the file, let’s go through the code.

import QtQuick 2.0
import Ubuntu.Components 0.1

Every QML document consists of two parts: an imports section and an object declaration section. First of all we import the QML types and components that we need, specifying the namespace and its version. In our case, we import the built-in QML and Ubuntu types and components.

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.

MainView {
    id: root
    // objectName for functional testing purposes (autopilot-qt5)
    objectName: "mainView"
    applicationName: "CurrencyConverter"

    width: units.gu(100)
    height: units.gu(75)
    
    property real margins: units.gu(2)
    property real buttonWidth: units.gu(9)

    Page {
        title: i18n.tr("Currency Converter")

    }
}

Secondly, we create a MainView, the most essential SDK component, which acts as the root container for our application. It also provides the standard Toolbar and Header.

With a syntax similar to JSON, we define its properties by giving it an id we can refer it to (root), and then we define some visual properties (width, height, color). Notice how in QML properties are bound to values with the ‘property: value’ syntax. We also define a custom property called margins, of type real (a number with decimal point). Don’t worry about the buttonWidth 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.

Notice how we specify units as units.gu. These are grid units, 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.

Inside our main view, we add a child Ubuntu Page, 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 i18n.tr() function, which will make it translatable.

Resolution independence

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 in short). Grid units translate to a pixel value depending on the type of screen and device the application is running on. Here are some examples:

Learn more about resolution independence ›

Internationalization

As part of the Ubuntu philosophy, internationalization and native language support is a key feature of the Ubuntu toolkit. We’ve chosen gettext as the most ubiquitous Free Software internationalization technology, which we’ve implemented in QML through the family of i18n.tr() functions.

Up next: Fetching and converting currencies