badatutorial.application[1]

8/8/2019 BadaTutorial.application[1]

1/42

Copyright 2010 Samsung Electronics Co., Ltd. All rights reserved. 1

bada 1.1.0Copyright 2010 Samsung Electronics Co., Ltd. All rights reserved.

bada Tutorial:

Application


2/42


Contents (1/2)

Essential Classes

Relationships between Classes

Overview

bada Applications

Application Model

Launching Applications Terminating Applications

Application State Transition

Application Life-cycle

Foreground and Background

System Events

Application Framework

Internationalization

Launching Other Applications


3/42


Contents (2/2)

AppControl

Application Control ID

Operation ID

Getting an AppControl

AppControl Examples

Examples: Create an Application

Save and Restore Application Settings

Handle Screen Events

Use Sign-In Application Control

Launch Other Applications and Handle Launch Arguments FAQ


4/42


Feature Provided by

Provides an interface to the application frame. IAppFrame

Provides a listener for AppControl. IAppControlEventListener

Feature Provided by

Provides the base class to create applications. It initializes and terminates the application,and also provides handlers for system events.

Application

Provides localized application string resources. AppResource

Provides a repository to save and load user applications state and context. AppRegistry

Provides application launching mechanism to use other application control features. AppControl

Finds the specific application control. AppManager

Essential Classes

Interfaces

Major classes


5/42


Relationships between Classes

AppManager

FindAppControl()

AppControl

Start()

ApplicationIAppControlEventListener

OnAppControlCompleted()

IAppFrame

AppRegistry

AppResource

Note: This is an externalclass created by the

developer.It does not belong to the

App namespace.

MyApplication


6/42


Overview

The App namespace contains classes and interfaces that providethe foundations for developing bada applications.

Key features include:

Application framework.

Background and foreground event handling.

Application Control.


7/42Copyright 2010 Samsung Electronics Co., Ltd. All rights reserved. 7

bada Applications

The application framework provides:

Application life-cycle management:

Initialization and termination

Background and foreground handling

Event handling:

Battery and memory events

Application control:

Dial, contact, browser, media,and messaging

Operating System


Your Application



Application Model (1/2)

In the bada platform, there are two application types:

Base applications:

Stored in the ROM and not removable via the Application manager.

For example, Dialer, Contact, Camera, and Music player.

bada applications:

Installable and removable applications.

In this document, the word application refers to a bada application.



Application Model (2/2)

A bada application running in the foreground is sent to thebackground when base applications are launched, for examplewhen receiving an incoming voice call or user switching to homescreen.

An application can utilize various device platform features providedby application controls through the AppControl class.

bada platform task management

Only one bada application can run at a time.

If a bada application is already running when launching another badaapplication, the first is always terminated by the platform.

One bada application can run simultaneously with multiple base

applications. Multi-tasking is available between a bada application and base applications.



Launching Applications

An application is launched when the user clicks the icon in the main menu.

The system loads the necessary libraries and application executable binaryto the memory.

The applications entry point (OspMain()) creates an instance of theapplication and executes it.

In the application initialization phase (OnAppInitializing()), resources,UI components, and previous application states can be loaded or initialized.

ApplicationMain menu

int OspMain()



Terminating Applications (1/2)

The application closes for one of 2 reasons:

1. When the bada application itself calls theApplication::Terminate() method, the application is terminated.

2. When the application is in the foreground, the user pressing the Endkey terminates the application.

The system forces the application to shut down:

1. If a second application launches while the first is running, the firstapplication is terminated. All bada applications follow a single badaapplication policy, so only one bada application can run at a time.

2. When memory or battery power is extremely low, the system terminatesthe application.



Terminating Applications (2/2)

Application termination tasks must be handled in theOnAppTerminating() method, which is called when the applicationterminates. When terminating:

The application must close quickly.

The application must free the resources it has been using to avoidmemory leakage.

The allocated UI control objects, such as the Frame, Form, and their childcontrols, are released before the OnAppTerminating() method is called.They are not accessible from within the OnAppTerminating() method.

The application must close all pending connections to servers.

