bada Tutorial: Application

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

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
Copyright © 2010 Samsung Electronics Co., Ltd. All rights reserved. 2

Contents (2/2)
• AppControl
– – – – – – – – – Application Control ID Operation ID Getting an AppControl AppControl Examples Create an Application Save and Restore Application Settings Handle Screen Events Use Sign-In Application Control Launch Other Applications and Handle Launch Arguments

• Examples:

• FAQ

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

3

Essential Classes
• Major classes
Feature Provided by Application AppResource AppRegistry AppControl AppManager

Provides the base class to create applications. It initializes and terminates the application, and also provides handlers for system events.
Provides localized application string resources. Provides a repository to save and load user application‟s state and context. Provides application launching mechanism to use other application control features. Finds the specific application control.

Interfaces
Feature Provided by IAppFrame IAppControlEventListener

Provides an interface to the application frame. Provides a listener for AppControl.

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

4

Ltd. 5 .Relationships between Classes <<interface>> IAppControlEventListener AppManager Application <<interface>> IAppFrame OnAppControlCompleted() FindAppControl() AppControl AppRegistry Start() MyApplication AppResource Note: This is an external class created by the developer. Copyright © 2010 Samsung Electronics Co. It does not belong to the App namespace. All rights reserved..

Copyright © 2010 Samsung Electronics Co. – Application Control. – Background and foreground event handling.. Ltd. All rights reserved. • Key features include: – Application framework.Overview • The App namespace contains classes and interfaces that provide the foundations for developing bada applications. 6 .

media. browser.bada Applications The application framework provides: – Application life-cycle management: • Initialization and termination • Background and foreground handling – Event handling: • Battery and memory events Your Application Application Framework – Application control: • Dial. All rights reserved. contact. 7 .. and messaging Operating System Copyright © 2010 Samsung Electronics Co. Ltd.

All rights reserved. Contact. • For example. Camera. the word “application” refers to a bada application. Dialer. and Music player. • In this document.Application Model (1/2) In the bada platform. Copyright © 2010 Samsung Electronics Co. Ltd.. – bada applications: • Installable and removable applications. there are two application types: – Base applications: • Stored in the ROM and not removable via the Application manager. 8 .

. • An application can utilize various device platform features provided by application controls through the AppControl class. • bada platform task management • Only one bada application can run at a time. 9 . – If a bada application is already running when launching another bada application. All rights reserved. Ltd. – Multi-tasking is available between a bada application and base applications. • One bada application can run simultaneously with multiple base applications. the first is always terminated by the platform. for example when receiving an incoming voice call or user switching to home screen.Application Model (2/2) • A bada application running in the foreground is sent to the background when base applications are launched. Copyright © 2010 Samsung Electronics Co.

10 . Main menu Application int OspMain() Copyright © 2010 Samsung Electronics Co. The application‟s entry point (OspMain()) creates an instance of the application and executes it. In the application initialization phase (OnAppInitializing()).. All rights reserved. The system loads the necessary libraries and application executable binary to the memory. Ltd.Launching Applications • • • • An application is launched when the user clicks the icon in the main menu. UI components. resources. and previous application states can be loaded or initialized.

If a second application launches while the first is running. When the bada application itself calls the Application::Terminate() method. the user pressing the End key terminates the application. When memory or battery power is extremely low. 2. • The system forces the application to shut down: 1.. 2. Ltd. 11 . the application is terminated. so only one bada application can run at a time. All bada applications follow a single bada application policy. Copyright © 2010 Samsung Electronics Co.Terminating Applications (1/2) • The application closes for one of 2 reasons: 1. the first application is terminated. the system terminates the application. All rights reserved. When the application is in the foreground.

