Mobile native Wearable native

Application

A Tizen native application is similar to a conventional Linux application, with some additional features optimized for mobile devices. The additional features have constraints, such as a relatively small screen size and lack of system resources compared to a larger system. For example, for power management reasons, the application can take actions to reduce usage when it finds out that it has its display window covered over by another application window. State change events are delivered to make it possible to detect these situations.

The Application API provides interfaces for the following categories:

In addition, you can use sub-category APIs to:

Managing the Event Loop

In order for an application to operate successfully, it must receive events from the platform. For this, it must start the main event loop - this is mandatory for all Tizen native applications.

The ui_app_main() function is used to start the event loop. Before calling this function, set up the app_event_callback_s structure variable, which is passed to the function.

For more information about launching applications, see App Control.

Registering Callbacks for Events

The following table lists the application state change events.

Table: Application state change events
Callback Description
app_create_cb() Used to take necessary actions before the main event loop starts. Place the UI generation code here to prevent missing any events from your application UI.
app_pause_cb() Used to take necessary actions when the application becomes invisible. For example, release memory resources so other applications can use them. Do not starve the foreground application that is interacting with the user.
app_resume_cb() Used to take necessary actions when the application becomes visible. If you relinquish anything in the app_pause_cb() callback, re-allocate those resources here before the application resumes.
app_terminate_cb() Used to take necessary actions when the application is terminating. Release all resources, especially any allocations and shared resources, so that other running applications can fully use any shared resources.

For more information, see Managing Application States and Transitions.

To listen to system events, use the ui_app_add_event_handler() function. The system events are triggered with the app_event_cb() callback function. The following table lists the event types.

Table: Event types
Event type Description
APP_EVENT_LOW_MEMORY Event type for the callback function that is responsible for saving data in the main memory to a persistent memory or storage to avoid data loss in case the Tizen platform Low Memory Killer kills your application to get more free memory. The callback function must also release any cached data in the main memory to secure more free memory.
APP_EVENT_LOW_BATTERY Event type for the callback function that is responsible for saving data in the main memory to a persistent memory or storage to avoid data loss in case the power goes off completely. The callback function must also stop heavy CPU consumption or power consumption activities to save the remaining power.
APP_EVENT_DEVICE_ORIENTATION_CHANGED Event type for the callback function that is responsible for changing the display orientation to match the device orientation.
APP_EVENT_LANGUAGE_CHANGED Event type for the callback function that is responsible for refreshing the display into the new language.
APP_EVENT_REGION_FORMAT_CHANGED Event type for the callback function that is responsible for refreshing the display into the new time zone.
APP_EVENT_SUSPENDED_STATE_CHANGED Event type for the callback function that is responsible for taking necessary actions before entering the suspended state or after exiting from the state. (Supported since Tizen 2.4.)

Managing Application States and Transitions

The Tizen native application can be in one of several different states. Typically, the application is launched by the user from the Launcher, or by another application. As the application is starting, the app_create_cb() callback is executed and the main event loop starts. The application now normally becomes the frontmost window, with focus. When the application loses the frontmost or focus status, the app_pause_cb() callback is invoked and your application goes into a pause state. The pause state means that the application is not terminated but is running in the background. The application can go into a pause state because:

  • A new application is launched from the request of your application.
  • The user requests to go to the home screen.
  • A system event occurs and causes a resident application with a higher priority (such as an incoming phone call) to become active and hide your application temporarily.
  • An alarm is triggered for another application, which becomes the top-most window and hides your application.

When your application becomes visible again, the app_resume_cb() callback is invoked. This happens because:

  • Another application requests your application to run (perhaps the Task Navigator, which shows all running applications and lets the user select any application to run).
  • All applications on top of your application in the window stack finish.
  • An alarm is triggered for your application, so it becomes the top-most window and hides other applications.