The application can save its own state or context throughAppRegistry. For instance, when the application is launched, it can

resume from the last form from the previous execution. The forcedTermination argument specifies that the application is

being terminated by the system. It is:

True, when the application is forced to terminate, for example due to secondbada application launching, low battery, or other system interruptions.False, when the termination is initiated by the user by pressing the End key,

by the application calling Terminate() itself or by closing from Task Manager.



Application State Transition (1/2)

Applications have the following states with corresponding event

handlers:

Initializing

Application framework initializes the application and creates the applications

frame.

If the OnAppInitializing() method returns false, application state

changes to Terminating and it exits. If the OnAppInitializing() returns true, the application framework

proceeds to Running state.

Running

Terminating

The application exits the event loop and frees its own resources.



Application State Transition (2/2)

Terminated

It releases the control of the flow to the system.

- Application destroyed.

- Register application context in thesystem.

- Create the application frame .

- Call the applicationsOnAppInitializing() method.

Initializing

Initializationsucceeds

Initialization fails

Termination

- Exit event loop.- Call the applicationsOnAppTerminating()

method.

- Destroy allocated resources.

- Process events.

Create

Running

Terminating

Terminated



Application Life-cycle

The diagram illustrates where

the application state eventsoccur in terms of the applicationlife-cycle.

Application life-cycle

OnAppInitializing()

OnForeground()

Running OnBackground()

OnAppTerminating()

Another windowcomes to theforeground

(for example, a

system popup oranother application)

ApplicationLaunch

Application comes tothe foreground

ApplicationExit

Showing splash image

Hiding splash image

Termination



Foreground and Background (1/3)

Foreground:

Applications are visible when they are in the foreground.

When an application is first launched, the OnForeground()method is

called.

An application is brought to the foreground from the background when:

The application is selected from the Task Manager.

The application icon is selected in the main menu.

When the application is brought to the foreground:

Resume graphics processing (3D or animation) since the application nowhas focus.

Resume the operations which were stopped when the application was lastmoved to the background.

When the system needs to refresh a screen component, it can call theOnForeground()method even if the application is present in the

foreground.


17/42



Background:

Applications are not visible when they are in the background.

An application moves to the background when :

The Home key is pressed.

Other windows pop up, such as windows for incoming calls and alarms.

When the application is sent to the background:

Stop graphics processing (3D, animation, etc.) since they will not bedisplayed anyway.

Release unnecessary resources.

Stop media processing, haptic and sensors manipulations.

-OnBackground() is called-OnForeground() is calledForeground

- Home key pressed- Other windows pop up

-Selected from Task manager- Icon pressed in the main menu

Background


18/42



The following diagram illustrates the various events and states from

the application and the application frameworks perspective.


19/42


System Events (1/3)

System events must be properly handled by the Application class event

handlers:

Battery event: Applications that use multimedia resources, such as thecamera and media player, need to check the battery level in theOnBatteryLevelChanged() event handler:

If the level is EMPTY, terminate the application.

If the level is CRITICAL, stop using multimedia features, since they are notguaranteed to function properly at this battery level.

Memory event: When memory is low, the OnLowMemory() event

handler is called. Free unused memory from the heap in this eventhandler.


20/42


System Events (2/3)

Screen event:

Applications can receive screen events in OnScreenOn() and OnScreenOff()

event handlers if they register a screen event listener. When theOnScreenOff() event handler is triggered, the application must reduce power

consumption by releasing the activated resources, such as 3D, multimedia, andsensors, which are no longer used. The released resources can be acquiredagain when the OnScreenOn() event handler is triggered.

The resources must be handled efficiently by the OnForeground()/OnBackground() and OnScreenOn()/OnScreenOff() event handlers.

Be careful not to duplicate or delete resources.

When the device is in auto lock mode, OnBackground()is called directlyafter OnScreenOff().

The following events are triggered when the backlight time expires:

OnScreenOff() If device is in auto lock mode, OnBackground() is called after OnScreenOff()when

the lock UI is displayed.


21/42


System Events (3/3)

The following events are triggered when the unlock key is pressed.

