Creating and running your first application with Harmattan Platform SDK

This section explains how you can easily create your first application, a Hello World program, on MeeGo 1.2 Harmattan platform. Creating a Hello World program is an optional step in the set-up process. However, by creating the Hello World application you can ensure that your development environment has been installed successfully.

MeeGo 1.2 Harmattan Platform SDK provides you with a simple project creator which makes it easy to start developing UI applications with QML or MeeGo Touch Framework. Based on your selection, it creates the project for you along with the Debian packaging files.

Prerequisites

Harmattan Platform SDK installed on your host workstation.
Xephyr running on your host workstation, launched with the following command:

$ Xephyr :2 -host-cursor -screen 480x854x16 -dpi 96 -ac +extension Composite &

Creating a new project

To log into Scratchbox, enter the following command in the host workstation terminal:

scratchbox

Scratchbox installed with Harmattan Platform SDK contains a number of different build targets. In this example, the HARMATTAN_X86 target is used.

To create a new project with the HARMATTAN_X86 target:

1. Enter the following command in Scratchbox:

sb-menu

The command opens a menu that allows you to manage the build targets. From there, you can activate the required HARMATTAN_X86 target.

2. After selecting the correct target, install the package that allows you to use the provided templates when creating new projects. Enter the following command:

[sbox-HARMATTAN_X86: ~] > apt-get install project-templates

3. To run the project creator script, enter the following command:

create-project

The project creator script offers default values for many of the attribute fields, such as the path for the project to be created. You can modify all other fields as needed, but you must set the program type to be created option as: c++-qml/meegotouch

The newly created template application is now available in Scratchbox in the selected directory. All the code is placed in a directory that is named according to the project name that you have given. The template includes enough code to bring up an empty application window and contains the files needed for Debian packaging. The following is an example of the console log:

[sbox-HARMATTAN_X86: ~] > create-project 
Enter path where you want to create new project [/home/tester]:
Enter program type to create (c++-qml, meegotouch) [c++-qml]:
Enter program name [MyProgram]:cplusplusqml
Enter package name [cplusplusqml]:
Enter main class name [MainWindow]:
Enter maintainer name (used for debian package):tester
Enter e-mail address (used for debian package):tester@ovi.com

In the future, you can do the same operation with the following command line:
create-project -p "/home/tester" -t c++-qml -n "cplusplusqml" -g cplusplusqml -m "tester" -e tester@ovi.com -c MainWindow

Overview
--------
Destination path: /home/tester
Project name: cplusplusqml
Package name: cplusplusqml
Icon name: cplusplusqml
Binary name: cplusplusqml
Project directory: /home/tester/cplusplusqml-0.1
Main class name: MainWindow
Maintainer: tester
e-mail address: tester@ovi.com
Is this OK? Enter "y" to confirm, or anything else to abort:y

New project successfully created in /home/tester

Before publishing you should do the following:
-Add short and long package descriptions to debian/control
-Add any dependencies and build dependencies to debian/control
-Create icon for your project, matching the name defined in .desktop file
-Update debian/README and debian/README.debian files (or remove, if empty)
-Add suitable license text to project files
[sbox-HARMATTAN_X86: ~] > cd cplusplusqml-0.1/
[sbox-HARMATTAN_X86: ~/cplusplusqml-0.1] > ls
cplusplusqml.pro  debian  src
[sbox-HARMATTAN_X86: ~/cplusplusqml-0.1] >

The project directory contains subdirectories debian and src, and the project file [projectname].pro.

Compiling the template code

To compile the template application in its default state:

Enter the following command in the project directory:

dpkg-buildpackage -rfakeroot

The compiled package is called [projectname]*[target].deb and it is placed under one level above the project directory.

Installing and running the template code

To run the compiled binary:

1. Go to one level above src directory.

2. Enter the following command:

dpkg -i [projectname]*i386.deb

3. To run the binary, enter the following command:

meego-run [projectname]

The meego-run is a script that starts the necessary services before launching any application. The template application appears in the Xephyr window.

Enhancing the template code

To make your application a little more interesting, add a button that can toggle its text between "Hello" and "World" when tapped:

If you have chosen to create an application using QML, proceed to Using QML.

If you have chosen to create an application using MeeGo Touch Framework, proceed to Using MeeGo Touch Framework.

Using QML