When your application starts exiting, the app_terminate_cb() callback is invoked. Your application terminates because:

  • Your application itself requests to exit by calling the ui_app_exit() function to terminate the event loop.
  • The Low Memory Killer is killing your application in a low memory situation.

The application state changes are managed by the underlying framework. The following figure and table illustrate the application states.

Figure: Application states

Application state transitions

Table: Application states
State Description
READY Application is launched.
CREATED Application starts the main loop.
RUNNING Application is running and visible to the user.
PAUSED Application is running but invisible to the user.
TERMINATED Application is terminated.

The Application API defines 5 states with corresponding transition handlers. The state transition is notified through a state transition callback function, whether the application is created, running, paused, resumed, or terminated. The application must react to each state change appropriately.

Figure: Application state transitions

Application state transitions

Allowing Applications to Run on the Background

Since Tizen 2.4, the application is not allowed to run on the background except when it is explicitly declared to do so. The following table lists the background categories that allow the application to run on the background.

Table: Allowed background application policy
Background category Description Related APIs Manifest file <background-category> element value
Media Playing audio, recording, and outputting streaming video on the background Multimedia API (in mobile and wearable applications) media
Download Downloading data with the Tizen Download-manager API Download API (in mobile applications) download
Background network Processing general network operations on the background (such as sync-manager, IM, and VOIP) Sync Manager API (in mobile applications), Socket, and Curl API (in mobile and wearable applications) background-network
Location Processing location data on the background Location API (in mobile and wearable applications) location
Sensor (context) Processing context data from the sensors, such as gesture Sensor API (in mobile and wearable applications) sensor
IoT Communication/Connectivity Communicating between external devices on the background (such as Wi-Fi and Bluetooth) Wi-Fi (in mobile and wearable applications) and Bluetooth API (in mobile and wearable applications) iot-communication

Describing the Background Category

An application with a background running capability must declare the background category in its manifest file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns="http://tizen.org/ns/packages" api-version="2.4" package="org.tizen.test" version="1.0.0">
   <ui-application appid="org.tizen.test" exec="text" type="capp" multiple="false" taskmanage="true" nodisplay="false">
      <icon>rest.png</icon>
      <label>rest</label>
      <!--For API version 2.4 or higher-->
      <background-category value="media"/>
      <background-category value="download"/>
      <background-category value="background-network"/>
   </ui-application>
   <service-application appid="org.tizen.test-service" exec="test-service" multiple="false" type="capp"/>
      <background-category value="background-network"/>
      <background-category value="location"/>
   </service-application>
</manifest>
Note
The <background-category> element is supported since the API version 2.4. An application with a <background-category> element declared can fail to be installed on devices with a Tizen version lower than 2.4. In this case, declare the background category as <metadata key="http://tizen.org/metadata/background-category/<value>"/>.
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns="http://tizen.org/ns/packages" api-version="2.3" package="org.tizen.test" version="1.0.0">
   <ui-application appid="org.tizen.test" exec="text" type="capp" multiple="false" taskmanage="true" nodisplay="false">
      <icon>rest.png</icon>
      <label>rest</label>
      <!--For API version lower than 2.4-->
      <metadata key="http://tizen.org/metadata/background-category/media"/>
      <metadata key="http://tizen.org/metadata/background-category/download"/>
      <metadata key="http://tizen.org/metadata/background-category/background-network"/>
   </ui-application>
   <service-application appid="org.tizen.test-service" exec="test-service" multiple="false" type="capp"/>
      <metadata key="http://tizen.org/metadata/background-category/background-network"/>
      <metadata key="http://tizen.org/metadata/background-category/location"/>
   </service-application>
</manifest>

The <metadata key="http://tizen.org/metadata/bacgkround-category/<value>"/> element has no effect on Tizen 2.3 devices, but, in Tizen 2.4 or higher devices, it has the same effect as the <background-category> element.

The background category of your application can be specified in the application project settings in the IDE.

Go to top