Focus

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

Enumerations | Functions
Focus

An Elementary application has, at all times, one (and only one) focused object. More...

## Enumerations
enum | Elm_Focus_Autoscroll_Mode { ELM_FOCUS_AUTOSCROLL_MODE_SHOW, ELM_FOCUS_AUTOSCROLL_MODE_NONE, ELM_FOCUS_AUTOSCROLL_MODE_BRING_IN }
| Focus Autoscroll Mode. More...
enum | Elm_Focus_Move_Policy { ELM_FOCUS_MOVE_POLICY_CLICK, ELM_FOCUS_MOVE_POLICY_IN }
| Focus Movement Policy. More...
enum | Elm_Focus_Direction { ELM_FOCUS_PREVIOUS, ELM_FOCUS_NEXT, ELM_FOCUS_UP, ELM_FOCUS_DOWN, ELM_FOCUS_RIGHT, ELM_FOCUS_LEFT }
| Focus directions. More...

## Functions
Elm_Focus_Autoscroll_Mode | elm_config_focus_autoscroll_mode_get (void)
| Get focus auto scroll mode. More...
void | elm_config_focus_autoscroll_mode_set (Elm_Focus_Autoscroll_Mode mode)
| Set focus auto scroll mode. More...
Eina_Bool | elm_config_focus_highlight_enabled_get (void)
| Get the enable status of the focus highlight. More...
void | elm_config_focus_highlight_enabled_set (Eina_Bool enable)
| Set the enable status of the focus highlight. More...
Eina_Bool | elm_config_focus_highlight_animate_get (void)
| Get the enable status of the focus highlight animation. More...
void | elm_config_focus_highlight_animate_set (Eina_Bool animate)
| Set the enable status of the highlight animation. More...
Eina_Bool | elm_config_focus_highlight_clip_disabled_get (void)
| Get the disable status of the focus highlight clip feature. More...
void | elm_config_focus_highlight_clip_disabled_set (Eina_Bool disable)
| Set the disable status of the focus highlight clip feature. More...
Elm_Focus_Move_Policy | elm_config_focus_move_policy_get (void)
| Get the focus movement policy. More...
void | elm_config_focus_move_policy_set (Elm_Focus_Move_Policy policy)
| Set elementary focus movement policy. More...
Eina_Bool | elm_config_item_select_on_focus_disabled_get (void)
| Get disable status of item select on focus feature. More...
void | elm_config_item_select_on_focus_disabled_set (Eina_Bool disabled)
| Set the disable status of the item select on focus feature. More...
Eina_Bool | elm_config_first_item_focus_on_first_focusin_get (void)
| Get status of first item focus on first focusin feature. More...
void | elm_config_first_item_focus_on_first_focusin_set (Eina_Bool enabled)
| Set the first item focus on first focusin feature. More...
Eina_Bool | elm_object_focus_get (const Evas_Object *obj)
| Get the whether an Elementary object has the focus or not. More...
void | elm_object_focus_set (Evas_Object *obj, Eina_Bool focus)
| Set/unset focus to a given Elementary object. More...
void | elm_object_focus_allow_set (Evas_Object *obj, Eina_Bool enable)
| Set the ability for an Elementary object to be focused. More...
Eina_Bool | elm_object_focus_allow_get (const Evas_Object *obj)
| Get whether an Elementary object is focusable or not. More...
void | elm_object_focus_custom_chain_set (Evas_Object *obj, Eina_List *objs)
| Set custom focus chain. More...
void | elm_object_focus_custom_chain_unset (Evas_Object *obj)
| Unset a custom focus chain on a given Elementary widget. More...
const Eina_List * | elm_object_focus_custom_chain_get (const Evas_Object *obj)
| Get custom focus chain. More...
void | elm_object_focus_custom_chain_append (Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child)
| Append object to custom focus chain. More...
void | elm_object_focus_custom_chain_prepend (Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child)
| Prepend object to custom focus chain. More...
void | elm_object_focus_next (Evas_Object *obj, Elm_Focus_Direction dir)
| Give focus to next object in object tree. More...
Evas_Object * | elm_object_focus_next_object_get (const Evas_Object *obj, Elm_Focus_Direction dir)
| Get next object which was set with specific focus direction. More...
void | elm_object_focus_next_object_set (Evas_Object *obj, Evas_Object *next, Elm_Focus_Direction dir)
| Set next object with specific focus direction. More...
Evas_Object * | elm_object_focused_object_get (const Evas_Object *obj)
| Get focused object in object tree. More...
void | elm_object_tree_focus_allow_set (Evas_Object *obj, Eina_Bool focusable)
| Make the elementary object and its children to be focusable (or unfocusable). More...
Eina_Bool | elm_object_tree_focus_allow_get (const Evas_Object *obj)
| Get whether an Elementary object and its children are focusable or not. More...
Eina_Bool | elm_object_focus_highlight_style_set (Evas_Object *obj, const char *style)
| Set the focus highlight style to be used by a given widget. More...
const char * | elm_object_focus_highlight_style_get (const Evas_Object *obj)
| Get the focus highlight style to be used by a given widget. More...
Elm_Object_Item * | elm_object_focused_item_get (const Evas_Object *obj)
| Get the focused object item. More...

