bada for Qt developers by Keith Bauwisestatic.bada.com/contents/blog/20120130/Complete(v1.2).KB.pdf · bada for Qt developers 2 ... read-write property for the window orientation

bada for Qt developers

1


by Keith Bauwise


2

Contents

Introduction .................................................................................................................................................. 3

Finding your way around .............................................................................................................................. 5

Importing an application using Qt Creator ............................................................................................... 5

Importing an app using the bada IDE ........................................................................................................ 8

A closer look at the architectures ............................................................................................................... 15

Application Folders ................................................................................................................................. 15

Application Life Cycle .............................................................................................................................. 17

bada UI Structure .................................................................................................................................... 21

Qt UI Structure ........................................................................................................................................ 22

The QML Language ............................................................................................................................. 22

Event Management ................................................................................................................................. 24

Control Event Reporting...................................................................................................................... 24

Inter-Object event communication .................................................................................................... 28

Class Mapping ......................................................................................................................................... 31

A practical comparison ............................................................................................................................... 34


3

Introduction

Qt provides a multiplatform application framework which can be used to create both mobile and PC

applications. This document will explain the bada platform from a Qt perspective. We’ll concentrate on

the main areas that developers moving from another platform- not just Qt- will want to know about

bada. This is the type of platform introduction we believe software developers, curious about a new

platform, would like to see.

Audience:

Anyone with existing Qt development experience, considering developing for bada. Their

existing Qt experience can be advanced or basic. Any developer curious about the bada

platform.

Practical:

In this guide we take a practical approach and supply two complete code projects that can be

run in either platform. Each application will perform a similar operation and we show how each

can be tested in a simulated environment.

Topics

The topics covered in this article are split into three sections. This will allow the reader to easily focus on

their areas of interest.

Part 1

Finding your way around

Generally, the first thing a developer wants to do when starting with a new IDE is to import,

compile, simulate and deploy the sample applications. So, we’ll map the features of Qt Creator

to the bada IDE, explain what targets can be deployed to and identify the key differences

between bada devices.


4

Part 2

A closer look at the architectures

UI Structure. Compare the Frame, Form, Container/Controls with Qt’s Window, widgets and

layout policy.

Application folders. Compares project file structures for both types of project

Application Lifecycle. Comparison of the respective application life cycles

Event Management

Compare Qt’s events/actions, signals and slots mechanisms to that of bada’s Interface

class/Listener and SendUserEvent for inter-object communication.

Class Mapping

A mapping of most important bada classes to Qt classes, allowing a Qt developer to see what

classes the bada platform provides.

Part 3

A practical comparison

We’ve included two projects complete with source code: a Qt battery level indicator and its

bada equivalent. The reader can make direct code level comparisons between Qt and bada.


5

Part 1

Finding your way around

As a developer encountering a new IDE you will usually want to perform one of two operations:

Create a hello world application

Import an example application, compile and execute it

We will explore the latter.

Both the Eclipse IDE used by bada, and the Qt Creator IDE provide the developer with quick access to

example applications which can be imported, compiled and executed.

Qt Creator separates the example applications into Qt C++ examples and Qt Quick examples. bada’s

equivalent of Qt Quick is the UI builder.

Importing an application using Qt Creator

The following importing process will be familiar to the experienced Qt developer:

Figure 1.1 Qt Creator Welcome Screen


6

Qt example application selection.

Figure 1.2 Selecting Targets in Qt creator

Selecting targets to build for.

Figure 1.3 Compile/Build and Debug Options


7

Build, execute and debug IDE icons

Figure 1.4 Simulated Execution and Testing with Simulator Control

Application execution in simulator with simulator control.


8

Importing an app using the bada IDE

Here’s what you need to do to import one of the sample apps using the bada IDE:

Import example application to the workspace

Set the build configuration

Build application, based on build configuration setting

Execute in emulator or target

Importing a bada sample application is as easy as locating the required application in the sample list,

right-clicking, then select ‘copy into my workspace’. You will see that the Project Explorer window is

