mobile/src/lib/elm_index.h

   1 /**
   2  * @defgroup Index Index
   3  * @ingroup Elementary
   4  *
   5  * @image html index_inheritance_tree.png
   6  * @image latex index_inheritance_tree.eps
   7  *
   8  * @image html img/widget/index/preview-00.png
   9  * @image latex img/widget/index/preview-00.eps
  10  *
  11  * An index widget gives you an index for fast access to whichever
  12  * group of other UI items one might have. It's a list of text
  13  * items (usually letters, for alphabetically ordered access).
  14  *
  15  * Index widgets are by default hidden and just appear when the
  16  * user clicks over it's reserved area in the canvas. In its
  17  * default theme, it's an area one @ref Fingers "finger" wide on
  18  * the right side of the index widget's container.
  19  *
  20  * When items on the index are selected, smart callbacks get
  21  * called, so that its user can make other container objects to
  22  * show a given area or child object depending on the index item
  23  * selected. You'd probably be using an index together with @ref
  24  * List "lists", @ref Genlist "generic lists" or @ref Gengrid
  25  * "general grids".
  26  *
  27  * This widget inherits from the @ref Layout one, so that all the
  28  * functions acting on it also work for index objects.
  29  *
  30  * This widget emits the following signals, besides the ones sent from
  31  * @ref Layout:
  32  * - @c "changed" - When the selected index item changes. @c
  33  *      event_info is the selected item's data pointer.
  34  * - @c "delay,changed" - When the selected index item changes, but
  35  *      after a small idling period. @c event_info is the selected
  36  *      item's data pointer.
  37  * - @c "selected" - When the user releases a mouse button and
  38  *      selects an item. @c event_info is the selected item's data
  39  *      pointer.
  40  * - @c "level,up" - when the user moves a finger from the first
  41  *      level to the second level
  42  * - @c "level,down" - when the user moves a finger from the second
  43  *      level to the first level
  44  * - @c "language,changed" - the program's language changed
  45  *
  46  * The @c "delay,changed" event is so that it'll wait a small time
  47  * before actually reporting those events and, moreover, just the
  48  * last event happening on those time frames will actually be
  49  * reported.
  50  *
  51  * Here are some examples on its usage:
  52  * @li @ref index_example_01
  53  * @li @ref index_example_02
  54  */
  55
  56 /**
  57  * @addtogroup Index
  58  * @{
  59  */
  60
  61 /**
  62  * Add a new index widget to the given parent Elementary
  63  * (container) object
  64  *
  65  * @param parent The parent object
  66  * @return a new index widget handle or @c NULL, on errors
  67  *
  68  * This function inserts a new index widget on the canvas.
  69  *
  70  * @ingroup Index
  71  */
  72 EAPI Evas_Object          *elm_index_add(Evas_Object *parent);
  73
  74 /**
  75  * Enable or disable auto hiding feature for a given index widget.
  76  *
  77  * @param obj The index object
  78  * @param disabled @c EINA_TRUE to disable auto hiding, @c EINA_FALSE to enable
  79  *
  80  * @see elm_index_autohide_disabled_get()
  81  *
  82  * @ingroup Index
  83  */
  84 EAPI void                  elm_index_autohide_disabled_set(Evas_Object *obj, Eina_Bool disabled);
  85
  86 /**
  87  * Get whether auto hiding feature is enabled or not for a given index widget.
  88  *
  89  * @param obj The index object
  90  * @return @c EINA_TRUE, if auto hiding is disabled, @c EINA_FALSE otherwise
  91  *
  92  * @see elm_index_autohide_disabled_set() for more details
  93  *
  94  * @ingroup Index
  95  */
  96 EAPI Eina_Bool             elm_index_autohide_disabled_get(const Evas_Object *obj);
  97
  98 /**
  99  * Set the items level for a given index widget.
 100  *
 101  * @param obj The index object.
 102  * @param level @c 0 or @c 1, the currently implemented levels.
 103  *
 104  * @see elm_index_item_level_get()
 105  *
 106  * @ingroup Index
 107  */
 108 EAPI void                  elm_index_item_level_set(Evas_Object *obj, int level);
 109
 110 /**
 111  * Get the items level set for a given index widget.
 112  *
 113  * @param obj The index object.
 114  * @return @c 0 or @c 1, which are the levels @p obj might be at.
 115  *
 116  * @see elm_index_item_level_set() for more information
 117  *
 118  * @ingroup Index
 119  */
 120 EAPI int                   elm_index_item_level_get(const Evas_Object *obj);
 121
 122 /**
 123  * Set the selected state of an item.
 124  *
 125  * @param it The index item
 126  * @param selected The selected state
 127  *
 128  * This sets the selected state of the given item @p it.
 129  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 130  *
 131  * If a new item is selected the previously selected will be unselected.
 132  * Previously selected item can be get with function
 133  * elm_index_selected_item_get().
 134  *
 135  * Selected items will be highlighted.
 136  *
 137  * @see elm_index_selected_item_get()
 138  *
 139  * @ingroup Index
 140  */
 141 EAPI void                  elm_index_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 142
 143 /**
 144  * Returns the last selected item, for a given index widget.
 145  *
 146  * @param obj The index object.
 147  * @param level @c 0 or @c 1, the currently implemented levels.
 148  * @return The last item @b selected on @p obj (or @c NULL, on errors).
 149  *
 150  * @ingroup Index
 151  */
 152 EAPI Elm_Object_Item      *elm_index_selected_item_get(const Evas_Object *obj, int level);
 153
 154 /**
 155  * Append a new item on a given index widget.
 156  *
 157  * @param obj The index object.
 158  * @param letter Letter under which the item should be indexed
 159  * @param func The function to call when the item is selected.
 160  * @param data The item data to set for the index's item
 161  * @return A handle to the item added or @c NULL, on errors
 162  *
 163  * Despite the most common usage of the @p letter argument is for
 164  * single char strings, one could use arbitrary strings as index
 165  * entries.
 166  *
 167  * @c item will be the pointer returned back on @c "changed", @c
 168  * "delay,changed" and @c "selected" smart events.
 169  *
 170  * @ingroup Index
 171  */
 172 EAPI Elm_Object_Item      *elm_index_item_append(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
 173
 174 /**
 175  * Prepend a new item on a given index widget.
 176  *
 177  * @param obj The index object.
 178  * @param letter Letter under which the item should be indexed
 179  * @param func The function to call when the item is selected.
 180  * @param data The item data to set for the index's item
 181  * @return A handle to the item added or @c NULL, on errors
 182  *
 183  * Despite the most common usage of the @p letter argument is for
 184  * single char strings, one could use arbitrary strings as index
 185  * entries.
 186  *
 187  * @c item will be the pointer returned back on @c "changed", @c
 188  * "delay,changed" and @c "selected" smart events.
 189  *
 190  * @ingroup Index
 191  */
 192 EAPI Elm_Object_Item      *elm_index_item_prepend(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
 193
 194 /**
 195  * Insert a new item into the index object after item @p after.
 196  *
 197  * @param obj The index object.
 198  * @param after The index item to insert after.
 199  * @param letter Letter under which the item should be indexed
 200  * @param func The function to call when the item is clicked.
 201  * @param data The item data to set for the index's item
 202  * @return A handle to the item added or @c NULL, on errors
 203  *
 204  * Despite the most common usage of the @p letter argument is for
 205  * single char strings, one could use arbitrary strings as index
 206  * entries.
 207  *
 208  * @c item will be the pointer returned back on @c "changed", @c
 209  * "delay,changed" and @c "selected" smart events.
 210  *
 211  * @note If @p relative is @c NULL this function will behave as
 212  * elm_index_item_append().
 213  *
 214  * @ingroup Index
 215  */
 216 EAPI Elm_Object_Item      *elm_index_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *letter, Evas_Smart_Cb func, const void *data);
 217
 218 /**
 219  * Insert a new item into the index object before item @p before.
 220  *
 221  * @param obj The index object.
 222  * @param before The index item to insert after.
 223  * @param letter Letter under which the item should be indexed
 224  * @param func The function to call when the item is clicked.
 225  * @param data The item data to set for the index's item
 226  * @return A handle to the item added or @c NULL, on errors
 227  *
 228  * Despite the most common usage of the @p letter argument is for
 229  * single char strings, one could use arbitrary strings as index
 230  * entries.
 231  *
 232  * @c item will be the pointer returned back on @c "changed", @c
 233  * "delay,changed" and @c "selected" smart events.
 234  *
 235  * @note If @p relative is @c NULL this function will behave as
 236  * elm_index_item_prepend().
 237  *
 238  * @ingroup Index
 239  */
 240 EAPI Elm_Object_Item      *elm_index_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *letter, Evas_Smart_Cb func, const void *data);
 241
 242 /**
 243  * Insert a new item into the given index widget, using @p cmp_func
 244  * function to sort items (by item handles).
 245  *
 246  * @param obj The index object.
 247  * @param letter Letter under which the item should be indexed
 248  * @param func The function to call when the item is clicked.
 249  * @param data The item data to set for the index's item
 250  * @param cmp_func The comparing function to be used to sort index
 251  * items <b>by index item handles</b>
 252  * @param cmp_data_func A @b fallback function to be called for the
 253  * sorting of index items <b>by item data</b>). It will be used
 254  * when @p cmp_func returns @c 0 (equality), which means an index
 255  * item with provided item data already exists. To decide which
 256  * data item should be pointed to by the index item in question, @p
 257  * cmp_data_func will be used. If @p cmp_data_func returns a
 258  * non-negative value, the previous index item data will be
 259  * replaced by the given @p item pointer. If the previous data need
 260  * to be freed, it should be done by the @p cmp_data_func function,
 261  * because all references to it will be lost. If this function is
 262  * not provided (@c NULL is given), index items will be @b
 263  * duplicated, if @p cmp_func returns @c 0.
 264  * @return A handle to the item added or @c NULL, on errors
 265  *
 266  * Despite the most common usage of the @p letter argument is for
 267  * single char strings, one could use arbitrary strings as index
 268  * entries.
 269  *
 270  * @c item will be the pointer returned back on @c "changed", @c
 271  * "delay,changed" and @c "selected" smart events.
 272  *
 273  * @ingroup Index
 274  */
 275 EAPI Elm_Object_Item      *elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func);
 276
 277 /**
 278  * Find a given index widget's item, <b>using item data</b>.
 279  *
 280  * @param obj The index object
 281  * @param data The item data pointed to by the desired index item
 282  * @return The index item handle, if found, or @c NULL otherwise
 283  *
 284  * @ingroup Index
 285  */
 286 EAPI Elm_Object_Item      *elm_index_item_find(Evas_Object *obj, const void *data);
 287
 288 /**
 289  * Removes @b all items from a given index widget.
 290  *
 291  * @param obj The index object.
 292  *
 293  * If deletion callbacks are set, via elm_object_item_del_cb_set(),
 294  * that callback function will be called for each item in @p obj.
 295  *
 296  * @ingroup Index
 297  */
 298 EAPI void                  elm_index_item_clear(Evas_Object *obj);
 299
 300 /**
 301  * Flush the changes made to the index items so they work correctly
 302  *
 303  * This flushes any changes made to items indicating the object is ready to
 304  * go. You should call this before any changes you expect to work. This
 305  * is similar to elm_list_go().
 306  *
 307  * @param obj The index object
 308  * @param level The index level (one of @c 0 or @c 1) where changes were made
 309  *
 310  * @warning If not called, it won't display the index properly.
 311  *
 312  * @ingroup Index
 313  */
 314 EAPI void                  elm_index_level_go(Evas_Object *obj, int level);
 315
 316 /**
 317  * Get the letter (string) set on a given index widget item.
 318  *
 319  * @param item The index item handle
 320  * @return The letter string set on @p it
 321  *
 322  * @ingroup Index
 323  */
 324 EAPI const char           *elm_index_item_letter_get(const Elm_Object_Item *item);
 325
 326 /**
 327  * Set the indicator as to be disabled.
 328  *
 329  * @param obj The index object
 330  * @param disabled  @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
 331  *
 332  * In Index widget, Indicator notes popup text, which shows a letter has been selecting.
 333  *
 334  * @see elm_index_indicator_disabled_get()
 335  *
 336  * @ingroup Index
 337  */
 338 EAPI void                 elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 339
 340 /**
 341  * Get the value of indicator's disabled status.
 342  *
 343  * @param obj The index object
 344  * @return EINA_TRUE if the indicator is disabled.
 345  *
 346  * @see elm_index_indicator_disabled_set()
 347  *
 348  * @ingroup Index
 349  */
 350 EAPI Eina_Bool            elm_index_indicator_disabled_get(const Evas_Object *obj);
 351
 352 /**
 353  * Enable or disable horizontal mode on the index object
 354  *
 355  * @param obj The index object.
 356  * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
 357  * disable it, i.e., to enable vertical mode. it's an area one @ref Fingers
 358  * "finger" wide on the bottom side of the index widget's container.
 359  *
 360  * @note Vertical mode is set by default.
 361  *
 362  * On horizontal mode items are displayed on index from left to right,
 363  * instead of from top to bottom. Also, the index will scroll horizontally.
 364  *
 365  * @see elm_index_horizontal_get()
 366  *
 367  * @ingroup Index
 368  */
 369 EAPI void                      elm_index_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 370
 371 /**
 372  * Get a value whether horizontal mode is enabled or not.
 373  *
 374  * @param obj The index object.
 375  * @return @c EINA_TRUE means horizontal mode selection is enabled.
 376  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 377  * @c EINA_FALSE is returned.
 378  *
 379  * @see elm_index_horizontal_set() for details.
 380  *
 381  * @ingroup Index
 382  */
 383 EAPI Eina_Bool                 elm_index_horizontal_get(const Evas_Object *obj);
 384
 385 /**
 386  * Set a delay change time for index object.
 387  *
 388  * @param obj The index object.
 389  * @param delay_change_time The delay change time to set.
 390  *
 391  * @note delay time is 0.2 sec by default.
 392  *
 393  * @see elm_index_delay_change_time_get
 394  *
 395  * @ingroup Index
 396  */
 397 EAPI void                      elm_index_delay_change_time_set(Evas_Object *obj, double delay_change_time);
 398
 399 /**
 400  * Get a delay change time for index object.
 401  *
 402  * @param obj The index object.
 403  * @return delay change time in seconds
 404  *
 405  * @see elm_index_delay_change_time_set
 406  *
 407  * @ingroup Index
 408  */
 409 EAPI double                    elm_index_delay_change_time_get(const Evas_Object *obj);
 410
 411 /**
 412  * Enable or disable omit feature for a given index widget.
 413  *
 414  * @param obj The index object
 415  * @param enabled @c EINA_TRUE to enable omit feature, @c EINA_FALSE to disable
 416  *
 417  * @see elm_index_omit_enabled_get()
 418  *
 419  * @ingroup Index
 420  */
 421 EAPI void                      elm_index_omit_enabled_set(Evas_Object *obj, Eina_Bool enabled);
 422
 423 /**
 424  * Get whether omit feature is enabled or not for a given index widget.
 425  *
 426  * @param obj The index object
 427  * @return @c EINA_TRUE, if omit feature is enabled, @c EINA_FALSE otherwise
 428  *
 429  * @see elm_index_omit_enabled_set() for more details
 430  *
 431  * @ingroup Index
 432  */
 433 EAPI Eina_Bool                 elm_index_omit_enabled_get(const Evas_Object *obj);
 434
 435 /**
 436  * Set priority of an item.
 437  *
 438  * @param The index item
 439  * @param priority
 440  *
 441  * @note priority is -1 by default, which means the item doesn't belong to a group.
 442  *
 443  * The value of the priority starts from 0.
 444  * In elm_index_level_go, the items are sorted in ascending order according to priority.
 445  * Items of the same priority make a group and the primary group is shown by default.
 446  *
 447  * @ingroup Index
 448  */
 449 EAPI void                      elm_index_item_priority_set(Elm_Object_Item *it, int priority);
 450
 451 /**
 452  * @}
 453  */