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    *elm_index_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  64
  65    /**
  66     * Set whether a given index widget is or not visible,
  67     * programatically.
  68     *
  69     * @param obj The index object
  70     * @param active @c EINA_TRUE to show it, @c EINA_FALSE to hide it
  71     *
  72     * Not to be confused with visible as in @c evas_object_show() --
  73     * visible with regard to the widget's auto hiding feature.
  74     *
  75     * @see elm_index_active_get()
  76     *
  77     * @ingroup Index
  78     */
  79    EAPI void            elm_index_active_set(Evas_Object *obj, Eina_Bool active) EINA_ARG_NONNULL(1);
  80
  81    /**
  82     * Get whether a given index widget is currently visible or not.
  83     *
  84     * @param obj The index object
  85     * @return @c EINA_TRUE, if it's shown, @c EINA_FALSE otherwise
  86     *
  87     * @see elm_index_active_set() for more details
  88     *
  89     * @ingroup Index
  90     */
  91    EAPI Eina_Bool       elm_index_active_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  92
  93    /**
  94     * Set the items level for a given index widget.
  95     *
  96     * @param obj The index object.
  97     * @param level @c 0 or @c 1, the currently implemented levels.
  98     *
  99     * @see elm_index_item_level_get()
 100     *
 101     * @ingroup Index
 102     */
 103    EAPI void            elm_index_item_level_set(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
 104
 105    /**
 106     * Get the items level set for a given index widget.
 107     *
 108     * @param obj The index object.
 109     * @return @c 0 or @c 1, which are the levels @p obj might be at.
 110     *
 111     * @see elm_index_item_level_set() for more information
 112     *
 113     * @ingroup Index
 114     */
 115    EAPI int             elm_index_item_level_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 116
 117    /**
 118     * Returns the last selected item, for a given index widget.
 119     *
 120     * @param obj The index object.
 121     * @return The last item @b selected on @p obj (or @c NULL, on errors).
 122     *
 123     * @ingroup Index
 124     */
 125    EAPI Elm_Object_Item *elm_index_item_selected_get(const Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
 126
 127    /**
 128     * Append a new item on a given index widget.
 129     *
 130     * @param obj The index object.
 131     * @param letter Letter under which the item should be indexed
 132     * @param item The item data to set for the index's item
 133     *
 134     * Despite the most common usage of the @p letter argument is for
 135     * single char strings, one could use arbitrary strings as index
 136     * entries.
 137     *
 138     * @c item will be the pointer returned back on @c "changed", @c
 139     * "delay,changed" and @c "selected" smart events.
 140     *
 141     * @ingroup Index
 142     */
 143    EAPI void            elm_index_item_append(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
 144
 145    /**
 146     * Prepend a new item on a given index widget.
 147     *
 148     * @param obj The index object.
 149     * @param letter Letter under which the item should be indexed
 150     * @param item The item data to set for the index's item
 151     *
 152     * Despite the most common usage of the @p letter argument is for
 153     * single char strings, one could use arbitrary strings as index
 154     * entries.
 155     *
 156     * @c item will be the pointer returned back on @c "changed", @c
 157     * "delay,changed" and @c "selected" smart events.
 158     *
 159     * @ingroup Index
 160     */
 161    EAPI void            elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
 162
 163    /**
 164     * Append a new item, on a given index widget, <b>after the item
 165     * having @p relative as data</b>.
 166     *
 167     * @param obj The index object.
 168     * @param letter Letter under which the item should be indexed
 169     * @param item The item data to set for the index's item
 170     * @param relative The index item to be the predecessor of this new one
 171     *
 172     * Despite the most common usage of the @p letter argument is for
 173     * single char strings, one could use arbitrary strings as index
 174     * entries.
 175     *
 176     * @c item will be the pointer returned back on @c "changed", @c
 177     * "delay,changed" and @c "selected" smart events.
 178     *
 179     * @note If @p relative is @c NULL this function will behave as
 180     * elm_index_item_append().
 181     *
 182     * @ingroup Index
 183     */
 184    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);
 185
 186    /**
 187     * Prepend a new item, on a given index widget, <b>after the item
 188     * having @p relative as data</b>.
 189     *
 190     * @param obj The index object.
 191     * @param letter Letter under which the item should be indexed
 192     * @param item The item data to set for the index's item
 193     * @param relative The index item to be the successor of this new one
 194     *
 195     * Despite the most common usage of the @p letter argument is for
 196     * single char strings, one could use arbitrary strings as index
 197     * entries.
 198     *
 199     * @c item will be the pointer returned back on @c "changed", @c
 200     * "delay,changed" and @c "selected" smart events.
 201     *
 202     * @note If @p relative is @c NULL this function will behave as
 203     * elm_index_item_prepend().
 204     *
 205     * @ingroup Index
 206     */
 207    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);
 208
 209    /**
 210     * Insert a new item into the given index widget, using @p cmp_func
 211     * function to sort items (by item handles).
 212     *
 213     * @param obj The index object.
 214     * @param letter Letter under which the item should be indexed
 215     * @param item The item data to set for the index's item
 216     * @param cmp_func The comparing function to be used to sort index
 217     * items <b>by #index item handles</b>
 218     * @param cmp_data_func A @b fallback function to be called for the
 219     * sorting of index items <b>by item data</b>). It will be used
 220     * when @p cmp_func returns @c 0 (equality), which means an index
 221     * item with provided item data already exists. To decide which
 222     * data item should be pointed to by the index item in question, @p
 223     * cmp_data_func will be used. If @p cmp_data_func returns a
 224     * non-negative value, the previous index item data will be
 225     * replaced by the given @p item pointer. If the previous data need
 226     * to be freed, it should be done by the @p cmp_data_func function,
 227     * because all references to it will be lost. If this function is
 228     * not provided (@c NULL is given), index items will be @b
 229     * duplicated, if @p cmp_func returns @c 0.
 230     *
 231     * Despite the most common usage of the @p letter argument is for
 232     * single char strings, one could use arbitrary strings as index
 233     * entries.
 234     *
 235     * @c item will be the pointer returned back on @c "changed", @c
 236     * "delay,changed" and @c "selected" smart events.
 237     *
 238     * @ingroup Index
 239     */
 240    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);
 241
 242    /**
 243     * Remove an item from a given index widget, <b>to be referenced by
 244     * it's data value</b>.
 245     *
 246     * @param obj The index object
 247     * @param item The item to be removed from @p obj
 248     *
 249     * If a deletion callback is set, via elm_index_item_del_cb_set(),
 250     * that callback function will be called by this one.
 251     *
 252     * @ingroup Index
 253     */
 254    EAPI void            elm_index_item_del(Evas_Object *obj, Elm_Object_Item *item) EINA_ARG_NONNULL(1);
 255
 256    /**
 257     * Find a given index widget's item, <b>using item data</b>.
 258     *
 259     * @param obj The index object
 260     * @param item The item data pointed to by the desired index item
 261     * @return The index item handle, if found, or @c NULL otherwise
 262     *
 263     * @ingroup Index
 264     */
 265    EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
 266
 267    /**
 268     * Removes @b all items from a given index widget.
 269     *
 270     * @param obj The index object.
 271     *
 272     * If deletion callbacks are set, via elm_index_item_del_cb_set(),
 273     * that callback function will be called for each item in @p obj.
 274     *
 275     * @ingroup Index
 276     */
 277    EAPI void            elm_index_item_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 278
 279    /**
 280     * Go to a given items level on a index widget
 281     *
 282     * @param obj The index object
 283     * @param level The index level (one of @c 0 or @c 1)
 284     *
 285     * @ingroup Index
 286     */
 287    EAPI void            elm_index_item_go(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
 288
 289    /**
 290     * Return the data associated with a given index widget item
 291     *
 292     * @param it The index widget item handle
 293     * @return The data associated with @p it
 294     * @deprecated Use elm_object_item_data_get() instead
 295     *
 296     * @see elm_index_item_data_set()
 297     *
 298     * @ingroup Index
 299     */
 300    EINA_DEPRECATED EAPI void           *elm_index_item_data_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
 301
 302    /**
 303     * Set the data associated with a given index widget item
 304     *
 305     * @param it The index widget item handle
 306     * @param data The new data pointer to set to @p it
 307     *
 308     * This sets new item data on @p it.
 309     *
 310     * @warning The old data pointer won't be touched by this function, so
 311     * the user had better to free that old data himself/herself.
 312     *
 313     * @deprecated Use elm_object_item_data_set() instead
 314     * @ingroup Index
 315     */
 316     EINA_DEPRECATED EAPI void            elm_index_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
 317
 318    /**
 319     * Set the function to be called when a given index widget item is freed.
 320     *
 321     * @param it The item to set the callback on
 322     * @param func The function to call on the item's deletion
 323     *
 324     * When called, @p func will have both @c data and @c event_info
 325     * arguments with the @p it item's data value and, naturally, the
 326     * @c obj argument with a handle to the parent index widget.
 327     *
 328     * @ingroup Index
 329     */
 330    EAPI void            elm_index_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 331
 332    /**
 333     * Get the letter (string) set on a given index widget item.
 334     *
 335     * @param it The index item handle
 336     * @return The letter string set on @p it
 337     *
 338     * @ingroup Index
 339     */
 340    EAPI const char     *elm_index_item_letter_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
 341
 342    /**
 343     * @}
 344     */
 345