diff options
Diffstat (limited to 'src/lib/elm_focus.h')
| -rw-r--r-- | src/lib/elm_focus.h | 351 |
1 files changed, 159 insertions, 192 deletions
diff --git a/src/lib/elm_focus.h b/src/lib/elm_focus.h index 3aad5e94c..4f160cc1e 100644 --- a/src/lib/elm_focus.h +++ b/src/lib/elm_focus.h @@ -1,6 +1,7 @@ /** * @defgroup Focus Focus - * @ingroup Elementary + * @ingroup elm_infra_group + * @brief This group provides functions to handle Elementary Focus. * * An Elementary application has, at all times, one (and only one) * @b focused object. This is what determines where the input @@ -11,327 +12,293 @@ * Elementary applications also have the concept of <b>focus * chain</b>: 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 + * 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 @b custom focus chains * for their applications. * - * Besides the focused decoration a widget may exhibit, when it + * Besides the focused decoration that a widget may exhibit, when it * gets focus, Elementary has a @b 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, + * extra highlight effect surrounds the current focused object, * too. * - * @note Some Elementary widgets are @b unfocusable, after + * @remarks Some Elementary widgets are @b unfocusable, after * creation, by their very nature: they are not meant to be * interacted with input events, but are there just for visual - * purposes. + * purposes. * * - * @ref general_functions_example_page "This" example contemplates - * some of these functions. + * @{ */ /** - * Focus directions. - * - * @ingroup Focus + * @brief Enumeration that defines the focus directions. */ typedef enum { - 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 */ + 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 */ + ELM_FOCUS_NONE } Elm_Focus_Direction; /** - * Get the whether an Elementary object has the focus or not. + * @typedef Elm_Focus_Info * - * @param obj The Elementary object to get the information from - * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if - * not (and on errors). + * @brief The structure type containing the info sent in the callback for the "focused" signals. + */ +typedef struct _Elm_Focus_Info Elm_Focus_Info; + +struct _Elm_Focus_Info +{ + Evas_Object *prev_focused; + Elm_Focus_Direction dir; +}; + +/** + * @brief Gets whether an Elementary object has the focus. * - * @see elm_object_focus_set() + * @since_tizen 2.3 + * + * @param[in] obj The Elementary object to get the information from + * @return @c EINA_TRUE if the object is focused, otherwise @c EINA_FALSE if + * not (and on errors) * - * @ingroup Focus + * @see elm_object_focus_set() */ EAPI Eina_Bool elm_object_focus_get(const Evas_Object *obj); /** - * Set/unset focus to a given Elementary object. + * @brief Sets or unsets focus to a given Elementary object. * - * @param obj The Elementary object to operate on. - * @param focus @c EINA_TRUE Set focus to a given object, - * @c EINA_FALSE Unset focus to a given object. + * @since_tizen 2.3 * - * @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 @p obj, passing it back to the previous element in the - * focus chain list. + * @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 @a 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. + * @param[in] obj The Elementary object to operate on + * @param[in] focus If @c EINA_TRUE the focus to a given object is set, + * otherwise @c EINA_FALSE to unset the focus to a given object * - * @see elm_object_focus_get(), elm_object_focus_custom_chain_get() - * - * @ingroup Focus + * @see elm_object_focus_get() + * @see elm_object_focus_custom_chain_get() */ EAPI void elm_object_focus_set(Evas_Object *obj, Eina_Bool focus); /** - * Set the ability for an Elementary object to be focused + * @brief Sets the ability for an Elementary object to be focused. * - * @param obj The Elementary object to operate on - * @param enable @c EINA_TRUE if the object can be focused, @c - * EINA_FALSE if not (and on errors) + * @details This sets whether the object @a 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. * - * This sets whether the object @p 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. + * @since_tizen 2.3 * - * @ingroup Focus + * @param[in] obj The Elementary object to operate on + * @param[in] enable If @c EINA_TRUE the object can be focused, + * otherwise @c EINA_FALSE if it cannot (and on errors) */ EAPI void elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable); /** - * Get whether an Elementary object is focusable or not + * @brief Gets whether an Elementary object is focusable. * - * @param obj The Elementary object to operate on - * @return @c EINA_TRUE if the object is allowed to be focused, @c - * EINA_FALSE if not (and on errors) + * @since_tizen 2.3 * - * @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. + * @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. * - * @ingroup Focus + * @param[in] obj The Elementary object to operate on + * @return @c EINA_TRUE if the object is allowed to be focused, + * otherwise @c EINA_FALSE if it is not (and on errors) */ EAPI Eina_Bool elm_object_focus_allow_get(const Evas_Object *obj); /** - * Set custom focus chain. + * @brief Sets the custom focus chain. + * + * @details 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. * - * 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. + * @since_tizen 2.3 * - * @note On focus cycle, only will be evaluated children of this container. + * @remarks On the focus cycle, there are only evaluated children of this container. * - * @param obj The container object - * @param objs Chain of objects to pass focus - * @ingroup Focus + * @param[in] obj The container object + * @param[in] objs The chain of objects to pass focus to */ EAPI void elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs); /** - * Unset a custom focus chain on a given Elementary widget + * @brief Unsets a custom focus chain on a given Elementary widget. * - * @param obj The container object to remove focus chain from + * @since_tizen 2.3 * - * Any focus chain previously set on @p obj (for its child objects) - * is removed entirely after this call. + * @remarks Any focus chain previously set on @a obj (for its child objects) + * is removed entirely after this call. * - * @ingroup Focus + * @param[in] obj The container object to remove the focus chain from */ EAPI void elm_object_focus_custom_chain_unset(Evas_Object *obj); /** - * Get custom focus chain + * @brief Gets the custom focus chain. * - * @param obj The container object - * @ingroup Focus + * @since_tizen 2.3 + * + * @param[in] obj The container object + * @return The focus custom chain list */ EAPI const Eina_List *elm_object_focus_custom_chain_get(const Evas_Object *obj); /** - * Append object to custom focus chain. + * @brief Appends an object to the custom focus chain. + * + * @since_tizen 2.3 * - * @note If relative_child equal to NULL or not in custom chain, the object - * will be added in end. + * @remarks If @a relative_child is equal to @c NULL or not in the custom chain, the object + * is added in the end. * - * @note On focus cycle, only will be evaluated children of this container. + * @remarks On the focus cycle, there are only evaluated children of this container. * - * @param obj The container object - * @param child The child to be added in custom chain - * @param relative_child The relative object to position the child - * @ingroup Focus + * @param[in] obj The container object + * @param[in] child The child to be added in the custom chain + * @param[in] relative_child The relative object to position the child */ EAPI void elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child); /** - * Prepend object to custom focus chain. + * @brief Prepends an object to the custom focus chain. + * + * @since_tizen 2.3 * - * @note If relative_child equal to NULL or not in custom chain, the object - * will be added in begin. + * @remarks If @a relative_child is equal to @c NULL or not in custom chain, the object + * is added in the beginning. * - * @note On focus cycle, only will be evaluated children of this container. + * @remarks On the focus cycle, there are only evaluated children of this container. * - * @param obj The container object - * @param child The child to be added in custom chain - * @param relative_child The relative object to position the child - * @ingroup Focus + * @param[in] obj The container object + * @param[in] child The child to be added in the custom chain + * @param[in] relative_child The relative object to position the child */ EAPI void elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child); /** - * Give focus to next object in object tree. + * @brief Gives focus to the next object in the 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. + * @details 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. * - * @param obj The object root of sub-tree - * @param dir Direction to move the focus + * @param[in] obj The object root of the sub-tree + * @param[in] dir The direction to move the focus * - * @see elm_object_focus_next_object_get(), elm_object_focus_next_object_set() - * - * @ingroup Focus + * @see elm_object_focus_next_object_get() + * @see elm_object_focus_next_object_set() */ EAPI void elm_object_focus_next(Evas_Object *obj, Elm_Focus_Direction dir); /** - * Get next object which was set with specific focus direction. + * @brief Gets the next object that is set with a specific focus direction. * - * Get next object which was set by elm_object_focus_next_object_set - * with specific focus direction. + * @details This gets the next object that is set by elm_object_focus_next_object_set() + * with a specific focus direction. * - * @param obj The Elementary object - * @param dir Focus direction - * @return Focus next object or @c NULL, if there is no focus next object. + * @since 1.8 * - * @see elm_object_focus_next_object_set(), elm_object_focus_next() + * @since_tizen 2.3 * - * @since 1.8 + * @param[in] obj The Elementary object + * @param[in] dir The focus direction + * @return The focus next object, otherwise @c NULL if there is no focus next object * - * @ingroup Focus + * @see elm_object_focus_next_object_set() + * @see elm_object_focus_next() */ EAPI Evas_Object * elm_object_focus_next_object_get(const Evas_Object *obj, Elm_Focus_Direction dir); /** - * Set next object with specific focus direction. + * @brief Sets the next object with a 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. + * @since 1.8 * - * @param obj The Elementary object - * @param next Focus next object - * @param dir Focus direction + * @since_tizen 2.3 * - * @see elm_object_focus_next_object_get(), elm_object_focus_next() + * @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. * - * @since 1.8 + * @param[in] obj The Elementary object + * @param[in] next The focus next object + * @param[in] dir The focus direction * - * @ingroup Focus + * @see elm_object_focus_next_object_get() + * @see elm_object_focus_next() */ EAPI void elm_object_focus_next_object_set(Evas_Object *obj, Evas_Object *next, Elm_Focus_Direction dir); /** - * Get focused object in object tree. - * - * This function returns current focused object in one object sub-tree. + * @brief Gets the focused object in the object tree. * - * @param obj The object root of sub-tree - * @return Current focused or @c NULL, if there is no focused object. + * @details This function returns the current focused object in one object sub-tree. * * @since 1.8 * - * @ingroup Focus + * @param obj The object root of the sub-tree + * @return The current focused object, otherwise @c NULL if there is no focused object */ EAPI Evas_Object *elm_object_focused_object_get(const Evas_Object *obj); /** - * Make the elementary object and its children to be focusable - * (or unfocusable). + * @brief Makes the elementary object and its children to be focusable + * (or unfocusable). * - * @param obj The Elementary object to operate on - * @param focusable @c EINA_TRUE for focusable, - * @c EINA_FALSE for unfocusable. + * @details This sets whether the object @a 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. * - * This sets whether the object @p 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. + * @since_tizen 2.3 * - * @see elm_object_tree_focus_allow_get() + * @param[in] obj The Elementary object to operate on + * @param[in] focusable If @c EINA_TRUE it is focusable, + * otherwise @c EINA_FALSE if it is unfocusable * - * @ingroup Focus + * @see elm_object_tree_focus_allow_get() * */ EAPI void elm_object_tree_focus_allow_set(Evas_Object *obj, Eina_Bool focusable); /** - * Get whether an Elementary object and its children are focusable or not. + * @brief Gets whether an Elementary object and its children are focusable. * - * @param obj The Elementary object to get the information from + * @since_tizen 2.3 + * + * @param[in] obj The Elementary object to get the information from * @return @c EINA_TRUE, if the tree is focusable, - * @c EINA_FALSE if not (and on errors). + * otherwise @c EINA_FALSE if it is not (and on errors) * * @see elm_object_tree_focus_allow_set() - * - * @ingroup Focus */ EAPI Eina_Bool elm_object_tree_focus_allow_get(const Evas_Object *obj); /** - * Set the focus highlight style to be used by a given widget. - * - * @param obj The Elementary widget for which focus style needs to be set. - * @param style The name of the focus style to use on it. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * @note This overrides the style which is set - * by elm_win_focus_highlight_style_set(). - * - * @see elm_object_focus_highlight_style_get - * - * @since 1.9 - * - * @ingroup Focus - */ -EAPI Eina_Bool elm_object_focus_highlight_style_set(Evas_Object *obj, const char *style); - -/** - * Get the focus highlight style to be used by a given widget. - * - * @param obj The Elementary widget to query for its focus highlight style. - * @return The focus highlight style name used by widget. - * - * @see elm_object_focus_highlight_style_set() - * - * @since 1.9 - * - * @ingroup Focus - */ -EAPI const char *elm_object_focus_highlight_style_get(const Evas_Object *obj); - -/** - * Get the focused object item - * - * This returns the focused object item. - * - * @param obj The container object - * @return The focused item, or @c NULL if none - * - * The focused item can be unfocused with function - * elm_object_item_focus_set(). - * - * see @elm_object_item_focus_set() - * see @elm_object_item_focus_get() - * - * @ingroup Focus - * @since 1.10 + * @} */ -EAPI Elm_Object_Item *elm_object_focused_item_get(const Evas_Object *obj); |