Managing UI Component Focus
Focus is a common UI concept, which refers to the state of the currently selected or otherwise active UI component on the screen. A UI component is focused when it is selected to receive an input event, such as a mouse button click or key press, from the user. A UI component application has, at all times, only 1 focused object to determine where the input event goes to within the application window.
Focused objects can be highlighted or decorated in a specific way to signal to the user where the focus is at any given moment.
There are 2 main ways to set focus on a graphical element:
Direct (immediate) selection
The user performs this selection by clicking an element using the touch screen or mouse.
Direct selection does not really need any kind of special treatment, as the user explicitly selects the UI component to interact with.
The user performs this selection by pressing a key.
In the relative selection, the key press moves the current selection from one UI component to another, such as going to the previous or next one.
An object can be focused if all of the following conditions apply:
Object is visible
Object is enabled
Object accepts focus
To set an object as focusable, or to determine whether the object is focusable, use the
Object’s subtree (if any) is focusable
To set an object and its children as focusable, or to determine whether the object and its children are focusable, use the
All of the subtrees in the object’s parents are focusable
If any of these conditions do not apply, the object is unfocusable.
To manage focusable objects:
- To determine whether a specific object is focused, use the
- To set the focus to an object:
Show the object on the screen with the
Set the focus with the
The second parameter is a Boolean value: if it is set to
EINA_TRUE, the focus is set to the given object; if it is set to
EINA_FALSE, the focus is unset and passed back to the previous element in the focus chain.
- When a focused UI component is hidden, deleted, or disabled, it becomes unfocusable, and the focus is automatically moved to another object.
- To monitor when the object receives or loses focus, register the
unfocusedsmart event and define a callback.
The order in which the focus moves from one UI component to another is called the focus chain. The default focus chain is the order in which the UI components have been added to the canvas.
If the components are added programmatically in a different order than they appear on the screen, the default focus chain can be quite confusing. In that case, you must customize the focus chain to make it work as expected.
When the user wants to switch the focus to the next object, Elementary searches for the first focusable object in the focus chain. If there is a disabled or read-only object in the focus chain, the focus skips over it to the next object in the requested direction.
When the focus is changed using key presses, Elementary handles the key presses automatically. According to which key is pressed, Elementary switches the focus to the selected direction. For example, if the user presses the Tab key, the focus moves to the next object in the natural (default focus chain) order. On the other hand, if the user presses the direction keys, the focus moves to the next object in the requested direction.
Customizing the Focus Chain
There can be several reasons for customizing the focus chain of an application. For example:
- If you have created a form with labels and text entries next to them, you want the focus to move to the entry field when the user clicks the associated label.
- If you have created an interface with several columns (a table), you can set the focus chain as you wish, for example, going horizontally instead of vertically, regardless of the order in which the UI components are added.
To customize the focus chain:
Customizing the object-specific focus exit (where the focus moves to after a specific object)
You can define where the focus moves from a specific object by using the
elm_object_focus_next_object_set()function. The third parameter is the move direction, which can be one of the following:
ELM_FOCUS_NEXT: Next UI component in the natural order
ELM_FOCUS_PREVIOUS: Previous UI component in the natural order
ELM_FOCUS_UP: UI component to focus when moving up
ELM_FOCUS_DOWN: UI component to focus when moving down
ELM_FOCUS_RIGHT: UI component to focus when moving right
ELM_FOCUS_LEFT: UI component to focus when moving left
Get the next object in a specific direction using the
Customizing the entire application’s focus chain
To customize the application’s focus chain:
Evas_Object *main; Evas_Object obj1; Evas_Object obj2; Evas_Object obj3; Evas_Object obj4; Evas_Object obj5; Eina_List *focus_chain = NULL; focus_chain = eina_list_append(focus_chain, obj3); focus_chain = eina_list_append(focus_chain, obj2); /* Chain is obj3 followed by obj2. Set the chain */ elm_object_focus_custom_chain_set(main, focus_chain); /* Prepend obj5 at the beginning of the chain */ elm_object_focus_custom_chain_prepend(main, obj5, NULL); /* Append obj1 after obj3 */ elm_object_focus_custom_chain_append(main, obj1, obj3); /* Prepend obj4 before obj1 */ elm_object_focus_custom_chain_prepend(main, obj4, obj1);
The focus chain is
obj5, obj3, obj4, obj1, obj2.
This applies to any container. It is possible to set the focus chain of a box, for example.
The object-specific focus exit overrides the application’s focus chain. This means that if an object is part of a focus chain and, in addition, has the next focused object defined, the next object takes precedence over the focus chain.
Consider the above focus chain example: if
obj5defined as its next object, the actual focus chain is
obj5, obj3, obj4, obj5(the chain loops back to
obj4instead of moving on the
obj1, as defined in the application focus chain).
If an Evas object has several sub-objects, set its focus chain using the same functions as for the application. Elementary first follows the main focus chain, and then the focus chain of each UI component, as applicable.
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable