Page Example

Resource Management Sample Overview

Mobile native

The Resource Management sample application demonstrates how you can extract objects from the application's previously created resources. The object extraction process is based on the environment the application is running in: language and the screen DPI. Currently supported objects that can be handled by the Resource Management are images, sounds, layouts, and custom binary files. The operational principle of the Resource Management application is to deliver an object relevant to the current application environment.

The sample application demonstrates how to automatically pick an image and layout matching:

  • Language changed in the Settings application
  • Device screen DPI

The following figure illustrates the view of the application running in four different screen DPI settings as well as different language settings.

Figure: Resource Management application screens

Main view of the application running with the DPI=240 Main view of the application running with the DPI=300 Main view of the application running with the DPI=380 Main view of the application running with the DPI=480

Main view of the application running with the DPI=240 Main view of the application running with the DPI=300 Main view of the application running with the DPI=380 Main view of the application running with the DPI=480

The Resource Management sample application provides a user interface for automatic change preview only. To influence the application, change the environment settings:

  • Language: change the display language in the Settings application by going to Settings application > Language and input > Display language.
  • Screen DPI: Create a new mobile emulator image with the default density value altered with a custom one, chosen from the following ranges:
    • 0 to 240 - LDPI
    • 241 to 300 - MDPI
    • 301 to 380 - HDPI
    • 381 to 480 - XHDPI
    • 481 to 600 - XXHDPI

The following figure shows the structure of the user interface. EDJE layout scripts are used.

Figure: Layout structure

Layout structure

The final application view is created by embedding the proper components into the layout depicted above. The following figure shows the resulting UI view.

Figure: Application UI view

Application UI view

The application workflow can be divided into 3 logical pipelines:

  • Application startup
  • Image extraction relevant to the screen DPI
  • Image and layout extraction relevant to the current language

The workflow is described by the following figure.

Figure: Application workflow

Application workflow

Prerequisites

To ensure proper application execution, the resources must be created using the Resource Manager tool. It enables you to create the resource structure assigned to an application.

Resource Manager Tool

The Resource Manager tool is launched by opening the Resource Manager view from the IDE menu: Window > Show View > Other > Tizen > Resource Manager. Press Resource Manager settings button to open the Resource Configuration Dialog, where you can define separate resource directories for languages and resolution settings. The related directory names are created automatically and are not changeable. For this sample application, the resource structure is defined as shown in the following figure.

Figure: Resource Configuration Dialog view

Resource Configuration Dialog view

Once the resource directory structure is created, you can add relevant resource files in the target directories. In this sample application, 2 types of images and a layout script are uploaded:

  • tizen.png: The Tizen logo adapted to each resolution respectively
  • flag.png: The national flag relevant to each supported language
  • language.edc: The layout script relevant to each supported language

The name of each of the resolution-related files is set to tizen.png and to flag.png. The file name for the language related file is language.edc for each language-related resource.

During the application packaging process, the res.xml file is created and uploaded to the application resource directory. This file is populated with a set of information acquired from the Resource Manager. It cannot be edited manually, as it is replaced by the Resource Manager each time the application is rebuilt.

In the application source code, after the Resource Manager API is initialized, the relevant resource file path is acquired using the app_resource_manager_get() function, where the parameters are:

  • type: Type of the resource (image, sound, layout, and bin are currently supported)
  • id: Identifier of the resource (file name with extension)
  • path: Pointer to the path where the expected resource (file) is stored

The Resource Manager looks for the file matching the type and id with respect to the current environment (resolution and language). As a result, the appropriate file path is returned.

Implementation

Type Definitions

The following code shows the structures used as placeholders for various application data:

// General structure for application data storage
struct 
__appdata 
{
   viewdata_s view;
};

// All Evas_Object objects represent UI components
struct 
__viewdata 
{
   Evas_Object *win;
   Evas_Object *conform;
   Evas_Object *layout_main_panel;
   Evas_Object *layout_language;
   Evas_Object *image_dpi;
   Evas_Object *image_language;
};

typedef struct __viewdata viewdata_s;

Application Initialization

