Efl Extension: Creating a Naviframe Window

This tutorial demonstrates how you can handle hardware key and rotary events.

Warm-up

Become familiar with the Efl Extension, Elementary, and Evas API basics by learning about:

Initializing the EFL Extension
Initialize the EFL Extension for use.
Managing Hardware Key Events
Use the Menu and Back keys in your application.
Managing Rotary Events
Manage rotary events on a circular device.

Initializing the EFL Extension

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

#include <efl_extension.h>

Managing Hardware Key Events

Note
Hardware key events are only supported in mobile devices.

The application has a window that contains a naviframe and registers the EFL Extension Menu and Back key events for the naviframe.

When the Menu key is pressed, a popup is created and an EFL Extension Back key event for this popup is registered. If the popup is shown and the Back key is pressed, the popup is removed. Otherwise, if the Back key is pressed and there is no popup, the application is hidden.

To manage hardware key events:

Create objects using the window and naviframe:

static void
create_base_gui(appdata_s *ad)
{
   Evas_Object *win = NULL;

   // Create the window
   win = elm_win_util_standard_add(NULL, "extension sample");
   evas_object_smart_callback_add(win, "delete,request", _win_del, NULL);

   // Create the naviframe
   Evas_Object *nf = NULL;
   nf = elm_naviframe_add(win);
   evas_object_size_hint_weight_set(win, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(win, nf);
   evas_object_show(nf);

   // Content
   Evas_Object *label = NULL;
   label = elm_label_add(nf);
   elm_object_text_set(label, "Press menu key to show popup,<br/>back key to exit.");
   elm_naviframe_item_push(nf, "Efl Extension usage", NULL, NULL, label, NULL);

   // Show the window
   evas_object_show(win);
}

static void
create_base_gui(appdata_s *ad)
{
   // Register the EFL extension callbacks for Menu and Back key events
   eext_object_event_callback_add(nf, EEXT_CALLBACK_MORE, _create_popup, NULL);
   eext_object_event_callback_add(nf, EEXT_CALLBACK_BACK, _nf_back_cb, win);
}

Create a popup and register EFL Extension Back key event callbacks for it:

static void
_create_popup(void *data, Evas_Object *obj, void *event_info)
{
   Evas_Object *parent = obj;

   Evas_Object *popup = NULL, *content = NULL;
   popup = elm_popup_add(parent);
   elm_object_part_text_set(popup, "title,text", "Title");
   elm_popup_orient_set(popup, ELM_POPUP_ORIENT_CENTER);

   // Popup content
   content = elm_label_add(parent);
   elm_object_text_set(content, "Press back key to remove popup.");
   elm_object_content_set(popup, content);

   // Register the EFL extension callback for the Back key event
   eext_object_event_callback_add(popup, EEXT_CALLBACK_BACK, eext_popup_back_cb, NULL);
   evas_object_show(popup);
}

To remove the popup when a Back key event occurs, use the eext_popup_back_cb callback.

The callback function for menu key callback:

static void
_nf_back_cb(void *data, Evas_Object *obj, void *event_info)
{
   Evas_Object *win = data;

   // Hide the window
   elm_win_lower(win);
}

Managing Rotary Events

Note
Rotary events are only supported in devices with a circular screen.

To manage rotary events:

Create the rotary event handler:

Create the window:

static void
create_base_gui(appdata_s *ad)
{
Evas_Object *win = NULL;

   // Window
   win = elm_win_util_standard_add(NULL, "extension circle sample");
   elm_win_autodel_set(win, EINA_TRUE);
   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);

   // Show the window after base gui is set up
   evas_object_show(win);
}

static void
create_base_gui(appdata_s *ad)
{
   // Register the rotary event handler
   eext_rotary_event_handler_add(_rotary_handler_cb, NULL);
}

Define the callback function:

Eina_Bool _rotary_handler_cb(void *data, Eext_Rotary_Event_Info *ev)
{
   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
   {
      dlog_print(DLOG_DEBUG, LOG_TAG, "Rotary device rotated in clockwise direction");
   }
   else
   {
      dlog_print(DLOG_DEBUG, LOG_TAG, "Rotary device rotated in counter clockwise direction");
   }

   return EINA_FALSE;
}

Remove the rotary event handler and release all resources when you do not need it anymore.

static void
app_terminate(void *data)
{
   // Release all resources
   eext_rotary_event_handler_del(_rotary_handler_cb);
}

Create a rotary event callback for a normal Evas object.

When a rotary event occurs, the slider value is adjusted accordingly.

Create the objects.

The window and the slider are created using the Elementary APIs.

static void
create_base_gui(appdata_s *ad)
{
   Evas_Object *win = NULL, *slider = NULL;

   // Window 
   win = elm_win_util_standard_add(NULL, "extension sample");
   elm_win_autodel_set(win, EINA_TRUE);
   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);

   // Slider
   slider = elm_slider_add(win);
   evas_object_size_hint_weight_set(slider, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_slider_min_max_set(slider, 0, 50);
   elm_slider_step_set(slider, 1.0);
   evas_object_show(slider);
   elm_win_resize_object_add(win, slider);

   // Show the window after the base GUI is set up 
   evas_object_show(win);
}

To receive the rotary event, register the rotary event callback and set the activated object as the slider object.

static void
create_base_gui(appdata_s *ad)
{
   // Register rotary event callback 
   ext_rotary_object_event_callback_add(slider, _rotary_event_cb, NULL);
   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
}

Define the rotary callback function:

Eina_Bool _rotary_event_cb(void *data, Evas_Object *obj, Eext_Rotary_Event_Info *ev)
{
   Evas_Object *slider = obj;
   int val = elm_slider_value_get(slider);
   if (ev->direction == EEXT_ROTARY_DIRECTION_CLOCKWISE)
   {
      elm_slider_value_set(slider, val + 1);
   }
   else
   {
      elm_slider_value_set(slider, val - 1);
   }

   return EINA_FALSE;
}

Create a rotary event callback for an EFL Extension object.

When a rotary event occurs, the slider value is adjusted accordingly.

Create the objects:

static void
create_base_gui(appdata_s *ad)
{
   Evas_Object *win = NULL, *conform = NULL;
   Eext_Circle_Surface *sur = NULL;

   // Window 
   win = elm_win_util_standard_add(NULL, "extension circle sample");
   elm_win_autodel_set(win, EINA_TRUE);
   evas_object_smart_callback_add(win, "delete,request", win_delete_request_cb, NULL);

   // Conformant
   conform = elm_conformant_add(win);
   elm_win_indicator_mode_set(win, ELM_WIN_INDICATOR_SHOW);
   elm_win_indicator_opacity_set(win, ELM_WIN_INDICATOR_OPAQUE);
   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(win, conform);
   evas_object_show(conform);

   // Surface 
   sur = eext_circle_surface_conformant_add(conform);

   // Slider
   slider = eext_circle_object_slider_add(conform, sur);
   eext_circle_object_value_min_max_set(slider, 0.0, 30.0);
   eext_circle_object_value_set(slider, 0.0);

   // Show the window after the base GUI is set up
   evas_object_show(win);
}

Set the activated object.

Since the EFL Extension API is used to create the slider object, the created slider object already registers the rotary event callbacks internally. To receive a rotary event, you only need to set the activated object as the desired object (slider).

static void
create_base_gui(appdata_s *ad)
{
   // Activate circle slider's rotary object event
   // Its value increases/decreases its value by 1.0 to clockwise or 
   // counter-clockwise rotary event
   eext_rotary_object_event_activated_set(slider, EINA_TRUE);
   eext_circle_object_slider_step_set(slider, 1.0);
}