When terminating: – The application must close quickly. or other system interruptions. which is called when the application terminates. such as the Frame. it can resume from the last form from the previous execution. All rights reserved. and their child controls. – The application can save its own state or context through AppRegistry. It is: • True. are released before the OnAppTerminating() method is called. False.Terminating Applications (2/2) Application termination tasks must be handled in the OnAppTerminating() method. – The application must close all pending connections to servers. by the application calling Terminate() itself or by closing from Task Manager. Ltd.. when the termination is initiated by the user by pressing the End key. Copyright © 2010 Samsung Electronics Co. – The application must free the resources it has been using to avoid memory leakage. for example due to second bada application launching. when the application is launched. – The forcedTermination argument specifies that the application is being terminated by the system. They are not accessible from within the OnAppTerminating() method. Form. For instance. when the application is forced to terminate. • The allocated UI control objects. 12 . low battery.

the application framework proceeds to „Running‟ state.. Ltd. • If the OnAppInitializing() returns true. – Running – Terminating • The application exits the event loop and frees its own resources. Copyright © 2010 Samsung Electronics Co. All rights reserved.Application State Transition (1/2) Applications have the following states with corresponding event handlers: – Initializing • Application framework initializes the application and creates the application‟s frame. application state changes to „Terminating‟ and it exits. 13 . • If the OnAppInitializing() method returns false.

. .Call the application‟s OnAppTerminating() method. . . .Create the application frame .Destroy allocated resources.. 14 .Application destroyed.Process events. All rights reserved. Terminated Copyright © 2010 Samsung Electronics Co.Application State Transition (2/2) – Terminated • It releases the control of the flow to the system.Register application context in the system.Exit event loop.Call the application‟s OnAppInitializing() method. Initialization succeeds Create Initializing Initialization fails Terminating Running Termination . . . Ltd.

15 . Application Launch Showing splash image Hiding splash image OnAppInitializing() Application comes to the foreground OnForeground() Running OnBackground() Another window comes to the foreground (for example. a system popup or another application) Termination OnAppTerminating() Application Exit Application life-cycle Copyright © 2010 Samsung Electronics Co. Ltd.Application Life-cycle The diagram illustrates where the application state events occur in terms of the application life-cycle.. All rights reserved.

• Resume the operations which were stopped when the application was last moved to the background. Ltd. Copyright © 2010 Samsung Electronics Co..Foreground and Background (1/3) Foreground: – Applications are visible when they are in the foreground. – When the application is brought to the foreground: • Resume graphics processing (3D or animation) since the application now has focus. it can call the OnForeground()method even if the application is present in the foreground. • The application icon is selected in the main menu. 16 . – An application is brought to the foreground from the background when: • The application is selected from the Task Manager. the OnForeground()method is called. All rights reserved. – When the system needs to refresh a screen component. – When an application is first launched.

OnBackground() is called -Selected from Task manager .. such as windows for incoming calls and alarms. • Stop media processing. All rights reserved. – An application moves to the background when : • The Home key is pressed. animation. Ltd. • Other windows pop up. haptic and sensors manipulations. .Icon pressed in the main menu Copyright © 2010 Samsung Electronics Co. 17 . • Release unnecessary resources.Home key pressed . – When the application is sent to the background: • Stop graphics processing (3D. etc.Foreground and Background (2/3) Background: – Applications are not visible when they are in the background.OnForeground() is called Foreground Background .) since they will not be displayed anyway.Other windows pop up .

Copyright © 2010 Samsung Electronics Co. 18 . All rights reserved.Foreground and Background (3/3) The following diagram illustrates the various events and states from the application and the application framework‟s perspective. Ltd..

such as the camera and media player. since they are not guaranteed to function properly at this battery level. Ltd. • Memory event: When memory is low. – If the level is CRITICAL. the OnLowMemory() event handler is called. 19 . All rights reserved..System Events (1/3) System events must be properly handled by the Application class event handlers: • Battery event: Applications that use multimedia resources. terminate the application. need to check the battery level in the OnBatteryLevelChanged() event handler: – If the level is EMPTY. stop using multimedia features. Copyright © 2010 Samsung Electronics Co. Free unused memory from the heap in this event handler.