To initialize the application:

  1. Implement the entire application life-cycle in the main source file, using a common Tizen application structure:
    int 
    main(int argc, char *argv[])
    {
       appdata_s ad = {{0,},};
       int ret = 0;
    
       ui_app_lifecycle_callback_s event_callback;
       app_event_handler_h handlers[5] = {NULL,};
    
       event_callback.create = __create_app;
       event_callback.terminate = __terminate_app;
       event_callback.pause = __pause_app;
       event_callback.resume = __resume_app;
       event_callback.app_control = __control_app;
    
       ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, __ui_app_low_battery, &ad);
       ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, __ui_app_low_memory, &ad);
       ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED], APP_EVENT_DEVICE_ORIENTATION_CHANGED, __ui_app_orient_changed, &ad);
       ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, __ui_app_lang_changed, &ad);
       ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, __ui_app_region_changed, &ad);
    
       ret = ui_app_main(argc, argv, &event_callback, &ad);
       if (ret != APP_ERROR_NONE)
          controller_log(DLOG_ERROR, "Function ui_app_main() failed with error = %d", ret);
    
       return ret;
    }
    
  2. Initialize the application with the __create_app() callback function, which is invoked on application startup:
    static bool 
    __create_app(void *data)
    {
       appdata_s *ad = (appdata_s *)data;
    
       return controller_init(&ad->view);
    }
    
  3. Invoke the controller_init() function, which controls the entire initialization process. This function is responsible for:
    • Resource Manager engine initialization (model_init())
    • User interface creation (view_create_base_gui()) and initialization (__controller_init_dpi())
    bool 
    controller_init(viewdata_s *vd)
    {
       if (!model_init())
          return false;
    
       if (!view_create_base_gui(vd))
          return false;
    
       __controller_init_dpi(vd);
    
       return true;
    }
    
    1. Invoke the app_resource_manager_init() function with the model_init() function to get access to the Resource Manager engine:

      bool 
      model_init(void)
      {
         return __model_init_app_resource_manager();
      }
      
      bool 
      __model_init_app_resource_manager(void)
      {
         int ret = app_resource_manager_init();
         if (ret != APP_RESOURCE_ERROR_NONE) 
         {
            controller_log(DLOG_ERROR, "Function app_resource_manager_init() failed with error %d.", ret);
      
            return false;
         }
      
         return true;
      }
      
    2. Use the __controller_init_dpi() function to get the tizen.png image file path from the Resource Manager and update the view with the image relevant to the screen DPI:

      static void 
      __controller_init_dpi(viewdata_s *vd)
      {
         char *file_path = NULL;
      
         if (!model_get_app_resource(APP_RESOURCE_TYPE_IMAGE, "tizen.png", &file_path))
            return;
      
         view_show_dpi_image(vd, file_path);
         free(file_path);
      }
      

      For reference of the Model-related functions that are not listed here, see Model. The view-related source code is not listed here, as it is not a subject of this topic.

Application Termination

To terminate the application:

  1. When the application is terminated, call the __terminate_app() callback function:
    static void 
    __terminate_app(void *data)
    {
       appdata_s *ad = (appdata_s *)data;
    
       controller_finit(&ad->view);
    }
    
  2. Release the previously allocated resources with the controller_finit() function, which is responsible for closing the Resource Manager API session and destroying the UI:
    void 
    controller_finit(viewdata_s *vd)
    {
       model_finit();
       view_destroy_base_gui(vd);
    }
    
  3. Close the Resource Manager API session in the Model module within the model_finit() function, which calls the internal __model_release_app_resource_manager() function.

    As the UI is not a subject for this topic, the implementation of the view_destroy_base_gui() function is omitted.

    bool 
    model_finit(void)
    {
       return __model_release_app_resource_manager();
    }
    
    bool 
    __model_release_app_resource_manager(void)
    {
       int ret = app_resource_manager_release();
       if (ret != APP_RESOURCE_ERROR_NONE) 
       {
          controller_log(DLOG_ERROR, "Function app_resource_manager_release() failed with error %d.", ret);
    
          return false;
       }
    
       return true;
    }
    

Resource File Handling

Once the resources are defined using the Resource Manager tool and appropriate resource files are uploaded to the destination folders, you can start using these files. For demonstration purposes, 3 scenarios are chosen:

  • Displaying the image related to the current DPI setting
  • Displaying the image related to the current locale setting
  • Setting the layout related to the current locale setting

