Mobile native Wearable native

Application: Using Alarms, Preferences, AppControl, and Other Fundamentals

This tutorial demonstrates how you can manage application fundamentals, such as application life-cycle callbacks.

Warm-up

Become familiar with the Application API basics by learning about:

For additional application-related features, see:

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.

To manage the application life-cycle:

  1. Start the application with the main() function. It initializes the Application API and starts the application.

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

    // Add this include to be able to use the functions from the Application API
#include <app.h>

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:

    #include <app.h>

// Structure to store the data for application logic; it is given
// to each callback invoked through the Application API
typedef struct 
appdata 
{
   char *several;
   char *fields;
} 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 functions from the SDK, 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.

Go to top