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  * Focus directions.
  38  *
  39  * @ingroup Focus
  40  */
  41 typedef enum
  42 {
  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;
  50
  51 /**
  52  * Get the whether an Elementary object has the focus or not.
  53  *
  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).
  57  *
  58  * @see elm_object_focus_set()
  59  *
  60  * @ingroup Focus
  61  */
  62 EAPI Eina_Bool            elm_object_focus_get(const Evas_Object *obj);
  63
  64 /**
  65  * Set/unset focus to a given Elementary object.
  66  *
  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.
  70  *
  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
  75  * focus chain list.
  76  *
  77  * @see elm_object_focus_get(), elm_object_focus_custom_chain_get()
  78  *
  79  * @ingroup Focus
  80  */
  81 EAPI void                 elm_object_focus_set(Evas_Object *obj, Eina_Bool focus);
  82
  83 /**
  84  * Set the ability for an Elementary object to be focused
  85  *
  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)
  89  *
  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
  95  * was previously.
  96  *
  97  * @ingroup Focus
  98  */
  99 EAPI void                 elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable);
 100
 101 /**
 102  * Get whether an Elementary object is focusable or not
 103  *
 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)
 107  *
 108  * @note Objects which are meant to be interacted with by input
 109  * events are created able to be focused, by default. All the
 110  * others are not.
 111  *
 112  * @ingroup Focus
 113  */
 114 EAPI Eina_Bool            elm_object_focus_allow_get(const Evas_Object *obj);
 115
 116 /**
 117  * Set custom focus chain.
 118  *
 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.
 122  *
 123  * @note On focus cycle, only will be evaluated children of this container.
 124  *
 125  * @param obj The container object
 126  * @param objs Chain of objects to pass focus
 127  * @ingroup Focus
 128  */
 129 EAPI void                 elm_object_focus_custom_chain_set(Evas_Object *obj, Eina_List *objs);
 130
 131 /**
 132  * Unset a custom focus chain on a given Elementary widget
 133  *
 134  * @param obj The container object to remove focus chain from
 135  *
 136  * Any focus chain previously set on @p obj (for its child objects)
 137  * is removed entirely after this call.
 138  *
 139  * @ingroup Focus
 140  */
 141 EAPI void                 elm_object_focus_custom_chain_unset(Evas_Object *obj);
 142
 143 /**
 144  * Get custom focus chain
 145  *
 146  * @param obj The container object
 147  * @ingroup Focus
 148  */
 149 EAPI const Eina_List     *elm_object_focus_custom_chain_get(const Evas_Object *obj);
 150
 151 /**
 152  * Append 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 end.
 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_append(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 165
 166 /**
 167  * Prepend object to custom focus chain.
 168  *
 169  * @note If relative_child equal to NULL or not in custom chain, the object
 170  * will be added in begin.
 171  *
 172  * @note On focus cycle, only will be evaluated children of this container.
 173  *
 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
 177  * @ingroup Focus
 178  */
 179 EAPI void                 elm_object_focus_custom_chain_prepend(Evas_Object *obj, Evas_Object *child, Evas_Object *relative_child);
 180
 181 /**
 182  * Give focus to next object in object tree.
 183  *
 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.
 187  *
 188  * @param obj The object root of sub-tree
 189  * @param dir Direction to move the focus
 190  *
 191  * @see elm_object_focus_next_object_get(), elm_object_focus_next_object_set()
 192  *
 193  * @ingroup Focus
 194  */
 195 EAPI void                 elm_object_focus_next(Evas_Object *obj, Elm_Focus_Direction dir);
 196
 197 /**
 198  * Get next object which was set with specific focus direction.
 199  *
 200  * Get next object which was set by elm_object_focus_next_object_set
 201  * with specific focus direction.
 202  *
 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.
 206  *
 207  * @see elm_object_focus_next_object_set(), elm_object_focus_next()
 208  *
 209  * @since 1.8
 210  *
 211  * @ingroup Focus
 212  */
 213 EAPI Evas_Object *        elm_object_focus_next_object_get(const Evas_Object *obj, Elm_Focus_Direction dir);
 214
 215 /**
 216  * Set next object with specific focus direction.
 217  *
 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.
 222  *
 223  * @param obj The Elementary object
 224  * @param next Focus next object
 225  * @param dir Focus direction
 226  *
 227  * @see elm_object_focus_next_object_get(), elm_object_focus_next()
 228  *
 229  * @since 1.8
 230  *
 231  * @ingroup Focus
 232  */
 233 EAPI void                 elm_object_focus_next_object_set(Evas_Object *obj, Evas_Object *next, Elm_Focus_Direction dir);
 234
 235 /**
 236  * Get focused object in object tree.
 237  *
 238  * This function returns current focused object in one object sub-tree.
 239  *
 240  * @param obj The object root of sub-tree
 241  * @return Current focused or @c NULL, if there is no focused object.
 242  *
 243  * @since 1.8
 244  *
 245  * @ingroup Focus
 246  */
 247 EAPI Evas_Object         *elm_object_focused_object_get(const Evas_Object *obj);
 248
 249 /**
 250  * Make the elementary object and its children to be focusable
 251  * (or unfocusable).
 252  *
 253  * @param obj The Elementary object to operate on
 254  * @param focusable @c EINA_TRUE for focusable,
 255  *        @c EINA_FALSE for unfocusable.
 256  *
 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.
 264  *
 265  * @see elm_object_tree_focus_allow_get()
 266  *
 267  * @ingroup Focus
 268  *
 269  */
 270 EAPI void                 elm_object_tree_focus_allow_set(Evas_Object *obj, Eina_Bool focusable);
 271
 272 /**
 273  * Get whether an Elementary object and its children are focusable or not.
 274  *
 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).
 278  *
 279  * @see elm_object_tree_focus_allow_set()
 280  *
 281  * @ingroup Focus
 282  */
 283 EAPI Eina_Bool            elm_object_tree_focus_allow_get(const Evas_Object *obj);