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 enable status of the focus highlight
  37  *
  38  * This gets whether the highlight on focused objects is enabled or not
  39  *
  40  * @see elm_focus_highlight_enabled_set()
  41  * @ingroup Focus
  42  */
  43 EAPI Eina_Bool            elm_focus_highlight_enabled_get(void);
  44
  45 /**
  46  * Set the enable status of the focus highlight
  47  *
  48  * @param enable Enable highlight if EINA_TRUE, disable otherwise
  49  *
  50  * Set whether to show or not the highlight on focused objects
  51  *
  52  * Note that it will take effect only to Elementary windows created after
  53  * this is called.
  54  *
  55  * @see elm_win_add()
  56  *
  57  * @ingroup Focus
  58  */
  59 EAPI void                 elm_focus_highlight_enabled_set(Eina_Bool enable);
  60
  61 /**
  62  * Get the enable status of the highlight animation
  63  *
  64  * @return The focus highlight mode set
  65  *
  66  * Get whether the focus highlight, if enabled, will animate its switch from
  67  * one object to the next
  68  *
  69  * @ingroup Focus
  70  */
  71 EAPI Eina_Bool            elm_focus_highlight_animate_get(void);
  72
  73 /**
  74  * Set the enable status of the highlight animation
  75  *
  76  * @param animate Enable animation if EINA_TRUE, disable otherwise
  77  *
  78  * Set whether the focus highlight, if enabled, will animate its switch from
  79  * one object to the next
  80  *
  81  * Note that it will take effect only to Elementary windows created after
  82  * this is called.
  83  *
  84  * @see elm_win_add()
  85  *
  86  * @ingroup Focus
  87  */
  88 EAPI void                 elm_focus_highlight_animate_set(Eina_Bool animate);
  89
  90 /**
  91  * Get the whether an Elementary object has the focus or not.
  92  *
  93  * @param obj The Elementary object to get the information from
  94  * @return @c EINA_TRUE, if the object is focused, @c EINA_FALSE if
  95  *            not (and on errors).
  96  *
  97  * @see elm_object_focus_set()
  98  *
  99  * @ingroup Focus
 100  */
 101 EAPI Eina_Bool            elm_object_focus_get(const Evas_Object *obj);
 102
 103 /**
 104  * Set/unset focus to a given Elementary object.
 105  *
 106  * @param obj The Elementary object to operate on.
 107  * @param focus @c EINA_TRUE Set focus to a given object,
 108  *              @c EINA_FALSE Unset focus to a given object.
 109  *
 110  * @note When you set focus to this object, if it can handle focus, will
 111  * take the focus away from the one who had it previously and will, for
 112  * now on, be the one receiving input events. Unsetting focus will remove
 113  * the focus from @p obj, passing it back to the previous element in the
 114  * focus chain list.
 115  *
 116  * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
 117  *
 118  * @ingroup Focus
 119  */
 120 EAPI void                 elm_object_focus_set(Evas_Object *obj, Eina_Bool focus);
 121
 122 /**
 123  * Set the ability for an Elementary object to be focused
 124  *
 125  * @param obj The Elementary object to operate on
 126  * @param enable @c EINA_TRUE if the object can be focused, @c
 127  *        EINA_FALSE if not (and on errors)
 128  *
 129  * This sets whether the object @p obj is able to take focus or
 130  * not. Unfocusable objects do nothing when programmatically
 131  * focused, being the nearest focusable parent object the one
 132  * really getting focus. Also, when they receive mouse input, they
 133  * will get the event, but not take away the focus from where it
 134  * was previously.
 135  *
 136  * @ingroup Focus
 137  */
 138 EAPI void                 elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable);
 139
 140 /**
 141  * Get whether an Elementary object is focusable or not
 142  *
 143  * @param obj The Elementary object to operate on
 144  * @return @c EINA_TRUE if the object is allowed to be focused, @c
 145  *             EINA_FALSE if not (and on errors)
 146  *
 147  * @note Objects which are meant to be interacted with by input
 148  * events are created able to be focused, by default. All the
 149  * others are not.
 150  *
 151  * @ingroup Focus
 152  */
 153 EAPI Eina_Bool            elm_object_focus_allow_get(const Evas_Object *obj);
 154
 155 /**
 156  * Set custom focus chain.
 157  *
 158  * This function overwrites any previous custom focus chain within
 159  * the list of objects. The previous list will be deleted and this list
 160  * will be managed by elementary. After it is set, don't modify it.
 161  *
 162  * @note On focus cycle, only will be evaluated children of this container.
 163  *
 164  * @param obj The container object
 165  * @param objs Chain of objects to pass focus
 166  * @ingroup Focus
 167  */
 168 EAPI void                 elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs);
 169
 170 /**
 171  * Unset a custom focus chain on a given Elementary widget
 172  *
 173  * @param obj The container object to remove focus chain from
 174  *
 175  * Any focus chain previously set on @p obj (for its child objects)
 176  * is removed entirely after this call.
 177  *
 178  * @ingroup Focus
 179  */
 180 EAPI void                 elm_object_focus_custom_chain_unset(Evas_Object *obj);
 181
 182 /**
 183  * Get custom focus chain
 184  *
 185  * @param obj The container object
 186  * @ingroup Focus
 187  */
 188 EAPI const Eina_List     *elm_object_focus_custom_chain_get(const Evas_Object *obj);
 189
 190 /**
 191  * Append object to custom focus chain.
 192  *
 193  * @note If relative_child equal to NULL or not in custom chain, the object
 194  * will be added in end.
 195  *
 196  * @note On focus cycle, only will be evaluated children of this container.
 197  *
 198  * @param obj The container object
 199  * @param child The child to be added in custom chain
 200  * @param relative_child The relative object to position the child
 201  * @ingroup Focus
 202  */
 203 EAPI void                 elm_object_focus_custom_chain_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 204
 205 /**
 206  * Prepend object to custom focus chain.
 207  *
 208  * @note If relative_child equal to NULL or not in custom chain, the object
 209  * will be added in begin.
 210  *
 211  * @note On focus cycle, only will be evaluated children of this container.
 212  *
 213  * @param obj The container object
 214  * @param child The child to be added in custom chain
 215  * @param relative_child The relative object to position the child
 216  * @ingroup Focus
 217  */
 218 EAPI void                 elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 219
 220 /**
 221  * Give focus to next object in object tree.
 222  *
 223  * Give focus to next object in focus chain of one object sub-tree.
 224  * If the last object of chain already have focus, the focus will go to the
 225  * first object of chain.
 226  *
 227  * @param obj The object root of sub-tree
 228  * @param dir Direction to cycle the focus
 229  *
 230  * @ingroup Focus
 231  */
 232 //XXX: How about elm_object_focus_move()? focus_next() ?
 233 EAPI void                 elm_object_focus_cycle(Evas_Object *obj, Elm_Focus_Direction dir);
 234
 235 /**
 236  * Make the elementary object and its children to be unfocusable
 237  * (or focusable).
 238  *
 239  * @param obj The Elementary object to operate on
 240  * @param tree_unfocusable @c EINA_TRUE for unfocusable,
 241  *        @c EINA_FALSE for focusable.
 242  *
 243  * This sets whether the object @p obj and its children objects
 244  * are able to take focus or not. If the tree is set as unfocusable,
 245  * newest focused object which is not in this tree will get focus.
 246  * This API can be helpful for an object to be deleted.
 247  * When an object will be deleted soon, it and its children may not
 248  * want to get focus (by focus reverting or by other focus controls).
 249  * Then, just use this API before deleting.
 250  *
 251  * @see elm_object_tree_unfocusable_get()
 252  *
 253  * @ingroup Focus
 254  *
 255  */
 256  //XXX: How about elm_object_tree_focus_allow_set()?
 257 EAPI void                 elm_object_tree_unfocusable_set(Evas_Object *obj, Eina_Bool tree_unfocusable);
 258
 259 /**
 260  * Get whether an Elementary object and its children are unfocusable or not.
 261  *
 262  * @param obj The Elementary object to get the information from
 263  * @return @c EINA_TRUE, if the tree is unfocussable,
 264  *         @c EINA_FALSE if not (and on errors).
 265  *
 266  * @see elm_object_tree_unfocusable_set()
 267  *
 268  * @ingroup Focus
 269  */
 270 //XXX: How about elm_object_tree_focus_allow_get()?
 271 EAPI Eina_Bool            elm_object_tree_unfocusable_get(const Evas_Object *obj);