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:

• Starting or exiting the main event loop (mandatory for every Tizen native application)
• Registering callbacks for application state change events
• Registering callbacks for basic system events
• Managing application states and transitions
• Allowing applications to run on the background

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

• Handle alarms with the Alarm API
• Launch applications with the App Control API
• Broadcast and subscribe to events with the Event API
• Localize application strings with the Internationalization API

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.

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.

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

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

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.

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>

<?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 background category of your application can be specified in the application project settings in the IDE.