This group provides functions to handle Elementary Focus.

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 defined by the order in which the widgets are added in the code. One cycles through the top level widgets, and, for each one containing sub-object, 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 that 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 surrounds the current focused object, too.

Remarks:: 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. *

Functions
Eina_Bool	elm_object_focus_get (const Evas_Object *obj)
	Gets whether an Elementary object has the focus.
void	elm_object_focus_set (Evas_Object *obj, Eina_Bool focus)
	Sets or unsets focus to a given Elementary object.
void	elm_object_focus_allow_set (Evas_Object *obj, Eina_Bool enable)
	Sets the ability for an Elementary object to be focused.
Eina_Bool	elm_object_focus_allow_get (const Evas_Object *obj)
	Gets whether an Elementary object is focusable.
void	elm_object_focus_custom_chain_set (Evas_Object obj, Eina_List objs)
	Sets the custom focus chain.
void	elm_object_focus_custom_chain_unset (Evas_Object *obj)
	Unsets a custom focus chain on a given Elementary widget.
const Eina_List *	elm_object_focus_custom_chain_get (const Evas_Object *obj)
	Gets the custom focus chain.
void	elm_object_focus_custom_chain_append (Evas_Object obj, Evas_Object child, Evas_Object *relative_child)
	Appends an object to the custom focus chain.
void	elm_object_focus_custom_chain_prepend (Evas_Object obj, Evas_Object child, Evas_Object *relative_child)
	Prepends an object to the custom focus chain.
void	elm_object_focus_next (Evas_Object *obj, Elm_Focus_Direction dir)
	Gives focus to the next object in the object tree.
Evas_Object *	elm_object_focus_next_object_get (const Evas_Object *obj, Elm_Focus_Direction dir)
	Gets the next object that is set with a specific focus direction.
void	elm_object_focus_next_object_set (Evas_Object obj, Evas_Object next, Elm_Focus_Direction dir)
	Sets the next object with a specific focus direction.
Evas_Object *	elm_object_focused_object_get (const Evas_Object *obj)
	Gets the focused object in the object tree.
void	elm_object_tree_focus_allow_set (Evas_Object *obj, Eina_Bool focusable)
	Makes the elementary object and its children to be focusable (or unfocusable).
Eina_Bool	elm_object_tree_focus_allow_get (const Evas_Object *obj)
	Gets whether an Elementary object and its children are focusable.
Typedefs
typedef struct _Elm_Focus_Info	Elm_Focus_Info
	The structure type containing the info sent in the callback for the "focused" signals.

Enumeration Type Documentation

enum Elm_Focus_Direction

Enumeration that defines the 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

Function Documentation

Eina_Bool elm_config_focus_highlight_animate_get ( void )

Gets the enable status of the highlight animation.

This gets whether the focus highlight, if enabled, animates its switch from one object to the next.

Since :: 2.3.1

Returns:: The focus highlight mode set

void elm_config_focus_highlight_animate_set ( Eina_Bool animate )

Sets the enable status of the highlight animation.

This sets whether the focus highlight, if enabled, animates its switch from one object to the next.

Since :: 2.3.1

Remarks:: Note that it takes effect only on Elementary windows created after this is called.

Parameters:

[in] animate If EINA_TRUE it enables animation, otherwise EINA_FALSE disables it

See also:: elm_win_add()

Eina_Bool elm_config_focus_highlight_enabled_get ( void )

Gets the enable status of the focus highlight.

This gets whether the highlight on the focused objects is enabled.

Returns:: The status of the focus highlight

Since :: 2.3.1

See also:: elm_config_focus_highlight_enabled_set()

void elm_config_focus_highlight_enabled_set ( Eina_Bool enable )

Sets the enable status of the focus highlight.

This sets whether to show the highlight on focused objects or not.

Since :: 2.3.1

Remarks:: Note that it takes effect only on Elementary windows created after this is called.

Parameters:

[in] enable If EINA_TRUE it enables highlight, otherwise EINA_FALSE disables highlight

See also:: elm_win_add()

Eina_Bool elm_object_focus_allow_get ( const Evas_Object * obj )

Gets whether an Elementary object is focusable.

Since :: 2.3.1

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

Parameters:

[in] obj The Elementary object to operate on

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

void elm_object_focus_allow_set	(	Evas_Object *	obj,
		Eina_Bool	enable
	)

Sets the ability for an Elementary object to be focused.

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 get the event, but do not take away the focus from where it is previously.

Since :: 2.3.1

Parameters:

[in]	obj	The Elementary object to operate on
[in]	enable	If `EINA_TRUE` the object can be focused, otherwise `EINA_FALSE` if it cannot (and on errors)

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