To extend the QML template above, add a button to the main application in the MainWindow.qml:

1. Edit the [projectname] source:

a. Add the line initialPage: MainWindow {} to [projectname]/src/[projectname].qml file:

[sbox-HARMATTAN_X86: ~/cplusplusqml-0.1/src] > cat cplusplusqml.qml 
import com.meego 1.0

PageStackWindow {
        initialPage: MainWindow {}
}
[sbox-HARMATTAN_X86: ~/cplusplusqml-0.1/src] >

b. Add MainWindow.qml file to the src folder.

vi MainWindow.qml

c. Edit the code inside MainWindow.qml file. For example, to add a button that toggles the text between Hello and World, the resulting MainWindow.qml file is:

 
import QtQuick 1.1
import com.meego 1.0

Page {

    Button {
        id: button 
        width: parent.width
        text: "Hello"
        onClicked: button.text == "Hello" ? button.text = "World" : button.text = "Hello"
    }

}

2. Edit the [projectname]/src/src.pro file as follows under #MAKE INSTALL section:

qmlgui.files += *.qml

The MainWindow.qml is also included when you build the Debian package. For instructions, see the next section.

Compiling and running your QML application in Scratchbox

To run the QML application in Scratchbox, execute the following commands:

[sbox-HARMATTAN_X86: ~/[projectname]-0.1/] > dpkg-buildpackage -rfakeroot
[sbox-HARMATTAN_X86: ~/[projectname]-0.1/] > cd ..
[sbox-HARMATTAN_X86: ~/[projectname]-0.1/] > dpkg -i [projectname]*deb

To launch the application, click the application icon in the Applications menu.

"Hello" appears on the screen:

Hello World using plain QML Framework

When you tap the button, the text changes to "World":

Hello World using plain QML Framework

Note: You can also run your application on the Harmattan device. For instructions, see Packaging and running binaries on the device.

Using MeeGo Touch Framework

In the MeeGo Touch UI library, you can add a button to the main application window with the class MButton as follows:

1. Edit the mainwindow.h file:

a. Include the needed header file.

b. Declare a variable of type MButton.

c. Add a declaration of the buttonClicked() function that is called when the button is tapped.

The resulting mainwindow.h file is:

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <MApplicationPage>
#include <MButton>

class MainWindow : public MApplicationPage
{
    Q_OBJECT

public:
    MainWindow();
    ~MainWindow();
    virtual void createContent();
private:
     MButton *button;
public Q_SLOTS:
     void buttonClicked();
            
};

#endif // MAINWINDOW_H

2. In the MainWindow class definition in mainwindow.cpp file, add the code that creates the button and connects the clicked() signal emitted when tapped:

#include <MApplicationPage>

#include "mainwindow.h"

MainWindow::MainWindow()
    : MApplicationPage()
{
        /*Set the title of our application*/
        setTitle("Hello World");
                 
        /*Add a button to the main window and set the text to "Hello" */
        button = new MButton("Hello");
                         
        /*Set this newly created button to be the central widget of the main window*/
        setCentralWidget(button);
                                 
        /*Connect the clicked() signal emitted by the push button when clicked by the mouse. */
        connect(button, SIGNAL(clicked(bool)), this, SLOT(buttonClicked()));                                     
                                        
}

void MainWindow::createContent()
{
}

/* Toggle the text in the push button when clicked by the mouse*/
void MainWindow::buttonClicked()
{
        if (button->text().compare("Hello") == 0) {
           button->setText("World");
        }
        else {
               button->setText("Hello");
        }
}

MainWindow::~MainWindow()
{
}

Your application is now ready for compiling and running.

Compiling and running your MeeGo Touch application in Scratchbox

To compile and run your MeeGo Touch application in Scratchbox, enter the following commands:

[sbox-HARMATTAN_X86: ~/myprogram-0.1/] > dpkg-buildpackage -rfakeroot
[sbox-HARMATTAN_X86: ~/myprogram-0.1/] > cd ..
[sbox-HARMATTAN_X86: ~/] > dpkg -i myprogram*deb

To launch the application, click the myprogram icon in the Applications menu.

"Hello" appears on the screen:

Hello World using MeeGo Touch Framework

When you tap the button, the text changes to "World":

Hello World using MeeGo Touch Framework

Note: You can also run your application on the Harmattan device. For instructions, see Packaging and running binaries on the device.