src/lib/elm_focus.h

   1 /**
   2  * @defgroup Focus Focus
   3  *
   4  * An Elementary application has, at all times, one (and only one)
   5  * @b focused object. This is what determines where the input
   6  * events go to within the application's window. Also, focused
   7  * objects can be decorated differently, in order to signal to the
   8  * user where the input is, at a given moment.
   9  *
  10  * Elementary applications also have the concept of <b>focus
  11  * chain</b>: one can cycle through all the windows' focusable
  12  * objects by input (tab key) or programmatically. The default
  13  * focus chain for an application is the one define by the order in
  14  * which the widgets where added in code. One will cycle through
  15  * top level widgets, and, for each one containing sub-objects, cycle
  16  * through them all, before returning to the level
  17  * above. Elementary also allows one to set @b custom focus chains
  18  * for their applications.
  19  *
  20  * Besides the focused decoration a widget may exhibit, when it
  21  * gets focus, Elementary has a @b global focus highlight object
  22  * that can be enabled for a window. If one chooses to do so, this
  23  * extra highlight effect will surround the current focused object,
  24  * too.
  25  *
  26  * @note Some Elementary widgets are @b unfocusable, after
  27  * creation, by their very nature: they are not meant to be
  28  * interacted with input events, but are there just for visual
  29  * purposes.
  30  *
  31  * @ref general_functions_example_page "This" example contemplates
  32  * some of these functions.
  33  */
  34
  35 /**
  36  * Get the whether an Elementary object has the focus or not.
  37  *
  38  * @param obj The Elementary object to get the information from
  39  * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if
  40  *            not (and on errors).
  41  *
  42  * @see elm_object_focus_set()
  43  *
  44  * @ingroup Focus
  45  */
  46 EAPI Eina_Bool            elm_object_focus_get(const Evas_Object *obj);
  47
  48 /**
  49  * Set/unset focus to a given Elementary object.
  50  *
  51  * @param obj The Elementary object to operate on.
  52  * @param focus @c EINA_TRUE Set focus to a given object,
  53  *              @c EINA_FALSE Unset focus to a given object.
  54  *
  55  * @note When you set focus to this object, if it can handle focus, will
  56  * take the focus away from the one who had it previously and will, for
  57  * now on, be the one receiving input events. Unsetting focus will remove
  58  * the focus from @p obj, passing it back to the previous element in the
  59  * focus chain list.
  60  *
  61  * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
  62  *
  63  * @ingroup Focus
  64  */
  65 EAPI void                 elm_object_focus_set(Evas_Object *obj, Eina_Bool focus);
  66
  67 /**
  68  * Set the ability for an Elementary object to be focused
  69  *
  70  * @param obj The Elementary object to operate on
  71  * @param enable @c EINA_TRUE if the object can be focused, @c
  72  *        EINA_FALSE if not (and on errors)
  73  *
  74  * This sets whether the object @p obj is able to take focus or
  75  * not. Unfocusable objects do nothing when programmatically
  76  * focused, being the nearest focusable parent object the one
  77  * really getting focus. Also, when they receive mouse input, they
  78  * will get the event, but not take away the focus from where it
  79  * was previously.
  80  *
  81  * @ingroup Focus
  82  */
  83 EAPI void                 elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable);
  84
  85 /**
  86  * Get whether an Elementary object is focusable or not
  87  *
  88  * @param obj The Elementary object to operate on
  89  * @return @c EINA_TRUE if the object is allowed to be focused, @c
  90  *             EINA_FALSE if not (and on errors)
  91  *
  92  * @note Objects which are meant to be interacted with by input
  93  * events are created able to be focused, by default. All the
  94  * others are not.
  95  *
  96  * @ingroup Focus
  97  */
  98 EAPI Eina_Bool            elm_object_focus_allow_get(const Evas_Object *obj);
  99
 100 /**
 101  * Set custom focus chain.
 102  *
 103  * This function overwrites any previous custom focus chain within
 104  * the list of objects. The previous list will be deleted and this list
 105  * will be managed by elementary. After it is set, don't modify it.
 106  *
 107  * @note On focus cycle, only will be evaluated children of this container.
 108  *
 109  * @param obj The container object
 110  * @param objs Chain of objects to pass focus
 111  * @ingroup Focus
 112  */
 113 EAPI void                 elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs);
 114
 115 /**
 116  * Unset a custom focus chain on a given Elementary widget
 117  *
 118  * @param obj The container object to remove focus chain from
 119  *
 120  * Any focus chain previously set on @p obj (for its child objects)
 121  * is removed entirely after this call.
 122  *
 123  * @ingroup Focus
 124  */
 125 EAPI void                 elm_object_focus_custom_chain_unset(Evas_Object *obj);
 126
 127 /**
 128  * Get custom focus chain
 129  *
 130  * @param obj The container object
 131  * @ingroup Focus
 132  */
 133 EAPI const Eina_List     *elm_object_focus_custom_chain_get(const Evas_Object *obj);
 134
 135 /**
 136  * Append object to custom focus chain.
 137  *
 138  * @note If relative_child equal to NULL or not in custom chain, the object
 139  * will be added in end.
 140  *
 141  * @note On focus cycle, only will be evaluated children of this container.
 142  *
 143  * @param obj The container object
 144  * @param child The child to be added in custom chain
 145  * @param relative_child The relative object to position the child
 146  * @ingroup Focus
 147  */
 148 EAPI void                 elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 149
 150 /**
 151  * Prepend object to custom focus chain.
 152  *
 153  * @note If relative_child equal to NULL or not in custom chain, the object
 154  * will be added in begin.
 155  *
 156  * @note On focus cycle, only will be evaluated children of this container.
 157  *
 158  * @param obj The container object
 159  * @param child The child to be added in custom chain
 160  * @param relative_child The relative object to position the child
 161  * @ingroup Focus
 162  */
 163 EAPI void                 elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 164
 165 /**
 166  * Give focus to next object in object tree.
 167  *
 168  * Give focus to next object in focus chain of one object sub-tree.
 169  * If the last object of chain already have focus, the focus will go to the
 170  * first object of chain.
 171  *
 172  * @param obj The object root of sub-tree
 173  * @param dir Direction to move the focus
 174  *
 175  * @ingroup Focus
 176  */
 177 EAPI void                 elm_object_focus_next(Evas_Object *obj, Elm_Focus_Direction dir);
 178
 179 /**
 180  * Make the elementary object and its children to be focusable
 181  * (or unfocusable).
 182  *
 183  * @param obj The Elementary object to operate on
 184  * @param focusable @c EINA_TRUE for focusable,
 185  *        @c EINA_FALSE for unfocusable.
 186  *
 187  * This sets whether the object @p obj and its children objects
 188  * are able to take focus or not. If the tree is set as unfocusable,
 189  * newest focused object which is not in this tree will get focus.
 190  * This API can be helpful for an object to be deleted.
 191  * When an object will be deleted soon, it and its children may not
 192  * want to get focus (by focus reverting or by other focus controls).
 193  * Then, just use this API before deleting.
 194  *
 195  * @see elm_object_tree_focus_allow_get()
 196  *
 197  * @ingroup Focus
 198  *
 199  */
 200 EAPI void                 elm_object_tree_focus_allow_set(Evas_Object *obj, Eina_Bool focusable);
 201
 202 /**
 203  * Get whether an Elementary object and its children are focusable or not.
 204  *
 205  * @param obj The Elementary object to get the information from
 206  * @return @c EINA_TRUE, if the tree is focusable,
 207  *         @c EINA_FALSE if not (and on errors).
 208  *
 209  * @see elm_object_tree_focus_allow_set()
 210  *
 211  * @ingroup Focus
 212  */
 213 EAPI Eina_Bool            elm_object_tree_focus_allow_get(const Evas_Object *obj);