src/lib/elm_index.h

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