## Detailed Description

An Elementary application has, at all times, one (and only one) focused object.

This is what determines where the input events go to within the application's window. Also, focused objects can be decorated differently, in order to signal to the user where the input is, at a given moment.

Elementary applications also have the concept of focus chain: one can cycle through all the windows' focusable objects by input (tab key) or programmatically. The default focus chain for an application is the one define by the order in which the widgets where added in code. One will cycle through top level widgets, and, for each one containing sub-objects, cycle through them all, before returning to the level above. Elementary also allows one to set custom focus chains for their applications.

Besides the focused decoration a widget may exhibit, when it gets focus, Elementary has a global focus highlight object that can be enabled for a window. If one chooses to do so, this extra highlight effect will surround the current focused object, too.

Note
  Some Elementary widgets are unfocusable, after creation, by their very nature: they are not meant to be interacted with input events, but are there just for visual purposes.

This example contemplates some of these functions.

## Enumeration Type Documentation

enum Elm_Focus_Autoscroll_Mode

Focus Autoscroll Mode.

Since
  1.10

Enumerator
ELM_FOCUS_AUTOSCROLL_MODE_SHOW | directly show the focused region or item automatically
ELM_FOCUS_AUTOSCROLL_MODE_NONE | do not show the focused region or item automatically
ELM_FOCUS_AUTOSCROLL_MODE_BRING_IN | bring_in the focused region or item automatically which might invole the scrolling

enum Elm_Focus_Direction

Focus directions.

Enumerator
ELM_FOCUS_PREVIOUS | previous direction
ELM_FOCUS_NEXT | next direction
ELM_FOCUS_UP | up direction
ELM_FOCUS_DOWN | down direction
ELM_FOCUS_RIGHT | right direction
ELM_FOCUS_LEFT | left direction

enum Elm_Focus_Move_Policy

Focus Movement Policy.

Since
  1.10

Enumerator
ELM_FOCUS_MOVE_POLICY_CLICK | move focus by mouse click or touch. Elementary focus is set on mouse click and this is checked at mouse up time. (default)
ELM_FOCUS_MOVE_POLICY_IN | move focus by mouse in. Elementary focus is set on mouse move when the mouse pointer is moved into an object.

## Function Documentation

Eina_Bool elm_config_first_item_focus_on_first_focusin_get | ( | void |  | ) |

Get status of first item focus on first focusin feature.

Returns
  The first item focus on first focusin status

See also
  elm_config_first_item_focus_on_first_focusin_set

Since
  1.11

void elm_config_first_item_focus_on_first_focusin_set | ( | Eina_Bool | enabled | ) |

Set the first item focus on first focusin feature.

Parameters

  enabled | first_item_focus_on_first_focusin if `EINA_TRUE`, enable otherwise

See also
  elm_config_first_item_focus_on_first_focusin_get

Since
  1.11

Elm_Focus_Autoscroll_Mode elm_config_focus_autoscroll_mode_get | ( | void |  | ) |

Get focus auto scroll mode.

When a region or an item is focused and it resides inside any scroller, elementary will automatically scroll the focused area to the visible viewport.