If the touch lock is enabled, OnScreenOn() is triggered. OnForeground() is called after the lock UI disappears.

When the lock key is pressed explicitly, only OnBackground() is calledafter the lock UI is displayed. When the backlight turns off, OnScreenOff() is

called.


22/42



Application:

All applications must derive from

Application class

AppManager:

Application manager class

Finds an AppControl instance IAppFrame:

UI frame interface

Frame is the main window in an application

AppResource:

Application resource class

Can contain localized strings

AppControl:

Application control class

Used to start an application and control specific behavior.

AppControl

IAppFrame

AppManagerApplication

AppRegistry

AppResource


23/42


Internationalization (1/2)

String resource is supported for multiple languages.

Each localized string is saved to each xml file in Res folder. For example: eng-GB.xml, fra-FR.xml, ita-IT.xml,

deu-DE.xml, kor-KR.xml

[IDE String Resource]

AppResource handles localized string resource based on preferred

display language that is defined in the device settings.

AppResource

eng-GB.xml

Hello

Your App

Menu Back

Form

Language Setting


24/42


Internationalization (2/2)

Retrieving localized strings

1. Prepare the localized strings table with the UI Builder. For moreinformation, see Using String Tables in the Development Environmenttutorial.

2. Get the localized string from the AppResource class.AppResource retrieves the chosen language from the display

language settings and returns the localized strings.

AppResource::GetString(const String& id, String&

loadedString)

Application* pApp = Application::GetInstance();

String str1;r = pApp->GetAppResource()->GetString("IDS_STRING1", str1);


25/42


Launching Other Applications

A bada application can launch other applications using the

AppManager::LaunchApplication()method.

The AppManager::LaunchApplication() method requires theSYSTEM privilege level, and to use the method, you must assign theAPP_SERVICE privilege group to your application.

All bada applications follow the single application policy. Therefore,the OnAppTerminating() method is called immediately after theLaunchApplication() method, and the calling application is

terminated.

You can retrieve the launch arguments from an application by usingthe Application::OnUserEventReceivedN() method. For

more information, see the API Reference.


26/42


AppControl (1/2)

AppControl is a standard mechanism for using specific

operations exported by base applications

AppControl can communicate data and get back results.

AppControl instance can be created from the AppManager.

AppManager finds the service providing application control and

returns it for your application to use. AppControls can be identified using 2 parameters:

Application Control ID:

Defines the variable for identifying each application control instance. Forexample, APPCONTROL_DIAL.

Operation ID:

Defines the variable for identifying the behavior of each application controlinstance. For example, OPERATION_VIEW.


27/42


AppControl (2/2)

The result of the application controls execution is returned by

IAppControlEventListeners OnAppControlCompleted()method.

OnAppControlCompleted() is invoked when an application finishes

its operation and a control callback event occurs.

Some AppControls require privileges to use them:

For example, Call and Browser requires Normal privilege.


28/42


29/42


AppControl name Operation ID Description

APPCONTROL_SIGNIN OPERATION_SIGNIN This operation can be used to sign in to the bada Server. After the user has

signed in for the first time, this operation handles all subsequent sign-ins

automatically. Using this AppControl requires special privileges.

OPERATION_SIGNOUT This operation can be used to sign out from the bada Server. This operation

signs out without displaying any dialog. Using this AppControl requires

special privileges.

APPCONTROL_CAMERA OPERATION_CAPTURE This operation can be used to launch the Camera UI to capture images or

record video.APPCONTROL_MESSAGE OPERATION_EDIT This operation can be used to compose SMS or MMS messages. The

parameters passed to this application control are automatically filled in the

appropriate fields in the displayed message composer.

APPCONTROL_EMAIL OPERATION_EDIT This operation can be used to compose email messages. The parameters

passed to this application control are automatically filled in the appropriate

fields in the displayed message composer.

APPCOTNROL_BT OPERATION_PICK This operation can be used to obtain the details of a Bluetooth profile on the

device.

APPCONTROL_MEDIA OPERATION_PICK This operation can be used to select one or more media files , such as

images or video recordings, from the My Files folder.

APPCONTROL_IMAGE OPERATION_VIEW This operation can be used to view image files on the device.

