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