. Be careful not to duplicate or delete resources. the application must reduce power consumption by releasing the activated resources. Ltd. and sensors. OnBackground() is called after OnScreenOff() when the lock UI is displayed. – The resources must be handled efficiently by the OnForeground()/ OnBackground() and OnScreenOn()/OnScreenOff() event handlers. – When the device is in auto lock mode. When the OnScreenOff() event handler is triggered. 20 . which are no longer used. The released resources can be acquired again when the OnScreenOn() event handler is triggered. – The following events are triggered when the backlight time expires: • OnScreenOff() • If device is in auto lock mode. such as 3D. multimedia. OnBackground()is called directly after OnScreenOff(). Copyright © 2010 Samsung Electronics Co.System Events (2/3) Screen event: – Applications can receive screen events in OnScreenOn() and OnScreenOff() event handlers if they register a screen event listener. All rights reserved.

System Events (3/3) – The following events are triggered when the unlock key is pressed. OnScreenOn() is triggered. Copyright © 2010 Samsung Electronics Co. When the backlight turns off. Ltd.. All rights reserved. 21 . only OnBackground() is called after the lock UI is displayed. • OnForeground() is called after the lock UI disappears. OnScreenOff() is called. • If the touch lock is enabled. – When the lock key is pressed explicitly.

Ltd. All rights reserved.Application Framework • Application: – All applications must derive from Application class Application AppManager • AppManager: – Application manager class – Finds an AppControl instance IAppFrame AppResource • IAppFrame: – UI frame interface – Frame is the main window in an application AppControl AppRegistry • AppResource: – Application resource class – Can contain localized strings • AppControl: – Application control class – Used to start an application and control specific behavior. Copyright © 2010 Samsung Electronics Co. 22 ..

– For example: eng-GB. ita-IT. Ltd. 23 .xml [IDE String Resource] • AppResource handles localized string resource based on preferred display language that is defined in the device settings. fra-FR. deu-DE. kor-KR. All rights reserved.xml.xml.xml.xml Menu Back Language Setting Copyright © 2010 Samsung Electronics Co. Your App Form AppResource “Hello” eng-GB..Internationalization (1/2) • String resource is supported for multiple languages. Each localized string is saved to each xml file in Res folder.xml.