In the first scenario, there are 5 image files depicting the Tizen logo with resolution label attached. Each of the images with their name set to tizen.png is stored in a different folder with respect to the DPI setting. The folders are res/contents/LDPI, res/contents/MDPI, res/contents/HDPI, res/contents/XHDPI, and res/contents/XXHDPI.

On application startup, during the initialization procedure (see Application Initialization), the __controller_init_dpi() function is called, which obtains the path to the relevant image based on the current screen settings. The core function performing the described task is the model_get_app_resource() function. For reference, see Model.

static void 
__controller_init_dpi(viewdata_s *vd)
{
   char *file_path = NULL;

   // Obtains the path to the tizen.png file with respect to the current screen settings
   if (!model_get_app_resource(APP_RESOURCE_TYPE_IMAGE, "tizen.png", &file_path))
      return;

   // Obtained image file is displayed
   view_show_dpi_image(vd, file_path);
   free(file_path);
}

In the second and third scenario, there are 48 image files (each name is set to flag.png) depicting the national flags, and 48 layout files (each name is set to language.edc) creating the text fields related to all supported languages. Each of the images and layouts are stored in a different folder. The folders are res/contents/az_AZ, res/contents/ca_ES, ..., res/contents/zh_TW.

When the current language is changed (in Settings > Language and input > Display language), the __ui_app_lang_changed() callback function is invoked (see Application Initialization). This callback function hooks the APP_EVENT_LANGUAGE_CHANGED event. At the entry point of the __ui_app_lang_changed() function, the current locale is obtained using the model_get_locale() function to be later set as a current language for the application with the elm_language_set() function.

Finally, the controller_set_language() function is invoked, which is responsible for obtaining and displaying the language-relevant image.

static void
__ui_app_lang_changed(app_event_info_h event_info, void *user_data)
{
   appdata_s *ad = (appdata_s *)user_data;
   char *locale = NULL;

   if (!model_get_locale(&locale))
      return;

   elm_language_set(locale);

   controller_log(DLOG_INFO, "Language set to: %s.", locale);

   if (locale)
      free(locale);

   controller_set_language(&ad->view);

   return;
}

void 
controller_set_language(viewdata_s *vd)
{
   char *file_path = NULL;

   // Obtains the path to the language.edj file with respect to the current language settings
   if (model_get_app_resource(APP_RESOURCE_TYPE_LAYOUT, "language.edj", &file_path)) 
   {
      const char *rel_file_path = NULL;

      // Layout file path must be transformed to the relative one, as the elm_layout component does not accept absolute paths
      if (__controller_get_relative_resource_file_path(file_path, &rel_file_path))
         // If successful, the layout file is uploaded and inserted to the PART_MAIN_BOTTOM_PANEL_LANGUAGE_PANEL swallow of the main layout
         view_show_language_layout(vd, rel_file_path);
   }

   if (file_path)
      free(file_path);

   file_path = NULL;

   // Obtains the path to the flag.png file with respect to the current language settings
   if (model_get_app_resource(APP_RESOURCE_TYPE_IMAGE, "flag.png", &file_path))
      // If successful, the image is displayed
      view_show_language_info(vd, file_path);

   if (file_path)
      free(file_path);
}

For all Model-related functions, see Model.

Model

The responsibility of the application Model module is to operate directly on the Resource Manager API. The additional benefit of this module is the simplification of the API function calling, as error checking and message logging is performed here.

Some of the functions implemented within the Model module were described in Application Initialization and Application Termination sections (model_init(), model_finit(), __model_init_app_resource_manager(), and __model_release_app_resource_manager()). Other functions are described here.

The path to the resource file pointed by the type and id is obtained with the model_get_app_resource() function:

bool 
model_get_app_resource(app_resource_e type, const char *id, char **path)
{
   *path = NULL;

   int ret = app_resource_manager_get(type, id, path);
   if (ret != APP_RESOURCE_ERROR_NONE) 
   {
      controller_log(DLOG_ERROR, "Function app_resource_manager_get() failed with error %d.", ret);

      return false;
   }

   return true;
}