populated with the selected application.

Figure 1.5 bada Eclipse IDE


9

With the project now visible in the Project Explorer, we can now set the required build configuration.

This describes how the project will be built when we select build. Build configurations and Build options

appear under the context menu for the project. Right-click on the top-level folder of a project to reveal

its context menu.

This illustration shows the ‘Target-Debug’ build configuration (usually the default) being selected.

Project applications built with this setting can be executed on the emulator or the real target. Having set

the build configuration, we can now build our project.

Figure 1.6 Selecting Build Configuration


10

From the context menu choose Build to build the project using the current build configuration.

Figure 1.7 Building bada Project


11

From the application’s context menu we select how we wish to run the application.

Figure 1.8 Executing bada Project


12

Figure 1.9 Execution with the Emulator

To debug any of the sample applications, simply choose the ‘Debug As’ option from the application’s

context menu. Then select whether you want to debug with the emulator or on target- connected via

USB. With the necessary drivers installed, the IDE will show the debug perspective as soon as it hits a

breakpoint.

The following illustration shows all the Wave devices that can be targeted with the latest version of the

bada SDK. Individual specifications can be found at;

http://www.samsung.com/uk/consumer/mobile-devices/smartphones/bada

http://www.samsung.com/uk/consumer/mobile-devices/smartphones/bada


13

Wave 1 Wave 2 Wave 3

Wave M Wave Y


14

Wave 533

Wave 723 Wave 578 Wave 525


15

Part 2.

A closer look at the architectures

Application Folders

The following diagram shows the application file structures of bada and Qt applications. You’ll notice

several similarities, for example the src, header/include and resource folders exist for both.

Figure 2.1 Comparison of Project File Structures

The starting point of the bada application is <project name>Entry.cpp. In the figure shown above this is

TextToSpeechSampleEntry.cpp. The code executed in the file will create an instance of your application

when its icon is selected from the application menu. The code in this file will never require modification,

but it’s important to know its role. The file TextToSpeechSample.cpp is the application’s main file and is


16

the starting point for your development. In here you will find stubs that the bada application framework

will call at various stages of your application’s life cycle.

Another important file in the bada application file structure is the manifest file. This file can be

considered to be your bada application’s statement of definition. It defines the services and

functionality your app is to use, what API version your app is adhering to and what devices your app is

targeting. When you create your app with the SDK wizard, you will be given the option to use the default

manifest file or apply a real valid one, created on the developer site, following the definition or update

of a new application.

Qt project files

In Qt, comparisons could be drawn to the project (.pro) file. In this file you are required to specify the

functionality that your application will use. In the example Qt application supplied with this guide, we

use the Qt Mobility API, in particular ‘System Info’ to get battery information. The following lines were

added to the .pro file:

CONFIG += mobility

MOBILITY += systeminfo

In bada, the use of functionality is governed by privileges and the functionality of the platform is

categorized into privilege groups. To get battery information from the bada platform, the system service

privilege is required. The following lines need to be added to the manifest file:

<Privileges>

<Privilege>

<Name>SYSTEM_SERVICE</Name>

</Privilege>

</Privileges>

This new entry into the manifest file is not made manually. Whenever new functionality is required for

your application, the developer needs to go to developer.bada.com and re-define the areas of

functionality that their app uses. This process results in an updated manifest file that is downloaded

from the developer site. The developer then overwrites the old manifest file with the newly downloaded

file.

Resources required by your application will be contained in the /Res/ folder. This could be UI forms

created by the UI Builder, language files, images or audio. At runtime, your application can simply open

these files and use them as required.


17

Application Life Cycle

The bada application can exist in of a number of discrete states. These are shown below. In your

application’s main file, there are methods which are called by the bada framework when your app is in a

particular state. These methods are OnAppInitializing, OnForeground, OnBackground and

OnAppTerminating. While in the ‘running’ state, your application can either be in foreground or

background.

Figure 2.2 bada Application States


18

