Managing Rotary Events

You can use various functions to work with the rotary events. The functions manage the rotary events, which are fired from the rotary device and delivered to a suitable target. To receive rotary events, you must define an event callback or a handler function, and register it using the EFL Extension functions. There are 2 ways to receive the rotary events: the rotary event handler and the rotary object event callback.

This feature is supported in wearable applications only.

Rotary Event Handler

The rotary event handler is suitable when you want to handle rotary events without taking care about an Evas Object or when the application is not implemented using an Evas Object. The handler works like the Ecore event in EFL:

The application registers a rotary event handler with the eext_rotary_event_handler_add() function.

The rotary event handlers are treated "first come first served". It means that the first registered handler is called first when rotary events happens. If the handler returns EINA_TRUE, the next handler is called. Otherwise, EFL Extension stops delivering the rotary events.
To remove a rotary event handler, use the eext_rotary_event_handler_del() function.

Rotary Object Event Callback

The rotary object event callback is suitable when you want EFL Extension to handle the event delivery between objects. It means that EFL Extension manages a callback and an object list and decides which object's callback must be called when rotary events happen:

The application registers a callback using the eext_rotary_object_event_callback_add() function.

EFL Extension treats callbacks based on the callback priority. If the application registers callbacks for a same object, the callback with the lowest priority number is called first. If this callback returns EINA_TRUE, the higher priority number is called. The above function registers the rotary event callback with a default priority number (value is 0). To register the rotary event callback with another priority number, use the eext_rotary_object_event_callback_priority_add() function.
To remove a registered callback from an object, use the eext_rotary_object_event_callback_del() function:

The rotary events are only delivered to 1 object named the activated object. If there is no activated object, the rotary event is not delivered to any object. If the activated object has registered callbacks and the callbacks return EINA_TRUE, the rotary events are delivered to the upper parents of the activated object until there is 1 callback that consumes the rotary event or it reaches the top parent object.

To set the object as the activated object, use the eext_rotary_object_event_activated_set() function.

Providing the activated parameter with the EINA_TRUE value sets the object as the activated object. Providing the EINA_FALSE value deactivates the object. Since there is only 1 object which is the activated object, if an object is set as the activated object, the previously activated object is deactivated and becomes a normal object. An activated signal named rotary,activated is sent when an object is set as the activated object, and the rotary,deactivated signal is sent when an object is deactivated.

You can register callbacks for activated or deactivated signals with the evas_object_smart_callback_add() function.

For more information, see the Evas smart callback function.

Managing Rotary Events

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 HANDLER: 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);
}