src/lib/elm_focus.h

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