Figure 2.3 bada Application and Application Framework Interaction


19

Qt Quick Application Life Cycle

In Qt, running applications can be either in the Active state (in the foreground) or in the Minimised state

(in the background where they cannot be interacted with). The transition between the states takes place

as a result of user interaction. State transitions are detected by capturing the change of the

property platformWindow.windowState. There are several ways to terminate an application when it

is in either of these states. All applications are automatically terminated when the device is shut down.

The windowState properties can return the following information:

windowState.visible: returns true if the window or its thumbnail is shown;

otherwise false if the window or its thumbnail has been hidden at least for 1000 ms.

windowState.active: returns true if the window is active (has focus).

windowState.animating: read-write property for the window orientation animation.

windowState.viewMode: returns the current view mode, WindowState.Fullsize for full-

screen andWindowState.Thumbnail for thumbnail modes.

windowState.viewModeString: returns the current view mode as a string, Fullsize for

full-size and Thumbnailfor thumbnail modes.


20

The following diagram illustrates application states.

Figure 2.4 Qt Application Life Cycle


21

bada UI Structure

The basic layers that make up the bada UI are Frames, Forms and Controls. The Frame can thought of as

the application’s top-level window. A bada application will only have one Frame and it is a container for

the application’s Forms. Into this Frame, the multiple views of the application, realized through forms,

are associated. Forms are visible to the user whereas the application Frame is not. Multiple Forms can

be associated with the application’s Frame, but only one can be current and visible at any one time. A

Form can have a number of controls associated with it. Controls, similar to Qt’s widgets, are the visual

elements that user will interact in order to use and control the application. The following diagram

illustrates these concepts.

Figure 2.5 bada Application UI Structure

You should not delete controls that get added to a container (ie a Form of the application), the

framework does that for you.


22

Qt UI Structure

The basic Qt UI structure consists of the following elements:

Window

Provides a component that is normally the application's root component and handles transitions

when the user rotates the screen.

StatusBar

The StatusBar shows important information of the device state such as network type, signal

strength, and battery level.

ToolBar

Provides a container for accessing quickly to commonly used actions.

PageStack

A Page component serves as a container for other QML content. A page may contain additional

components such as TextEdit or Button components. The PageStack component allows for

multiple pages of an application to be managed in the form of a stack. Pushing a page to the

stack will make the page visible to the user. Also, it destroys the page instance when the page is

popped from the stack. This means you don't have to worry about memory management since it

is all handled by the page stack.

In Qt, Qt Quick consists of a rich set of user interface elements, a declarative language for describing

user interfaces, and a language runtime. A collection of C++ APIs is used to integrate these high level

features with classic Qt applications. Version 2.1 of the Qt Creator integrated development environment

(IDE) introduces tools for developing Qt Quick applications.

The QML Language

QML is a high level, scripted language. Its commands, more correctly elements, leverage the power and

efficiency of the Qt libraries to make easy to use commands that perform intuitive functions. Drawing a

rectangle, displaying an image, and application events -- all are possible with declarative programming.

A QML element usually has various properties that help define the element. For example, if we created

an element called Circle then the radius of the circle would be a property.

While QML does not require Qt knowledge to use, if you are already familiar with Qt, much of your

knowledge is directly relevant to learning and using QML. Of course, an application with a UI defined in

QML also uses Qt for all the non-UI logic.


23

For example, to add common navigation controls to a Qt application, such as those seen below;

Figure 2.6 Qt UI Navigation Controls

This could be defined in QML with the following;

Of particular note is how events can be managed from within QML. Selection of the ‘back’ toolbar

button will invoke the calling Qt.quit() causing the application to quit. How bada gets events from user

interactions such as button selections is discussed in the following event management section.

