Notification Windows: Supporting Notification Levels, Screenshots, and Input Generators

The EFL UTIL utility package supports the following EFL functionalities:

• Notification Window and Level

  You can initialize the EFL Utility, create a notification window and set a window level, and get the notification window level.

• Screenshot

  You can initialize the EFL Utility and capture a screenshot.

• Input Generator

  You can initialize the EFL Utility, and generate a key input event and touch input event.

Notification Window and Level

The EFL UTIL API allows you to set and get 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.

Using the Notification Windows

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
   }
}

Screenshot

The EFL UTIL SCREENSHOT API (in mobile and wearable applications) allows you to get the screen image to the user.

First you must make the efl_util_screenshot_h structure and initialize the structure members with the efl_util_screenshot_initialize() function. To take the actual screenshot, create screen capture data and return it to the tbm_surface handler with the efl_util_screenshot_take_tbm_surface() function.

When no longer needed, remember to free the efl_util_screenshot_h structure with the efl_util_screenshot_deinitialize() function.

Input Generator

The EFL UTIL INPUT API (in mobile and wearable applications) allows you to generate input events (such as key and touch events).

First you must create the efl_util_inputgen_h structure and initialize the structure members with the efl_util_input_initialize_generator() function. To generate actual key or touch events, use the efl_util_input_generate_key() or efl_util_input_generate_touch() function.

When no longer needed, remember to free the efl_util_inputgen_h structure with the efl_util_input_deinitialize_generator() function.

Initializing EFL Utility

To use the EFL UTIL API, the following header file has to be included:

#include <efl_util.h>

Creating a Notification Window and Setting a Notification Window Level

To create a notification window and set the window level, use the efl_util_set_notification_window_level() function. If the window type is not notification type, the function returns an error.

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

void create_win() 
{
   Evas_Object *eo;
   efl_util_error_e error;
   char *name = "Notification window";
   
   // Create notification window
   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
   if (!eo) return;
   
   // Set notification level
   error = efl_util_set_notification_window_level
           (eo, EFL_UTIL_NOTIFICATION_LEVEL_1);
   if (error != EFL_UTIL_ERROR_NONE)
   {
      // Do error handling
   }
}

Getting the Notification Window Level

To get the notification window level, use the efl_util_get_notification_window_level() function:

void create_win() 
{
   Evas_Object *eo;
   efl_util_error_e error;
   efl_util_notification_level_e notification_level;
   char *name = "Notification window";
   
   // Create notification window
   eo = elm_win_add(NULL, name, ELM_WIN_NOTIFICATION);
   if (!eo) return;
   
   // Get notification level
   error = efl_util_get_notification_window_level
           (eo, &notification_level);
   if (error == EFL_UTIL_ERROR_NONE) 
   {
      switch (notification_level) 
      {
         case EFL_UTIL_NOTIFICATION_LEVEL_1:
            // Do something for notification level 1
            break;
         case EFL_UTIL_NOTIFICATION_LEVEL_2:
            // Do something for notification level 2
            break;
      }
   }
}

Getting a Screenshot

To get a screenshot:

1. Initialize with the efl_util_screenshot_initialize() function:

   #include <tbm_surface.h>
   #include <X11/Xlib.h>
   
   void capture()
   {
      efl_util_screenshot_h screenshot = NULL;
      tbm_surface_h tbm_surface = NULL;
      tbm_surface_info_s tsuri;
   
      screenshot = efl_util_screenshot_initialize(width, height);
   

2. After getting the efl_util_screenshot_h structure, execute the efl_util_screenshot_take_tbm_surface() function to get the tbm_surface handler which has the screenshot data.

      if (screenshot) 
      {
         tbm_surface = efl_util_screenshot_take_tbm_surface(screenshot);
         if (tbm_surface) 
         {
            // Treat tbm_surface handler (screenshot data)
         }
   

3. Free the resources with the efl_util_screenshot_deinitialize() function:

         efl_util_screenshot_deinitialize(screenshot);
      }
   }

Generating a Key Input Event

To generate key input events:

1. Execute the efl_util_input_initialize_generator() function:

   void key_event_generator()
   {
      int ret = EFL_UTIL_ERROR_NONE;
      efl_util_inputgen_h inputgen = NULL;
   
      inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_KEYBOARD);
      if (!inputgen)
      {
         // Failed to initialize the input generator system
   
         return;
      }
   

2. After setting input device type, execute the efl_util_input_generate_key() function to generate key input events:

      ret = efl_util_input_generate_key(inputgen, "XF86Menu", 1);
      if (ret != EFL_UTIL_ERROR_NONE) 
      {
         // Failed to generate a "XF86Menu" key press event
         ret = efl_util_input_deinitialize_generator(inputgen);
         if (ret != EFL_UTIL_ERROR_NONE)
         {
            // Failed to deinitialize the input generator system
         }
   
         return;
      }
   
      ret = efl_util_input_generate_key(inputgen, "XF86Menu", 0);
      if (ret != EFL_UTIL_ERROR_NONE) 
      {
         // Failed to generate a "XF86Menu" key release event
         ret = efl_util_input_deinitialize_generator(inputgen);
         if (ret != EFL_UTIL_ERROR_NONE)
         {
            // Failed to deinitialize the input generator system
         }
   
         return;
      }
   

3. Free the resources with the efl_util_input_deinitialize_generator() function:

      ret = efl_util_input_deinitialize_generator(inputgen);
      if (ret != EFL_UTIL_ERROR_NONE)
      {
         // Failed to deinitialize the input generator system
      }
   }
   

Generating a Touch Input Event

To generate touch input events:

1. Execute the efl_util_input_initialize_generator() function:

   void touch_event_generator()
   {
      int ret = EFL_UTIL_ERROR_NONE;
      efl_util_inputgen_h inputgen = NULL;
   
      inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN);
      if (!inputgen)
      {
         // Failed to initialize the input generator system
   
         return;
      }
   

2. After setting input device type, execute the efl_util_input_generate_touch() function to generate touch input events:

      ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_BEGIN, 100, 100);
      if (ret != EFL_UTIL_ERROR_NONE) 
      {
         // Failed to generate a first finger touch press event on (100, 100)
         ret = efl_util_input_deinitialize_generator(inputgen);
         if (ret != EFL_UTIL_ERROR_NONE)
         {
            // Failed to deinitialize the input generator system
         }
   
         return;
      }
      ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_UPDATE, 110, 110);
      if (ret != EFL_UTIL_ERROR_NONE) 
      {
         // Failed to generate a first finger touch move event to (110, 110)
         ret = efl_util_input_deinitialize_generator(inputgen);
         if (ret != EFL_UTIL_ERROR_NONE)
         {
            // Failed to deinitialize the input generator system
         }
   
         return;
      }
      ret = efl_util_input_generate_touch(inputgen, 0, EFL_UTIL_INPUT_TOUCH_END, 110, 110);
      if (ret != EFL_UTIL_ERROR_NONE) 
      {
         // Failed to generate a first finger touch release event to (110, 110)
         ret = efl_util_input_deinitialize_generator(inputgen);
         if (ret != EFL_UTIL_ERROR_NONE)
         {
            // Failed to deinitialize the input generator system
         }
   
         return;
      }
   

3. Free the resources with the efl_util_input_deinitialize_generator() function:

      ret = efl_util_input_deinitialize_generator(inputgen);
      if (ret != EFL_UTIL_ERROR_NONE)
      {
         // Failed to deinitialize the input generator system
      }
   }