APPCONTROL_VIDEO OPERATION_PLAY This operation can be used to play video files on the device.

APPCONTROL_AUDIO OPERATION_PLAY This operation can be used to play audio files on the device.

Application Control ID (2/2)


30/42


Operation ID

Operations specify the specific behavior or action that must be

performed.

Operation ID Description

OPERATION_ADD Adds an item or content to a specific AppControl.

OPERATION_CAPTURE Captures an item or content in a specific AppControl.

OPERATION_EDIT Edits an item or content in a specific AppControl.

OPERATION_DEFAULT Launches the AppControl without any operation.

OPERATION_PICK Obtains data from a specific AppControl.

OPERATION_PLAY Plays an item or content in a specific AppControl.

OPERATION_VIEW Displays an item or content in a specific AppControl.

OPERATION_SIGNIN Displays a sign-in window.

OPERATION_SIGNOUT Signs out of a session.


31/42


Getting an AppControl

badaApplication

AppControlsRegistry

AppControl

AppManager

[AppControl Resolver]

#Dialtype=

Path=

#Browsertype=

Path=

#SignIntype=

Path=

type=

Path=

#Videotype=

Path=

Base Application(For example, Contact)

AppControl

4. Launch the application AppControlID and operation ID.

2 Resolve the AppControl ID and operation ID.

1. Find AppControl.

IAppControlEventListener

OnAppControlCompleted()

5. Asynchronously send result to

AppControl event listener.

3. Start AppControl.


32/42


MediaApplication

AppControl Examples

APPCONTROL_MEDIA:

Launches the mediaapplication to select audio,video, or image content fromthe Media folder.

Receives selections in an

event handler.

CallerApplication

AppControl ID: APPCONTROL_MEDIAOperation ID: OPERATION_PICKOption: type:video

selectionType:single

The calling application receives information of theselected media, i.e. URI.

Caller

Application

Dialer

Application

AppControl ID: APPCONTROL_DIALOperation ID: NONEOption: tel:+82312798707

APPCONTROL_DIAL:

Launches the dialerapplication with a pre-filledphone number.

Requires normal privilege.


33/42


Example: Create an Application (1/2)

This example illustrates how application default methods are created.

Open \\Examples\UIApplication\src\HelloWorld.cpp.

1. Create the HelloWorld application code using the Frame BasedApplication template.


34/42


Example: Create an Application (2/2)

Notes

Applications must derive from the Application class.

You must create and download your applications manifest.xml file from

bada Developers. In addition to the information above (name, ID, secretcode), it contains other information necessary for your application, suchas privileges and device profiles.

Application NameGetAppName()

Application IDGetAppId()

Secret Code

GetAppSecret()

Manifest.xml

Application

MyApplication


35/42


Example: Save and Restore Application Settings(1/2)Save and restore application state.

1. In the OnAppInitializing() method, use AppRegistry to

retrieve application settings:AppRegistry::Get(key, value)

2. The first time an application runs, the registry entry must be added:

AppRegistry::Add(key, value)3. Save application settings to disk in the registry:

AppRegistry::Save()

4. Set registry values in the OnAppTerminating() event handler:

AppRegistry::Set(key, value)

l d l


36/42


Example: Save and Restore Application Settings(2/2)

bool MyApplication::OnAppTerminating(AppRegistry&

appRegistry)

{

result r = E_SUCCESS;

r = appRegistry.Set("LastMessage", "Who destroyed");

//enum { INIT=0, PLAYING, SCORE } GameStatus =

PLAYING;

appRegistry.Set("GameStatus", (int)GameStatus);

appRegistry.Save();

}

bool MyApplication::OnAppInitializing(AppRegistry&

appRegistry)