See also
  elm_config_focus_autoscroll_mode_set()

Since
  1.10

void elm_config_focus_autoscroll_mode_set | ( | Elm_Focus_Autoscroll_Mode | mode | ) |

Set focus auto scroll mode.

Parameters

  mode | focus auto scroll mode. This can be one of the Elm_Focus_Autoscroll_Mode enum values.

When a region or an item is focused and it resides inside any scroller, elementary will automatically scroll the focused area to the visible viewport. Focus auto scroll mode is set to ELM_FOCUS_AUTOSCROLL_MODE_SHOW by default historically.

See also
  elm_config_focus_autoscroll_mode_get()

Since
  1.10

Eina_Bool elm_config_focus_highlight_animate_get | ( | void |  | ) |

Get the enable status of the focus highlight animation.

Returns
  animate `EINA_TRUE` if the focus highlight animation is enabled, `EINA_FALSE` otherwise.

Get whether the focus highlight, if enabled, will animate its switch from one object to the next

See also
  elm_config_focus_highlight_animate_set()

void elm_config_focus_highlight_animate_set | ( | Eina_Bool | animate | ) |

Set the enable status of the highlight animation.

Parameters

  animate | Enable animation if `EINA_TRUE`, disable otherwise

Set whether the focus highlight, if enabled, will animate its switch from one object to the next

Note that it will take effect only to Elementary windows created after this is called.

See also
  elm_config_focus_highlight_animate_get()

Eina_Bool elm_config_focus_highlight_clip_disabled_get | ( | void |  | ) |

Get the disable status of the focus highlight clip feature.

Returns
  The focus highlight clip disable status

Get whether the focus highlight clip feature is disabled. If disabled return `EINA_TRUE`, else return `EINA_FALSE`. If the return is `EINA_TRUE`, focus highlight clip feature is not disabled so the focus highlight can be clipped.

See also
  elm_config_focus_highlight_clip_disabled_set()

Since
  1.10

void elm_config_focus_highlight_clip_disabled_set | ( | Eina_Bool | disable | ) |

Set the disable status of the focus highlight clip feature.

Parameters

  disable | Disable focus highlight clip feature if `EINA_TRUE`, enable it otherwise.

See also
  elm_config_focus_highlight_clip_disabled_get()

Since
  1.10

Eina_Bool elm_config_focus_highlight_enabled_get | ( | void |  | ) |

Get the enable status of the focus highlight.

This gets whether the highlight on focused objects is enabled or not

Returns
  enable `EINA_TRUE` if the focus highlight is enabled, `EINA_FALSE` otherwise.

See also
  elm_config_focus_highlight_enabled_set()

void elm_config_focus_highlight_enabled_set | ( | Eina_Bool | enable | ) |

Set the enable status of the focus highlight.

Parameters

  enable | Enable highlight if `EINA_TRUE`, disable otherwise

Set whether to show or not the highlight on focused objects

Note that it will take effect only to Elementary windows created after this is called.

See also
  elm_config_focus_highlight_enabled_get()

Elm_Focus_Move_Policy elm_config_focus_move_policy_get | ( | void |  | ) |

Get the focus movement policy.

Returns
  The focus movement policy

Get how the focus is moved to another object. It can be ELM_FOCUS_MOVE_POLICY_CLICK or ELM_FOCUS_MOVE_POLICY_IN. The first means elementary focus is moved on elementary object click. The second means elementary focus is moved on elementary object mouse in.

See also
  elm_config_focus_move_policy_set()

Since
  1.10

void elm_config_focus_move_policy_set | ( | Elm_Focus_Move_Policy | policy | ) |

Set elementary focus movement policy.

Parameters

  policy | A policy to apply for the focus movement

See also
  elm_config_focus_move_policy_get()

Since
  1.10

Eina_Bool elm_config_item_select_on_focus_disabled_get | ( | void |  | ) |

Get disable status of item select on focus feature.

Returns
  The item select on focus disable status

See also
  elm_config_item_select_on_focus_disabled_set

Since
  1.10

void elm_config_item_select_on_focus_disabled_set | ( | Eina_Bool | disabled | ) |