Appends an object to the custom focus chain.

Since :: 2.3.1

Remarks:: If relative_child is equal to NULL or not in the custom chain, the object is added in the end.; On the focus cycle, there are only evaluated children of this container.

Parameters:

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

const Eina_List* elm_object_focus_custom_chain_get ( const Evas_Object * obj )

Gets the custom focus chain.

Since :: 2.3.1

Parameters:

[in] obj The container object

Returns:: The focus custom chain list

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

Prepends an object to the custom focus chain.

Since :: 2.3.1

Remarks:: If relative_child is equal to NULL or not in custom chain, the object is added in the beginning.; On the focus cycle, there are only evaluated children of this container.

Parameters:

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

void elm_object_focus_custom_chain_set	(	Evas_Object *	obj,
		Eina_List *	objs
	)

Sets the custom focus chain.

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

Since :: 2.3.1

Remarks:: On the focus cycle, there are only evaluated children of this container.

Parameters:

[in]	obj	The container object
[in]	objs	The chain of objects to pass focus to

void elm_object_focus_custom_chain_unset ( Evas_Object * obj )

Unsets a custom focus chain on a given Elementary widget.

Since :: 2.3.1

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

Parameters:

[in] obj The container object to remove the focus chain from

Eina_Bool elm_object_focus_get ( const Evas_Object * obj )

Gets whether an Elementary object has the focus.

Since :: 2.3.1

Parameters:

[in] obj The Elementary object to get the information from

Returns:: EINA_TRUE if the object is focused, otherwise EINA_FALSE if not (and on errors)

See also:: elm_object_focus_set()

void elm_object_focus_next	(	Evas_Object *	obj,
		Elm_Focus_Direction	dir
	)

Gives focus to the next object in the object tree.

This gives focus to the next object in the focus chain of one the object sub-tree. If the last object of the chain already has focus, the focus goes to the first object of the chain.

Since :: 2.3.1

Parameters:

[in]	obj	The object root of the sub-tree
[in]	dir	The 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
	)

Gets the next object that is set with a specific focus direction.

This gets the next object that is set by elm_object_focus_next_object_set() with a specific focus direction.

Since (EFL) :: 1.8

Since :: 2.3.1

Parameters:

[in]	obj	The Elementary object
[in]	dir	The focus direction

Returns:: The focus next object, otherwise NULL if there is no focus next object

See also:: elm_object_focus_next_object_set(); elm_object_focus_next()

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

Sets the next object with a specific focus direction.

Since (EFL) :: 1.8

Since :: 2.3.1

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

Parameters:

[in]	obj	The Elementary object
[in]	next	The focus next object
[in]	dir	The focus direction

See also:: elm_object_focus_next_object_get(); elm_object_focus_next()

void elm_object_focus_set	(	Evas_Object *	obj,
		Eina_Bool	focus
	)

Sets or unsets focus to a given Elementary object.

Since :: 2.3.1

Remarks:: When you set focus to this object, if it can handle focus, it takes the focus away from the one who had it previously and, from now on, becomes the one receiving input events. Unsetting focus removes the focus from obj, passing it back to the previous element in the focus chain list.

Parameters:

[in]	obj	The Elementary object to operate on
[in]	focus	If `EINA_TRUE` the focus to a given object is set, otherwise `EINA_FALSE` to unset the focus to a given object

See also:: elm_object_focus_get(); elm_object_focus_custom_chain_get()

Evas_Object* elm_object_focused_object_get ( const Evas_Object * obj )

Gets the focused object in the object tree.

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

Since :: 2.3.1

Since (EFL) :: 1.8

Parameters:

obj	The object root of the sub-tree

Returns:: The current focused object, otherwise NULL if there is no focused object

Eina_Bool elm_object_tree_focus_allow_get ( const Evas_Object * obj )

Gets whether an Elementary object and its children are focusable.

Since :: 2.3.1

Parameters:

[in] obj The Elementary object to get the information from

Returns:: EINA_TRUE, if the tree is focusable, otherwise EINA_FALSE if it is 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
	)

Makes the elementary object and its children to be focusable (or 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, the newest focused object which is not in this tree gets focus. This API can be helpful for an object to be deleted. When an object is deleted soon, the object and its children may not want to get focus (by focus reverting or by other focus controls). Then, just use this API before deleting.

Since :: 2.3.1

Parameters:

[in]	obj	The Elementary object to operate on
[in]	focusable	If `EINA_TRUE` it is focusable, otherwise `EINA_FALSE` if it is unfocusable

See also:: elm_object_tree_focus_allow_get()

Functions

Typedefs

Enumeration Type Documentation

Function Documentation