{

String message("NONE");

r = appRegistry.Get("LastMessage", message);

if(r == E_KEY_NOT_FOUND

{

appRegistry.Add("LastMessage", message);}

// Enumeration definitions are defined

elsewhere.

// enum { INIT=0, PLAYING, SCORE } GameStatus

= INIT;

int gamestatus = GameStatus;

r = appRegistry.Get("GameStatus", gamestatus);

if(r == E_KEY_NOT_FOUND

{

appRegistry.Add("GameStatus", gamestatus);

}

appRegistry.Save();

}


37/42


This example illustrates how to

handle a sound resource duringscreen on and screen off events.You can handle other resourcesin the same way.

1. Implement theScreenEventListener to

handle screen events.2. Check the sound status

using the boolean value ofthe IsPlaying variable.

3. Play or stop the sound usingPlaySound()orStopSound() accordingly.

Example: Handle Screen Events

bool MyApplication::OnAppInitializing(AppRegistry&

appRegistry){

PowerManager::SetScreenEventListener(*this);

}

void MyApplication::OnScreenOn (void)

{

// Check if sound is off, then turn on sound.

if(!IsPlaying)

PlaySound();}

void MyApplication::OnScreenOff (void)

{

if(IsPlaying)

StopSound();

}

void MyApplication::OnForeground()

{

if(!IsPlaying)

PlaySound();

}

void MyApplicaiton::OnBackground()

{

if(IsPlaying)

StopSound();

}


38/42


Example: Use Sign-In Application Control

1. Get an AppControl instance by calling the FindAppControlN()

method. Provide the SignIn Control ID as parameter:AppManager::FindAppControlN(APPCONTROL_SIGNIN,

OPERATION_SIGNIN)

2. If the FindAppControlN() method returns an AppControl instance,start the AppControl by calling its Start() method:AppControl::Start(null, this)

Notes:

If you require event handlers, implement anIAppControlEventListener .

AppControl* pAc = AppManager::FindAppControlN(APPCONTROL_SIGNIN, OPERATION_SIGNIN);if(pAc != null)

{pAc->Start(null, this);

delete pAc;

}

elseAppLog("AppControl Not Found. \n");


39/42


Example: Launch Other Applications and HandleLaunch Arguments (1/2)

This example illustrates how to launch other applications from a bada

application and retrieve the launch arguments.

1. A caller application launches another application with argumentsusing the LaunchApplication() method.

2. The OnAppTerminating()method is called, terminating the caller

application.

3. The called application is launched. If the launch arguments exist,requestId is assigned as a reserved launch ID(AppLaunchRequestId).

l h h l d dl


40/42


Example: Launch Other Applications and HandleLaunch Arguments (2/2)

AppId calleeAppId = L1234567890;

AppManager *pAppManager = AppManager::GetInstance();

ArrayList *pArgList = new ArrayList();

pArgList->Construct();

String *aArg = new String(Lyourdata);

pArgList->Add(*aArg);

r = pAppManager->LaunchApplication(calleeAppId, pArgList, AppManager::LAUNCH_OPTION_DEFAULT);

Caller application:

void CalleeApp::OnUserEventReceivedN (RequestId requestId, Osp::Base::Collection::IList *pArgs)

{

if(requestId == AppLaunchRequestId) // If launch arguments come

{

if(pArgs)

{

for(int i = 0; i < pArgs->GetCount(); i++)

AppLog("pData[%d]=%S", i, ((String*)(pArgs->GetAt(i)))->GetPointer());

// pArgs[0] represents the launch type (for example, APP_LAUNCH_NORMAL value)

// pArgs[1] represents the operation of the launch (default value is OPERATION_DEFAULT).

// pAgrs[>=2] contains the actual arguments sent from the caller (for example, yourdata)

}

else // Handling User Events

Called application:


41/42


FAQ

Where do I initialize and free-up application resources?

Initialize them in the OnAppInitializing()method.

Free non UI resources in the OnAppTerminating()method, but UI

resources(e.g. form and its child controls) is freed automatically whenthe application closed. You do not need to free them explicitly.Please review the UI parts of this document about UI resource.

Do I have to set my applications ID somewhere? No, an application ID (a unique identifier bound to a bada application) is

created from the bada developer site and saved into the applicationmanifest file (manifest.xml).The bada IDE does not automatically generate the GetAppId(),GetAppName(), and GetAppSecret()methods, since they are

member methods of the Application class.


42/42

badatutorial.application[1]

Documents