Set the disable status of the item select on focus feature.

Parameters

  disabled | Disable item select on focus if `EINA_TRUE`, enable otherwise

See also
  elm_config_item_select_on_focus_disabled_get

Since
  1.10

Eina_Bool elm_object_focus_allow_get | ( | const Evas_Object * | obj | ) |

Get whether an Elementary object is focusable or not.

Parameters

  obj | The Elementary object to operate on

Returns
  `EINA_TRUE` if the object is allowed to be focused, `EINA_FALSE` if not (and on errors)

Note
  Objects which are meant to be interacted with by input events are created able to be focused, by default. All the others are not.

void elm_object_focus_allow_set | ( | Evas_Object * | obj,
|  | Eina_Bool | enable
| ) |  |

Set the ability for an Elementary object to be focused.

Parameters

  obj | The Elementary object to operate on
  enable | `EINA_TRUE` if the object can be focused, `EINA_FALSE` if not (and on errors)

This sets whether the object `obj` is able to take focus or not. Unfocusable objects do nothing when programmatically focused, being the nearest focusable parent object the one really getting focus. Also, when they receive mouse input, they will get the event, but not take away the focus from where it was previously.

Examples:
  general_funcs_example.c.

void elm_object_focus_custom_chain_append | ( | Evas_Object * | obj,
|  | Evas_Object * | child,
|  | Evas_Object * | relative_child
| ) |  |

Append object to custom focus chain.

Note
  If relative_child equal to NULL or not in custom chain, the object will be added in end.
  On focus cycle, only will be evaluated children of this container.

Parameters

  obj | The container object
  child | The child to be added in custom chain
  relative_child | The relative object to position the child

const Eina_List* elm_object_focus_custom_chain_get | ( | const Evas_Object * | obj | ) |

Get custom focus chain.

Parameters

  obj | The container object

void elm_object_focus_custom_chain_prepend | ( | Evas_Object * | obj,
|  | Evas_Object * | child,
|  | Evas_Object * | relative_child
| ) |  |

Prepend object to custom focus chain.

Note
  If relative_child equal to NULL or not in custom chain, the object will be added in begin.
  On focus cycle, only will be evaluated children of this container.

Parameters

  obj | The container object
  child | The child to be added in custom chain
  relative_child | The relative object to position the child

void elm_object_focus_custom_chain_set | ( | Evas_Object * | obj,
|  | Eina_List * | objs
| ) |  |

Set custom focus chain.

This function overwrites any previous custom focus chain within the list of objects. The previous list will be deleted and this list will be managed by elementary. After it is set, don't modify it.

Note
  On focus cycle, only will be evaluated children of this container.

Parameters

  obj | The container object
  objs | Chain of objects to pass focus

void elm_object_focus_custom_chain_unset | ( | Evas_Object * | obj | ) |

Unset a custom focus chain on a given Elementary widget.

Parameters

  obj | The container object to remove focus chain from

Any focus chain previously set on `obj` (for its child objects) is removed entirely after this call.

Eina_Bool elm_object_focus_get | ( | const Evas_Object * | obj | ) |

Get the whether an Elementary object has the focus or not.

Parameters

  obj | The Elementary object to get the information from

Returns
  `EINA_TRUE`, if the object is focused, `EINA_FALSE` if not (and on errors).

See also
  elm_object_focus_set()

const char* elm_object_focus_highlight_style_get | ( | const Evas_Object * | obj | ) |

Get the focus highlight style to be used by a given widget.

Parameters

  obj | The Elementary widget to query for its focus highlight style.

Returns
  The focus highlight style name used by widget.

See also
  elm_object_focus_highlight_style_set()

Since
  1.9

Eina_Bool elm_object_focus_highlight_style_set | ( | Evas_Object * | obj,
|  | const char * | style
| ) |  |

Set the focus highlight style to be used by a given widget.

Parameters

  obj | The Elementary widget for which focus style needs to be set.
  style | The name of the focus style to use on it.

Returns
  `EINA_TRUE` on success, `EINA_FALSE` otherwise.

Note
  This overrides the style which is set by elm_win_focus_highlight_style_set().

See also
  elm_object_focus_highlight_style_get