. see Using String Tables in the Development Environment tutorial. Get the localized string from the AppResource class. 2. – AppResource::GetString(const String& id. 24 . str1). Copyright © 2010 Samsung Electronics Co. Ltd. All rights reserved. Prepare the localized strings table with the UI Builder. String str1. String& loadedString) Application* pApp = Application::GetInstance().Internationalization (2/2) Retrieving localized strings 1. r = pApp->GetAppResource()->GetString("IDS_STRING1". AppResource retrieves the chosen language from the display language settings and returns the localized strings. For more information.

. and the calling application is terminated. • All bada applications follow the single application policy. the OnAppTerminating() method is called immediately after the LaunchApplication() method. Copyright © 2010 Samsung Electronics Co. you must assign the APP_SERVICE privilege group to your application. All rights reserved. • You can retrieve the launch arguments from an application by using the Application::OnUserEventReceivedN() method. For more information. 25 . see the API Reference. • The AppManager::LaunchApplication() method requires the SYSTEM privilege level. Therefore. and to use the method.Launching Other Applications • A bada application can launch other applications using the AppManager::LaunchApplication()method. Ltd.

• AppControl instance can be created from the AppManager. 26 . OPERATION_VIEW. • AppManager finds the service providing application control and returns it for your application to use. For example. APPCONTROL_DIAL. • AppControls can be identified using 2 parameters: – Application Control ID: • Defines the variable for identifying each application control instance.. Copyright © 2010 Samsung Electronics Co.AppControl (1/2) • AppControl is a standard mechanism for using specific operations exported by base applications • AppControl can communicate data and get back results. Ltd. All rights reserved. For example. – Operation ID: • Defines the variable for identifying the behavior of each application control instance.

27 . – OnAppControlCompleted() is invoked when an application finishes its operation and a control callback event occurs. All rights reserved.AppControl (2/2) • The result of the application control‟s execution is returned by IAppControlEventListener‟s OnAppControlCompleted() method.. • Some AppControls require privileges to use them: – For example. Ltd. Copyright © 2010 Samsung Electronics Co. Call and Browser requires Normal privilege.

. This operation can be used to view and save a vCard file. such as events.Application Control ID (1/2) AppControl name APPCONTROL_CONTACT Operation ID OPERATION_PICK OPERATION_ADD Description This operation can be used to read the phone number. This operation can be used to open a Web browser using the specified URL. This operation can be used to call the specified number. Event and to-do items are returned as . The parameter passed to this application control is displayed on the screen. This operation can be used to view and save a vCalendar file. This operation can be used to add a contact to the contact database. This operation can be used with either the single or the multiple selection feature to select one or more Calendar application items. to-do items.vnt files. contact ID. or memos. OPERATION_EDIT OPERATION_VIEW APPCONTROL_CALENDAR OPERATION_PICK OPERATION_VIEW APPCONTROL_DIAL OPERATION_MAIN APPCONTROL_CALL APPCONTROL_BROWSER OPERATION_MAIN OPERATION_MAIN Copyright © 2010 Samsung Electronics Co. This operation can be used to edit a contact in the contact database.vcs files and memo items as . Using this AppControl requires special privileges. All rights reserved. The parameters passed to this AppControl are automatically filled in the appropriate fields in the Add Contact UI. email address. 28 . or vCard file path for one or more contacts in the contact database. Ltd. Users can edit this number and make calls using the Call key. Using this AppControl requires special privileges. This application control can be used to launch the Dial UI. The parameters passed to this AppControl are automatically filled in the appropriate fields in the Edit Contact UI.

. After the user has signed in for the first time. Using this AppControl requires special privileges. This operation can be used to sign out from the bada Server. All rights reserved. This operation can be used to launch the Camera UI to capture images or record video. This operation can be used to compose email messages. from the My Files folder. this operation handles all subsequent sign-ins automatically. The parameters passed to this application control are automatically filled in the appropriate fields in the displayed message composer. This operation can be used to play video files on the device. This operation can be used to obtain the details of a Bluetooth profile on the device. The parameters passed to this application control are automatically filled in the appropriate fields in the displayed message composer. This operation signs out without displaying any dialog. OPERATION_SIGNOUT APPCONTROL_CAMERA OPERATION_CAPTURE APPCONTROL_MESSAGE OPERATION_EDIT This operation can be used to compose SMS or MMS messages. Using this AppControl requires special privileges. Ltd. 29 . This operation can be used to select one or more media files . This operation can be used to play audio files on the device. This operation can be used to view image files on the device. such as images or video recordings. APPCONTROL_EMAIL OPERATION_EDIT APPCOTNROL_BT APPCONTROL_MEDIA OPERATION_PICK OPERATION_PICK APPCONTROL_IMAGE APPCONTROL_VIDEO APPCONTROL_AUDIO OPERATION_VIEW OPERATION_PLAY OPERATION_PLAY Copyright © 2010 Samsung Electronics Co.Application Control ID (2/2) AppControl name APPCONTROL_SIGNIN Operation ID OPERATION_SIGNIN Description This operation can be used to sign in to the bada Server.

Launches the AppControl without any operation.. Ltd.Operation ID Operations specify the specific behavior or action that must be performed. 30 . Displays an item or content in a specific AppControl. Captures an item or content in a specific AppControl. Plays an item or content in a specific AppControl. Signs out of a session. Obtains data from a specific AppControl. Copyright © 2010 Samsung Electronics Co. Operation ID OPERATION_ADD OPERATION_CAPTURE OPERATION_EDIT OPERATION_DEFAULT OPERATION_PICK OPERATION_PLAY OPERATION_VIEW Description Adds an item or content to a specific AppControl. All rights reserved. OPERATION_SIGNIN OPERATION_SIGNOUT Displays a sign-in window. Edits an item or content in a specific AppControl.

. 31 . AppControls Registry #Dial #Video type=“…” #SignIn type=“…” Path=“…” #Browser type=“…” Path=“…” type=“…” … type=“…” Path=“…”… Path=“…” Path=“…” … … … Copyright © 2010 Samsung Electronics Co. Asynchronously send result to AppControl event listener. 2 Resolve the AppControl ID and operation ID. bada Application AppControl Base Application (For example. Ltd. All rights reserved. AppManager [AppControl Resolver] 4. Contact) AppControl 1. Start AppControl. 3. Find AppControl.Getting an AppControl IAppControlEventListener OnAppControlCompleted() 5. Launch the application AppControl ID and operation ID.

. i. AppControl ID: APPCONTROL_MEDIA Operation ID: OPERATION_PICK Option: “type:video” “selectionType:single” Caller Application Media Application • APPCONTROL_DIAL: – Launches the dialer application with a pre-filled phone number. Copyright © 2010 Samsung Electronics Co. Ltd. URI.e.AppControl Examples • APPCONTROL_MEDIA: – Launches the media application to select audio. – Receives selections in an event handler. video. or image content from the Media folder. All rights reserved. – Requires normal privilege. AppControl ID: APPCONTROL_DIAL Operation ID: NONE Option: “tel:+82312798707” Caller Application Dialer Application The calling application receives information of the selected media. 32 .

.Example: Create an Application (1/2) This example illustrates how application default methods are created. 1.cpp. Ltd. 33 . – Open \<BADA_SDK_HOME>\Examples\UIApplication\src \HelloWorld. Create the HelloWorld application code using the Frame Based Application template. Copyright © 2010 Samsung Electronics Co. All rights reserved.

ID. it contains other information necessary for your application.xml file from bada Developers. 34 . such as privileges and device profiles. Ltd. All rights reserved.Example: Create an Application (2/2) Notes – Applications must derive from the Application class. In addition to the information above (name.xml MyApplication Copyright © 2010 Samsung Electronics Co. – You must create and download your application‟s manifest. secret code). Application Name GetAppName() Application Application ID GetAppId() Secret Code GetAppSecret() Manifest..

1. use AppRegistry to retrieve application settings: AppRegistry::Get(key. value) 2. Save application settings to disk in the registry: AppRegistry::Save() 4. value) Copyright © 2010 Samsung Electronics Co. 35 . In the OnAppInitializing() method. The first time an application runs.Example: Save and Restore Application Settings (1/2) Save and restore application state. Set registry values in the OnAppTerminating() event handler: AppRegistry::Set(key. the registry entry must be added: AppRegistry::Add(key. All rights reserved.. value) 3. Ltd.

gamestatus). Ltd. … } bool MyApplication::OnAppTerminating(AppRegistry& appRegistry) { … result r = E_SUCCESS.Set("LastMessage".Get("GameStatus". } appRegistry.Get("LastMessage".Add("GameStatus". appRegistry. // enum { INIT=0. r = appRegistry. //enum { INIT=0. if(r == E_KEY_NOT_FOUND { appRegistry. if(r == E_KEY_NOT_FOUND { appRegistry. message).Save().Set("GameStatus". 36 .Example: Save and Restore Application Settings (2/2) bool MyApplication::OnAppInitializing(AppRegistry& appRegistry) { … String message("NONE"). PLAYING. gamestatus). r = appRegistry. "Who destroyed"). PLAYING. r = appRegistry. All rights reserved. } // Enumeration definitions are defined elsewhere. … } Copyright © 2010 Samsung Electronics Co. SCORE } GameStatus = INIT. (int)GameStatus). message). appRegistry.Save().Add("LastMessage". int gamestatus = GameStatus. SCORE } GameStatus = PLAYING..

Implement the ScreenEventListener to handle screen events. } Copyright © 2010 Samsung Electronics Co. then turn on sound. All rights reserved. } void MyApplicaiton::OnBackground() { if(IsPlaying) StopSound(). You can handle other resources in the same way.Example: Handle Screen Events This example illustrates how to handle a sound resource during screen on and screen off events. } void MyApplication::OnScreenOff (void) { if(IsPlaying) StopSound(). if(!IsPlaying) PlaySound(). Play or stop the sound using PlaySound()or StopSound() accordingly. Check the sound status using the boolean value of the IsPlaying variable.. 2. 37 . } void MyApplication::OnForeground() { if(!IsPlaying) PlaySound(). … } void MyApplication::OnScreenOn (void) { // Check if sound is off. 1. bool MyApplication::OnAppInitializing(AppRegistry& appRegistry) { … PowerManager::SetScreenEventListener(*this). Ltd. 3.

38 . if(pAc != null) { pAc->Start(null. delete pAc. start the AppControl by calling its Start() method: AppControl::Start(null. \n"). this) Notes: – If you require event handlers. this). Get an AppControl instance by calling the FindAppControlN() method. } else AppLog("AppControl Not Found.. AppControl* pAc = AppManager::FindAppControlN(APPCONTROL_SIGNIN.Example: Use Sign-In Application Control 1. OPERATION_SIGNIN) 2. Ltd. Copyright © 2010 Samsung Electronics Co. OPERATION_SIGNIN). implement an IAppControlEventListener. If the FindAppControlN() method returns an AppControl instance. All rights reserved. Provide the SignIn Control ID as parameter: AppManager::FindAppControlN(APPCONTROL_SIGNIN.

Copyright © 2010 Samsung Electronics Co. terminating the caller application. 3. The called application is launched.Example: Launch Other Applications and Handle Launch Arguments (1/2) This example illustrates how to launch other applications from a bada application and retrieve the launch arguments.. 1. requestId is assigned as a reserved launch ID (AppLaunchRequestId). If the launch arguments exist. All rights reserved. The OnAppTerminating()method is called. A caller application launches another application with arguments using the LaunchApplication() method. 2. Ltd. 39 .

“yourdata”) … } else // Handling User Events Copyright © 2010 Samsung Electronics Co. // pArgs[0] represents the launch type (for example. ArrayList *pArgList = new ArrayList().Example: Launch Other Applications and Handle Launch Arguments (2/2) Caller application: … AppId calleeAppId = L”1234567890”. APP_LAUNCH_NORMAL value) // pArgs[1] represents the operation of the launch (default value is OPERATION_DEFAULT). Called application: void CalleeApp::OnUserEventReceivedN (RequestId requestId. pArgList->Construct(). r = pAppManager->LaunchApplication(calleeAppId. AppManager *pAppManager = AppManager::GetInstance(). String *aArg = new String(L”yourdata”). i++) AppLog("pData[%d]=%S". pArgList. ((String*)(pArgs->GetAt(i)))->GetPointer()). AppManager::LAUNCH_OPTION_DEFAULT). i. Ltd. // pAgrs[>=2] contains the actual arguments sent from the caller (for example. Osp::Base::Collection::IList *pArgs) { if(requestId == AppLaunchRequestId) // If launch arguments come { if(pArgs) { for(int i = 0. pArgList->Add(*aArg).. 40 . All rights reserved. i < pArgs->GetCount().

form and its child controls) is freed automatically when the application closed. since they are member methods of the Application class. but UI resources(e.. – Free non UI resources in the OnAppTerminating() method. and GetAppSecret() methods. an application ID (a unique identifier bound to a bada application) is created from the bada developer site and saved into the application manifest file (manifest.xml). Ltd. Please review the UI parts of this document about UI resource. All rights reserved. You do not need to free them explicitly.FAQ • Where do I initialize and free-up application resources? – Initialize them in the OnAppInitializing() method. Copyright © 2010 Samsung Electronics Co. 41 . GetAppName(). • Do I have to set my application‟s ID somewhere? – No. The bada IDE does not automatically generate the GetAppId().g.

42 . All rights reserved.. Ltd.Copyright © 2010 Samsung Electronics Co.

Sign up to vote on this title
UsefulNot useful