Efl Extension

The Efl Extension is an extension package for EFL that provides functions to work with the hardware keys and rotary events.

Working with Hardware Keys

Note
Hardware key events are only supported in mobile devices.

Normally, the key events are only delivered to the object in focus. However, with the EFL Extension functions, you can let visible objects without focus get events from the Menu and Back keys.

Figure: Menu and Back keys

The EFL Extension maintains its own object stack for determining which object to deliver events to. Only visible objects are added to this stack. The stack is based on the Evas layer. It means that if 2 objects are registered for the same EFL Extension event, the object on the higher Evas layer gets the event.

The following figure shows an example of objects and their layers. Objects 1, 2, and 3 are registered with EFL Extension callbacks for the same event, such as a Back key event. When the event occurs, object 3, which is on the highest layer (layer 3), gets the event callback.

Figure: Objects with layers

If objects stay on the same layer, the object which is registered to the callback first gets the event.

To register a callback for the Menu or Back key, use the eext_object_event_callback_add() function with the application callback type:

• EEXT_CALLBACK_BACK: Hardware Back key event
• EEXT_CALLBACK_MORE: Hardware Menu key event

To delete a registered event in the EFL Extension, use the eext_object_event_callback_del() function.

The EFL Extension also provides other convenient functions to work with the Menu and Back keys for popup, ctxpopup, naviframe, and entry components (in mobile and wearable applications).

Working with Rotary Events

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

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.

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 (in mobile and wearable applications).