2 * @defgroup Focus Focus
5 * An Elementary application has, at all times, one (and only one)
6 * @b focused object. This is what determines where the input
7 * events go to within the application's window. Also, focused
8 * objects can be decorated differently, in order to signal to the
9 * user where the input is, at a given moment.
11 * Elementary applications also have the concept of <b>focus
12 * chain</b>: one can cycle through all the windows' focusable
13 * objects by input (tab key) or programmatically. The default
14 * focus chain for an application is the one define by the order in
15 * which the widgets where added in code. One will cycle through
16 * top level widgets, and, for each one containing sub-objects, cycle
17 * through them all, before returning to the level
18 * above. Elementary also allows one to set @b custom focus chains
19 * for their applications.
21 * Besides the focused decoration a widget may exhibit, when it
22 * gets focus, Elementary has a @b global focus highlight object
23 * that can be enabled for a window. If one chooses to do so, this
24 * extra highlight effect will surround the current focused object,
27 * @note Some Elementary widgets are @b unfocusable, after
28 * creation, by their very nature: they are not meant to be
29 * interacted with input events, but are there just for visual
32 * @ref general_functions_example_page "This" example contemplates
33 * some of these functions.
43 ELM_FOCUS_PREVIOUS, /**< previous direction */
44 ELM_FOCUS_NEXT, /**< next direction */
45 ELM_FOCUS_UP, /**< up direction */
46 ELM_FOCUS_DOWN, /**< down direction */
47 ELM_FOCUS_RIGHT, /**< right direction */
48 ELM_FOCUS_LEFT /**< left direction */
49 } Elm_Focus_Direction;
52 * Get the whether an Elementary object has the focus or not.
54 * @param obj The Elementary object to get the information from
55 * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if
56 * not (and on errors).
58 * @see elm_object_focus_set()
62 EAPI Eina_Bool elm_object_focus_get(const Evas_Object *obj);
65 * Set/unset focus to a given Elementary object.
67 * @param obj The Elementary object to operate on.
68 * @param focus @c EINA_TRUE Set focus to a given object,
69 * @c EINA_FALSE Unset focus to a given object.
71 * @note When you set focus to this object, if it can handle focus, will
72 * take the focus away from the one who had it previously and will, for
73 * now on, be the one receiving input events. Unsetting focus will remove
74 * the focus from @p obj, passing it back to the previous element in the
77 * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
81 EAPI void elm_object_focus_set(Evas_Object *obj, Eina_Bool focus);
84 * Set the ability for an Elementary object to be focused
86 * @param obj The Elementary object to operate on
87 * @param enable @c EINA_TRUE if the object can be focused, @c
88 * EINA_FALSE if not (and on errors)
90 * This sets whether the object @p obj is able to take focus or
91 * not. Unfocusable objects do nothing when programmatically
92 * focused, being the nearest focusable parent object the one
93 * really getting focus. Also, when they receive mouse input, they
94 * will get the event, but not take away the focus from where it
99 EAPI void elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable);
102 * Get whether an Elementary object is focusable or not
104 * @param obj The Elementary object to operate on
105 * @return @c EINA_TRUE if the object is allowed to be focused, @c
106 * EINA_FALSE if not (and on errors)
108 * @note Objects which are meant to be interacted with by input
109 * events are created able to be focused, by default. All the
114 EAPI Eina_Bool elm_object_focus_allow_get(const Evas_Object *obj);
117 * Set custom focus chain.
119 * This function overwrites any previous custom focus chain within
120 * the list of objects. The previous list will be deleted and this list
121 * will be managed by elementary. After it is set, don't modify it.
123 * @note On focus cycle, only will be evaluated children of this container.
125 * @param obj The container object
126 * @param objs Chain of objects to pass focus
129 EAPI void elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs);
132 * Unset a custom focus chain on a given Elementary widget
134 * @param obj The container object to remove focus chain from
136 * Any focus chain previously set on @p obj (for its child objects)
137 * is removed entirely after this call.
141 EAPI void elm_object_focus_custom_chain_unset(Evas_Object *obj);
144 * Get custom focus chain
146 * @param obj The container object
149 EAPI const Eina_List *elm_object_focus_custom_chain_get(const Evas_Object *obj);
152 * Append object to custom focus chain.
154 * @note If relative_child equal to NULL or not in custom chain, the object
155 * will be added in end.
157 * @note On focus cycle, only will be evaluated children of this container.
159 * @param obj The container object
160 * @param child The child to be added in custom chain
161 * @param relative_child The relative object to position the child
164 EAPI void elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
167 * Prepend object to custom focus chain.
169 * @note If relative_child equal to NULL or not in custom chain, the object
170 * will be added in begin.
172 * @note On focus cycle, only will be evaluated children of this container.
174 * @param obj The container object
175 * @param child The child to be added in custom chain
176 * @param relative_child The relative object to position the child
179 EAPI void elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
182 * Give focus to next object in object tree.
184 * Give focus to next object in focus chain of one object sub-tree.
185 * If the last object of chain already have focus, the focus will go to the
186 * first object of chain.
188 * @param obj The object root of sub-tree
189 * @param dir Direction to move the focus
191 * @see elm_object_focus_next_object_get(), elm_object_focus_next_object_set()
195 EAPI void elm_object_focus_next(Evas_Object *obj, Elm_Focus_Direction dir);
198 * Get next object which was set with specific focus direction.
200 * Get next object which was set by elm_object_focus_next_object_set
201 * with specific focus direction.
203 * @param obj The Elementary object
204 * @param dir Focus direction
205 * @return Focus next object or @c NULL, if there is no focus next object.
207 * @see elm_object_focus_next_object_set(), elm_object_focus_next()
213 EAPI Evas_Object * elm_object_focus_next_object_get(const Evas_Object *obj, Elm_Focus_Direction dir);
216 * Set next object with specific focus direction.
218 * When focus next object is set with specific focus direction, this object
219 * will be the first candidate when finding next focusable object.
220 * Focus next object can be registered with six directions that are previous,
221 * next, up, down, right, and left.
223 * @param obj The Elementary object
224 * @param next Focus next object
225 * @param dir Focus direction
227 * @see elm_object_focus_next_object_get(), elm_object_focus_next()
233 EAPI void elm_object_focus_next_object_set(Evas_Object *obj, Evas_Object *next, Elm_Focus_Direction dir);
236 * Get focused object in object tree.
238 * This function returns current focused object in one object sub-tree.
240 * @param obj The object root of sub-tree
241 * @return Current focused or @c NULL, if there is no focused object.
247 EAPI Evas_Object *elm_object_focused_object_get(const Evas_Object *obj);
250 * Make the elementary object and its children to be focusable
253 * @param obj The Elementary object to operate on
254 * @param focusable @c EINA_TRUE for focusable,
255 * @c EINA_FALSE for unfocusable.
257 * This sets whether the object @p obj and its children objects
258 * are able to take focus or not. If the tree is set as unfocusable,
259 * newest focused object which is not in this tree will get focus.
260 * This API can be helpful for an object to be deleted.
261 * When an object will be deleted soon, it and its children may not
262 * want to get focus (by focus reverting or by other focus controls).
263 * Then, just use this API before deleting.
265 * @see elm_object_tree_focus_allow_get()
270 EAPI void elm_object_tree_focus_allow_set(Evas_Object *obj, Eina_Bool focusable);
273 * Get whether an Elementary object and its children are focusable or not.
275 * @param obj The Elementary object to get the information from
276 * @return @c EINA_TRUE, if the tree is focusable,
277 * @c EINA_FALSE if not (and on errors).
279 * @see elm_object_tree_focus_allow_set()
283 EAPI Eina_Bool elm_object_tree_focus_allow_get(const Evas_Object *obj);