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