EFL UTIL

The EFL UTIL utility package supports the additional notification level functionality of EFL. It provides the following functions for setting and getting the notification level of the notification window (which is of the EFL window type):

• efl_util_set_notification_window_level()
• efl_util_get_notification_window_level()

To understand notification levels, you must first learn about the Tizen window layer hierarchy. Window layers are logical containers used to control the window stack order. Each window belongs to 1 layer and can change the stack order in the layer. Windows in same layer are always placed on or under a window in another layer. In addition to the default "normal layer", there exists a "notification layer", which is always placed above the normal layer.

Figure: Window layers

Each window is set to a specific layer according to its type or properties. Most application windows belong to the normal layer. However, in case of an important alarm or other information crucial to the user, you can set the window to belong to the notification layer. This ensures that the user notices the information immediately, because the window belonging to the notification layer is always shown above the windows in the normal layer.

A window that belongs to the notification layer is called a "notification window". To make a notification window:

1. Set the window type to NOTIFICATION, by calling the elm_win_add() function with the third parameter set to ELM_WIN_NOTIFICATION.
2. Set the notification level by calling the efl_util_set_notification_window_level() function.

   The notification level defines the priority of the window, and the notification layer contains 3 levels (EFL_UTIL_NOTIFICATION_LEVEL_1, EFL_UTIL_NOTIFICATION_LEVEL_2, and EFL_UTIL_NOTIFICATION_LEVEL_3).

   The default notification window level is EFL_UTIL_NOTIFICATION_LEVEL_1. Most of notification windows can be set to this level. The EFL_UTIL_NOTIFICATION_LEVEL_2 is a higher level than EFL_UTIL_NOTIFICATION_LEVEL_1, which means that the window set to EFL_UTIL_NOTIFICATION_LEVEL_2 is always on the EFL_UTIL_NOTIFICATION_LEVEL_1 level window. The EFL_UTIL_NOTIFICATION_LEVEL_3 is the highest level in notification windows. Very few applications can use this level.

   If there are notification windows that have the same level, the most recently created notification window is placed on top of the other window.

Figure: Notification levels

In general, notification levels in Tizen are used as follows:

• NOTIFICATION_LEVEL_1 is the basic level which is used as a normal notification popup.
• NOTIFICATION_LEVEL_2 is used for the lock screen window.
• NOTIFICATION_LEVEL_3, the highest layer, is used in case the user needs to be notified in any circumstances. For example, the incoming call popup can use this level.

The following code snippets shown how to make a notification window with a higher level.

#include <Elementary.h>
#include <efl_util.h>
#include <dlog.h>

static Evas_Object *create_win(const char *name)
{
   Evas_Object *eo;
   efl_util_error_e error;
   // Create the NOTIFICATION window object
   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);

   if (!eo) return NULL;

   // Set the NOTIFICATION level
   error = efl_util_set_notification_window_level(eo, EFL_UTIL_NOTIFICATION_LEVEL_1);

   elm_win_title_set(eo, name);
   elm_win_autodel_set(eo, EINA_TRUE); 
   evas_object_smart_callback_add(eo, "delete,request", _quit_cb, NULL); 
	
   return eo;
}

Use the efl_util_get_notification_window_level() function to get the currently set notification level of a window. If the window is not of the notification type, the function returns the -EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE error.

#include <Elementary.h>
#include <efl_util.h>
#include <dlog.h>

void get_notification_level (Evas_Object *eo)
{
   efl_util_error_e error;
   efl_util_notification_level_e  notification_level;

   if (!eo) return;

   // Get the window notification level
   error = efl_util_get_notification_window_level (eo, &notification_level);

   // Check the return value
   if (error== EFL_UTIL_ERROR_NONE)
   {
      switch (notification_level)
      {
         case EFL_UTIL_NOTIFICATION_LEVEL_1:
            // Do something for level 1
            break;

         case EFL_UTIL_NOTIFICATION_LEVEL_2:
            // Do something for level 2
            break;
      }
   }
   else
   {
      // Error handling
   }
}