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