Getting Started with the Trolltech Greenphone SDK

Qtopia development will make any Qt or KDE developer feel right at home, as it is quite compatible with the desktop version of Qt. There are a few minor differences, as we will see in the example application in the Greenphone SDK found at ~/projects/application.

The style lately, with C++ in general and Qt v4.x in particular, is to include a header named after the class we want declared. This saves ever having to guess which header contains a class' declaration. In the following example, we have the old way commented out and the easier-to-remember method following it:

// main.cpp
#include "example.h"
// #include <qtopia/qtopiaapplication.h>
#include <QtopiaApplication>

QTOPIA_ADD_APPLICATION("example", Example)
QTOPIA_MAIN

// end of main.cpp

The function formerly known as main() has been deprecated in Qtopia in favor of two macros.

In the above example, the QTOPIA_ADD_APPLICATION macro is used to create an instance of the main application window. The first parameter is the executable name, and the second parameter is the base class of the application window class.

The QTOPIA_MAIN macro expands out either to the traditional main() function if building a traditional application or to the entry point needed if building a quick launcher plugin.

Inside our example.h, we find the class declaration for our main window, which we have sub-classed from a generic QWidget:

#ifndef EXAMPLE_H
#define EXAMPLE_H
#include "ui_examplebase.h"

class ExampleBase : public QWidget, public Ui_ExampleBase
{
public:
    ExampleBase( QWidget *parent = 0, Qt::WFlags f = 0 );
    virtual ~ExampleBase();
};

class Example : public ExampleBase
{
    Q_OBJECT
public:
    Example( QWidget *parent = 0, Qt::WFlags f = 0 );
    virtual ~Example();

private slots:
    void goodBye();
};

#endif // EXAMPLE_H

This class uses a form created using the Qt Designer GUI building tool, so we see an include file called ui_examplebase.h that brings in its declaration. In Qt, headers with names starting with ui_ typically are Designer-generated. This is followed by our class' immediate ancestor called ExampleBase. This base class inherits from both QWidget and the class defined by the GUI builder called Ui_ExampleBase.

Figure 3. Designer Running in VM

Our main window is an instance of the Example class derived from ExampleBase. It makes use of a technique called signals and slots—a method used by Trolltech that allows great flexibility for defining how a function is invoked. The invoking side of the connection is called a SIGNAL(), and the invokee side is called a SLOT(). They are joined together using a method called connect() that allows a many-to-many connection relationship. Qt uses a preprocessor to add metadata processing to add to C++ dynamic invocation and object introspection effectively and elegantly—elements available in other OOP languages.

Our final code example shows the implementation of our classes:

#include "example.h"
#include <QPushButton>

ExampleBase::ExampleBase( QWidget *parent, Qt::WFlags f )
    : QWidget( parent, f )
{
    setupUi( this );
}

ExampleBase::~ExampleBase() { }

Example::Example( QWidget *parent, Qt::WFlags f )
    : ExampleBase( parent, f )
{
    connect(quit, SIGNAL(clicked()), this, SLOT(goodBye()));
}

Example::~Example() { }

void Example::goodBye()
{
    close();
}

Our ExampleBase class' constructor calls the Designer-generated setupUi() method to have the form-defined child widgets created and their layout and other properties set. Without that step, it would be a generic QWidget.

The next interesting thing we see is the constructor for the Example class. It calls the connect() method to join the clicked() signal on the Qt Designer-generated QPushButton called quit with our goodBye() slot. This allows us to exit the example program by clicking the QPushButton labeled Quit.