EFL Basic UI Application

To create an EFL basic UI application, you must:

• Define the application fundamentals, mainly the entry point and life-cycle callbacks.

  The entry point starts the event loop, which is mandatory for every Tizen native application. Within the event loop, the application can receive both basic system events and application state change events. You can register callbacks for these events to react to them.

• Manage application states and transitions during its life-cycle.

• Define a background category for your application, if you want it to run in the background.

Event Callbacks

The following table lists the application state change events.

Table: Application state change events

For more information, see Application State and Transition Management.

To listen for 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

Application States and Transitions

The Tizen Native application can be in one of several different application states.

The Application API defines 5 states with corresponding transition handlers. A state transition callback is triggered after each state change, whenever the application is created, starts running, or is paused, resumed, or terminated. The application must react to each state change appropriately.

Table: Application states

The following figure illustrates the application state transitions.

Figure: Application state transitions

Prerequisites

To use the functions and data types of the Application API (in mobile and wearable applications), include the <app.h> header file in your application:

#include <app.h>

Handling the Application Fundamentals

The Application API is a simple framework all Tizen applications are based on. It only handles interactions between applications and the operating system. 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.

To manage the application life-cycle:

1. Start the application with the main() function. It initializes the Application API and starts the main event loop with the ui_app_main() function. Before calling the ui_app_main() function, set up the app_event_callback_s structure variable, which is passed to the function.

   The following code is a minimal application using the Application API. It only builds and runs.

   int
   main(int argc, char *argv[])
   {
       /* Create a ui_app_lifecycle_callback_s object and initialize its contents to 0 */
       ui_app_lifecycle_callback_s event_callback = {0,};
   
       /* Run the application */
       return ui_app_main(&argc, &argv, &event_callback, NULL);
   }
   

2. Define the application state callbacks.

   The Application API has 2 classes of application state callbacks: those about the application life-cycle and those about the system.

   • Application life-cycle callbacks:
     • create: Called after the ui_app_main() function and used to initialize the UI.
     • control: Triggered when the application is started to do something. It can be called several times during the lifespan of an application, and it shows the screen for the action requested. It requires specific information given to the callback.
     • terminate: Saves work, releases resources, and exits.
     • pause: Sets the application window not visible and switches to a mode which uses less resources.
     • resume: Sets the application window to be visible again.
   • System-related events (handled with the app_event_cb() callback):
     • APP_EVENT_LOW_MEMORY: Used to save 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 event is also used to release any cached data in the main memory to secure more free memory.
     • APP_EVENT_LOW_BATTERY: Used to save data in the main memory to a persistent memory or storage to avoid data loss in case the power goes off completely. The event is also used to stop heavy CPU consumption or power consumption activities to save the remaining power.
     • APP_EVENT_DEVICE_ORIENTATION_CHANGED: Used to change the display orientation to match the device orientation.
     • APP_EVENT_LANGUAGE_CHANGED: Used to refresh the display into a new language.
     • APP_EVENT_REGION_FORMAT_CHANGED: Used to refresh the display into a new time zone.

   The following example shows a basic application state callback implementation:

   /*
      Structure to store the data for application logic; it is given
      to each callback invoked through the Application API
   */
   struct appdata {
       char *several;
       char *fields;
   };
   typedef struct appdata appdata_s;
   
   static bool
   app_create(void *data)
   {
       /*
          Hook to take necessary actions before main event loop starts; this
          usually means initializing the UI and application data (the "data"
          parameter to this function)
       */
   
       appdata_s *ad = data;
       create_gui(ad);
   
       /* If this function returns true, the main loop starts */
       /* If this function returns false, the application is terminated */
       return true;
   }
   
   static void
   app_control(app_control_h app_control, void *data)
   {
       /*
          Handle the launch request, show the user the task requested through the
          "app_control" parameter (see the next step)
       */
   }
   
   static void
   app_pause(void *data)
   {
       /* Take necessary actions when application becomes invisible */
   }
   
   static void
   app_resume(void *data)
   {
       /* Take necessary actions when application becomes visible */
   }
   
   static void
   app_terminate(void *data)
   {
       /* Release all resources */
       appdata_s *ad = data;
   
       if (!ad)
           return;
   
       /*
          If specific steps are needed:
          destroy_gui(ad);
       */
   }
   
   int
   main(int argc, char *argv[])
   {
       appdata_s ad = {0,};
       ui_app_lifecycle_callback_s event_callback = {0,};
   
       /* Set the callbacks for the application logic */
       event_callback.create = app_create;
       event_callback.terminate = app_terminate;
       event_callback.pause = app_pause;
       event_callback.resume = app_resume;
       event_callback.app_control = app_control;
   
       /* Note the &ad below is how the struct is given to the callbacks */
       return ui_app_main(argc, argv, &event_callback, &ad);
   }
   

3. Define any required application controls. An app control is a mechanism through which the application receives additional information about why it was started and with which parameters.

   The application receives a handle to an app control object in the app_control callback. The app_control_h type is opaque and information can only be extracted from it through API functions, such as:

   • app_control_get_operation(): Retrieve a string describing which operation the application was started for.
   • app_control_get_mime(): Retrieve the MIME type of the data (such as image/jpg).
   • app_control_get_app_extra_data(): Get the string value associated with a given key.
   • app_control_get_app_extra_data_array(): Get the string array associated with a given key (first check with app_control_is_extra_data_array() whether the data associated with the key is an array).

   For other available functions, see the app.h header file.

   For more information on launching other applications from your application using application controls, see Application Controls.

Background Categories

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

Table: Allowed background application policy

Note

Since Tizen 4.0, even if the background network category is declared, the running application stops if the network is not connected.

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 and 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 on Tizen 2.4 and 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 Tizen Studio.

Related Information

• Dependencies
  • Tizen 2.4 and Higher for Mobile
  • Tizen 2.3.1 and Higher for Wearable