ToolBar {

id: toolBar

anchors { bottom: parent.bottom }

opacity: !inputContext.visible

Behavior on opacity { PropertyAnimation { duration: 200 } }

tools: ToolBarLayout {

ToolButton { iconSource: "toolbar-back"; onClicked: Qt.quit() }

ButtonRow {

exclusive: false

ToolButton { iconSource: "toolbar-previous" }

ToolButton { iconSource: "toolbar-share" }

ToolButton { iconSource: "toolbar-delete" }

ToolButton { iconSource: "toolbar-next" }

}

}

}


24

Event Management

Control Event Reporting

All events in bada are managed asynchronously and there is a tight coupling between the object

requiring the event and the interface that implements the processing of the event. Essentially, an object

must implement the interfaces that describe the events they wish to receive. bada uses the C++

mechanism of inheriting from a abstract class (the interface) in which all the ‘event’ methods are pure

virtual. It is the responsibility of the application programmer to implement these pure virtual methods

and in doing so, they are called by the application frame work, when the event occurs.

So for example, if we have a form on which there is a button and we need to know when the button is

clicked, we need to know the following:

What interface class implements this event

o IActionEventListener

What pure virtual method in this interface class informs of the event occurring

o OnActionPerformed

Inherit the interface class and override the pure virtual methods

So what does this look like…..

class ButtonForm :

public IActionEventListener

{

public:

ButtonForm(void);

virtual ~ButtonForm(void);

bool Initialize(void);

protected:

static const int ID_BUTTON_ON = 101;

public:

virtual result OnInitializing(void);

virtual void OnActionPerformed(const Osp::Ui::Control& source, int

actionId);

};


25

In the class definition above, ButtonForm is a form that will contain a button and will receive an event

when the button is selected. Let’s break it down:

class ButtonForm : public IActionEventListener

This line states that when we create an instance of the ButtonForm class, it’s this ButtonForm class that

will implement the IActionEventListener interface. The IActionEventListener interface consists of one

method to override and this is listed a public method of the ButtonForm class. This is shown as

public: virtual void OnActionPerformed(const Osp::Ui::Control& source, int actionId);

We might have more than one button on our form. To uniquely identify which button has been

selected, we can assign an ‘action ID’ to a specific button. This allows us to check in the

OnActionPerformed method which button was selected. In our class definition we have defined an

action ID ID_BUTTON_ON which we could assign to a specific button instance in the following manner

pButtonOn->SetActionId(ID_BUTTON_ON);

When this button is selected the OnActionPerformed method is called and we use the actionId to

identify which button is clicked:

void

ButtonForm::OnActionPerformed(const Control& source, int actionId)

{

switch (actionId)

{

case ID_BUTTON_ON:

__pLabelButton->SetText(L"Button ON Clicked!");

break;

case ID_BUTTON_OFF:

__pLabelButton->SetText(L"Button OFF Clicked!");

break;

default:

break;

}

__pLabelButton->Draw();

__pLabelButton->Show();

}


26

In Qt, this coupling between an object’s instance and its interface is not so strong. In fact in Qt, any

object wishing to receive an event simply has to connect its ‘slot’ to the ‘signal’ emitted when the event

is caused. Any slot can connect to any signal providing their signatures (prototype match).

Figure 2.7 Qt Signals and Slots Event Mechanism

The signals and slots mechanism is type safe: The signature of a signal must match the signature of the

receiving slot. (In fact a slot may have a shorter signature than the signal it receives because it can

ignore extra arguments.)

A class which emits a signal neither knows nor cares which slots receive the signal. Qt's signals and slots

mechanism ensures that if you connect a signal to a slot, the slot will be called with the signal's

parameters at the right time. Signals and slots can take any number of arguments of any type. They are

completely type safe. Signals are emitted by objects when they change their state in a way that may be

interesting to other objects. This is all the object does to communicate.

Slots can be used for receiving signals, but they are also normal member functions. Just as an object

does not know if anything receives its signals, a slot does not know if it has any signals connected to it.


27

All classes that contain signals or slots must mention Q_OBJECT at the top of their declaration. They

must also derive (directly or indirectly) from QObject. Defining a class that makes use of signals and slots

would take the following form:

