src/lib/elm_index.h

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