+ +

EFL Utilities

+ +

You can take advantage of various EFL utilities in your application:

+ +

Managing notification windows +
A window that belongs to the notification layer within the Tizen window layer hierarchy is called a "notification window". You can create notification windows and access their current notification levels (as long as they are of the EFL window type) using the EFL UTIL API (for mobile and wearable applications).
Taking screenshots +
You can capture screenshots and store the screenshot data as a TBM surface, using the EFL UTIL SCREENSHOT API (for mobile and wearable applications).
Using the input generator +
You can generate input events using the EFL UTIL INPUT API (for mobile and wearable applications). You can generate key input events that emulate various hardware key presses and touch input events that emulate screen touches.

+ +

Window Layers and Notification Levels

+ +

Tizen windows have a 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

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, for 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.

+ +

The notification layer contains 3 levels, which define the priority of a notification window:

EFL_UTIL_NOTIFICATION_LEVEL_1: Default level, to which most windows are set. It is used as a normal notification popup.
EFL_UTIL_NOTIFICATION_LEVEL_2: Higher level; the windows on this level are always on top of the level 1 windows. It is used for the lock screen window in general.
EFL_UTIL_NOTIFICATION_LEVEL_3: Highest level, which very few applications can use. It is used in case the user needs to be notified in any circumstances. For example, the incoming call popup uses this level.

+ +

Figure: Notification levels

Notification levels

+ + +

Prerequisites

+ +

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

+#include <efl_util.h>
+

+ +

Managing Notification Windows

+ +

To create notification windows and access the current notification level of an existing notification window:

+ +

Create a notification window with the default notification level (EFL_UTIL_NOTIFICATION_LEVEL_1): + +

To create a new window and give it the NOTIFICATION type, call the elm_win_add() function with the third parameter set to ELM_WIN_NOTIFICATION: +

+#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;
+

To set the notification level, call the efl_util_set_notification_window_level() function: +

+    /* 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;
+}
+

Get the currently set notification level of a window by using the efl_util_get_notification_window_level() function. +

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 */
+    }
+}
+

+ + +

Taking Screenshots

+ +

To take a screenshot:

+ +

Create the efl_util_screenshot_h structure and initialize the structure members 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);
+

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: +

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

When no longer needed, free the efl_util_screenshot_h structure with the efl_util_screenshot_deinitialize() function: +
```
+        efl_util_screenshot_deinitialize(screenshot);
+    }
+}
+
```

+ + + +

Generating Key Input Events

+ +

To generate key input events:

+ +

Create the efl_util_inputgen_h structure and initialize the structure members with the efl_util_input_initialize_generator() or efl_util_input_initialize_generator_with_name() function: +

+void
+key_event_generator()
+{
+    int ret = EFL_UTIL_ERROR_NONE;
+    efl_util_inputgen_h inputgen = NULL;
+
+    /* Create an input device with the default name: "Input Generator" */
+    inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_KEYBOARD);
+    /*
+       Since Tizen 4.0, you can create an input generator with a given name (in this example, "Local Device"):
+       inputgen = efl_util_input_initialize_generator_with_name(EFL_UTIL_INPUT_DEVTYPE_KEYBOARD, "Local_Device");
+    */
+    if (!inputgen) {
+        /* Failed to initialize the input generator system */
+
+        return;
+    }
+

After setting the input device type, call 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;
+    }
+

When no longer needed, free the efl_util_inputgen_h structure 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 Touch Input Events

+ +

To generate touch input events:

+ +

Create the efl_util_inputgen_h structure and initialize the structure members with the efl_util_input_initialize_generator() or efl_util_input_initialize_generator_with_name() function: +

+void
+touch_event_generator()
+{
+    int ret = EFL_UTIL_ERROR_NONE;
+    efl_util_inputgen_h inputgen = NULL;
+
+    /* Create an input device with the default name: "Input Generator" */
+    inputgen = efl_util_input_initialize_generator(EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN);
+    /*
+       Since Tizen 4.0, you can create an input device with a given name (in this example, "Local Device"):
+       inputgen = efl_util_input_initialize_generator_with_name(EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN, "Local_Device");
+    */
+    if (!inputgen) {
+        /* Failed to initialize the input generator system */
+
+        return;
+    }
+

After setting the input device type, call 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 on (110, 110) */
+        ret = efl_util_input_deinitialize_generator(inputgen);
+        if (ret != EFL_UTIL_ERROR_NONE)
+            /* Failed to deinitialize the input generator system */
+
+        return;
+    }
+

When no longer needed, free the efl_util_inputgen_h structure 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 */
+}
+

+ + + + +