In the following code snippet, we create two Counter objects and connect the first object's

valueChanged() signal to the second object's setValue() slot using QObject::connect():

Whereas the bada method is polymorphic, the Qt mechanism is about encapsulation.

#include <QObject>

class Counter : public QObject

{

Q_OBJECT

public:

Counter() { m_value = 0; }

int value() const { return m_value; }

public slots:

void setValue(int value);

signals:

void valueChanged(int newValue);

private: int m_value;

};

Counter a, b;

QObject::connect(&a, SIGNAL(valueChanged(int)), &b, SLOT(setValue(int)));

a.setValue(12); // a.value() == 12, b.value() == 12

b.setValue(48); // a.value() == 12, b.value() == 48


28

Inter-Object event communication

The preceding section explained how bada manages the reporting of events associated with controls

that they interact with. This section will explain inter-object event communication- how an object can

asynchronously pass information to another object.

In Qt, events are objects, derived from the abstract QEvent class, that represent things that have

happened either within an application or as a result of outside activity that the application needs to

know about. Events can be received and handled by any instance of a QObject subclass. When an event

occurs, Qt creates an event object to represent it by constructing an instance of the

appropriate QEvent subclass, and delivers it to a particular instance of QObject (or one of its subclasses)

by calling its event() function.

These objects can re-implement QObject::event(), the general event handler, and either do their event

handling before or after the usual handling, or they can replace the function completely. The following

code snipped illustrates this:

bool MyWidget::event(QEvent *event)

{

if (event->type() == QEvent::KeyPress) {

QKeyEvent *ke = static_cast<QKeyEvent *>(event);

if (ke->key() == Qt::Key_Tab) {

// special tab handling here

return true;

}

} else if (event->type() == MyCustomEventType) {

MyCustomEvent *myEvent = static_cast<MyCustomEvent *>(event);

// custom event handling here

return true;

}

return QWidget::event(event);

}

http://doc.qt.nokia.com/4.7/qevent.html

http://doc.qt.nokia.com/4.7/qobject.html

http://doc.qt.nokia.com/4.7/qevent.html

http://doc.qt.nokia.com/4.7/qobject.html

http://doc.qt.nokia.com/4.7/qobject.html#event


29

bada has two APIs that can used for general event sending and receiving respectively. They are

SendUserEvent() and OnUserEventReceived(). These APIs can allow for simple asynchronous data

exchange between Forms and Controls.

Their full prototypes are given as follows;

result SendUserEvent (RequestId requestId, const Osp::Base::Collection::IList *pArgs)

virtual void OnUserEventReceivedN (RequestId requestId, Osp::Base::Collection::IList

*pArgs)

If a given handle (pointer) to a form exists, it is possible to call SendUserEvent() on this handle to

asynchronously send an event containing data to this form. The form, will handle the reception of this

event within its own implementation of OnUserEventReceived. Even though both prototypes define the

IList type as the format of the events payload, this heap allocated pointer could type cast to some

custom type if required. The following illustration explains how inter-form event sending could take

place:


30

class FormA: public Form

{

int x;

public:

….

….

};

class FormB: public Form

{

int y;

public:

….

….

};

result MyClass::eventHandling(void)

{

result r;

FormA *pFormA = null;

pFormA = new FormA();

if (pFormA)

{

r = pFormA->SendUserEvent(FormA::ID1, null);

if (IsFailied(r))

{

}

}

return r;

}

void

FormA::OnUserEventReceived(RequestId requestId, Osp::Base::Collection::IList

*pArgs)

{

FormB *pFormB;

switch (requestId)

{

case ID1:

// some handling here

……..

……..

pFormB->SendUserEvent(FormB::ID3, null);

break;

default:

break;

}

}


31

Class Mapping

The following table maps the most important classes in both platforms so that the developer can gain an

idea of where to start looking to find equivalent functionality. To make this mapping simple, Qt classes

will be mapped on grouped functionality as its classes are not grouped into namespaces like bada. As