Since
  1.9

void elm_object_focus_next | ( | Evas_Object * | obj,
|  | Elm_Focus_Direction | dir
| ) |  |

Give focus to next object in object tree.

Give focus to next object in focus chain of one object sub-tree. If the last object of chain already have focus, the focus will go to the first object of chain.

Parameters

  obj | The object root of sub-tree
  dir | Direction to move the focus

See also
  elm_object_focus_next_object_get(), elm_object_focus_next_object_set()

Evas_Object* elm_object_focus_next_object_get | ( | const Evas_Object * | obj,
|  | Elm_Focus_Direction | dir
| ) |  |

Get next object which was set with specific focus direction.

Get next object which was set by elm_object_focus_next_object_set with specific focus direction.

Parameters

  obj | The Elementary object
  dir | Focus direction

Returns
  Focus next object or `NULL`, if there is no focus next object.

See also
  elm_object_focus_next_object_set(), elm_object_focus_next()

Since
  1.8

void elm_object_focus_next_object_set | ( | Evas_Object * | obj,
|  | Evas_Object * | next,
|  | Elm_Focus_Direction | dir
| ) |  |

Set next object with specific focus direction.

When focus next object is set with specific focus direction, this object will be the first candidate when finding next focusable object. Focus next object can be registered with six directions that are previous, next, up, down, right, and left.

Parameters

  obj | The Elementary object
  next | Focus next object
  dir | Focus direction

See also
  elm_object_focus_next_object_get(), elm_object_focus_next()

Since
  1.8

void elm_object_focus_set | ( | Evas_Object * | obj,
|  | Eina_Bool | focus
| ) |  |

Set/unset focus to a given Elementary object.

Parameters

  obj | The Elementary object to operate on.
  focus | `EINA_TRUE` Set focus to a given object, `EINA_FALSE` Unset focus to a given object.

Note
  When you set focus to this object, if it can handle focus, will take the focus away from the one who had it previously and will, for now on, be the one receiving input events. Unsetting focus will remove the focus from `obj`, passing it back to the previous element in the focus chain list.

Warning
  Only visible object can get a focus. Call evas_object_show(o) before calling this API, if you want to give a focus to the evas object.

See also
  elm_object_focus_get(), elm_object_focus_custom_chain_get()

Examples:
  entry_example.c, general_funcs_example.c, glview_example_01.c, and web_example_02.c.

References ELM_FOCUS_NEXT, and elm_win_inlined_image_object_get().

Elm_Object_Item* elm_object_focused_item_get | ( | const Evas_Object * | obj | ) |

Get the focused object item.

This returns the focused object item.

Parameters

  obj | The container object

Returns
  The focused item, or `NULL` if none

The focused item can be unfocused with function elm_object_item_focus_set().

see () see ()

Since
  1.10

Evas_Object* elm_object_focused_object_get | ( | const Evas_Object * | obj | ) |

Get focused object in object tree.

This function returns current focused object in one object sub-tree.

Parameters

  obj | The object root of sub-tree

Returns
  Current focused or `NULL`, if there is no focused object.

Since
  1.8

Eina_Bool elm_object_tree_focus_allow_get | ( | const Evas_Object * | obj | ) |

Get whether an Elementary object and its children are focusable or not.

Parameters

  obj | The Elementary object to get the information from

Returns
  `EINA_TRUE`, if the tree is focusable, `EINA_FALSE` if not (and on errors).

See also
  elm_object_tree_focus_allow_set()

void elm_object_tree_focus_allow_set | ( | Evas_Object * | obj,
|  | Eina_Bool | focusable
| ) |  |

Make the elementary object and its children to be focusable (or unfocusable).

Parameters

  obj | The Elementary object to operate on
  focusable | `EINA_TRUE` for focusable, `EINA_FALSE` for unfocusable.

This sets whether the object `obj` and its children objects are able to take focus or not. If the tree is set as unfocusable, newest focused object which is not in this tree will get focus. This API can be helpful for an object to be deleted. When an object will be deleted soon, it and its children may not want to get focus (by focus reverting or by other focus controls). Then, just use this API before deleting.

See also
  elm_object_tree_focus_allow_get()