the focus here is mobile, and large amounts of functionality is contained within the Qt Mobility Project

API, the specific areas will be listed. The QtMobility project covers a diverse range of features and

technologies. It is not a single API but a collection of APIs and frameworks.

Qt Class Group bada namespace (Class)

QApplication

Application invocation and management of

resources. Manages the main event loop and

event handling

Osp::App::Application

Handles basic application fundamentals like

application launch, system events, state transitions

(background/foreground) and data management

(registry).

QGL Osp::Graphics, Osp::Graphics::Opengl

bada &Qt:

Supports the integration of the OpenGL 2.0 library into the platform.

Qt Mobility (Location API) Osp::Locations

bada &Qt:

Provides methods for obtaining location, positioning, landmark management and mapping.

Qt Mobility (Connectivity API)

Local device connectivity such as Bluetooth and

NFC.

Osp::Net (Bluetooth, WiFi, NFC etc)

All data communication such as Bluetooth, NFC,

HTTP, Sockets and WiFi. Data connections and

account management are also managed here.


32

Qt Mobility (Telephony Events API)

Provides access to telephony events, services and

call notifications and call states (in-progress, on

hold, terminating)

Osp::Telephony

Accessing the type and status of a current call.

Receiving notifications on network status and

accessing the SIM

QLayout, QWidget, QLabel etc

Supports the creation of user accessible widgets,

labels. Provides control on their layout and

position.

Osp::UI

Allows for the creation of user accessible controls

such as buttons, check-boxes and lists. Many

controls exist and users specifies how their layout

within a form.

QThread

Creates a separate thread of control that can share

data with other processes but executes

independently.

Osp::Base::Runtime

Supports fixed period timers,

synchonisationsynchronization using mutexes,

semaphores and monitors. Sequential execution

using threads.

Qt Mobility (Messaging API)

Enables access to messaging services such as

search, sort and send. Message composition and

message response

Osp::Messaging

Allows for the creation and sending of SMS, MMS

and Email message types. Services to search

messages and register for PUSH messaging.

Qt Mobility (Multimedia API)

Allows for the playing, recording and streaming of

media content.

Osp::Media

Supports the encoding and decoding of images.

Recording and playback of both audio and video.

Capturing PCM data and handling DRM.

Qt Mobility (Contacts API) Osp::Social::Record


33

Access (read/write) contact data and associated

meta data

ProviesProvides the ability to search, create,

read/write contact information

Qt Mobility (Sensors API)

Manages the registration, availability and data

received from of sensors such as the

accelerometer, light sensor, compass, rotation and

proximity sensors.

Osp::Uix

Provides access to a device’ss sensors

(accelerometer, magnetic, proximity and tilt). In

addition haptic effects, face detection and speech

recognition are supported.


34

Part 3.

A practical comparison To show the practical differences between bada and Qt, we’ve provided a simple example from the Qt

SDK and created its bada equivalent. You can download both samples as a .zip file at the end of this

document. This is a good way to compare bada and Qt at a code level.

The example is a simple battery indicator which uses a progress bar to show the available battery of the

device.

Figure 3.1 Qt Creator Example Application

To create the Qt version of the application, we used the ‘Creating the Battery Indicator Project’ guide

from the Qt Creator help.


35

There are a number of key areas in Qt illustrated in this process:

Application wizard – Creating the application

Graphical UI design – Qt Designer

Asynchronous event handling – Signals and slots

Simulated Testing – Simulator and simulator control

Figure 3.2 Qt Application Execution and Testing with Simulator


36

A bada equivalent of this simple application has been created using:

Application wizard – creating application

Graphical UI design - UI Builder

Asynchronous event handling - Event Listeners to get battery change events

Simulated testing using emulator and Event injector

Figure 3.3 bada Application Execution and Testing with Emulator

Documents

bada for Qt developers by Keith Bauwisestatic.bada.com/contents/blog/20120130/Complete(v1.2).KB.pdf · bada for Qt developers 2 ... read-write property for the window orientation