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);
  64
  65 /**
  66  * Enable or disable auto hiding feature for a given index widget.
  67  *
  68  * @param obj The index object
  69  * @param active @c EINA_TRUE to enable auto hiding, @c EINA_FALSE to disable
  70  *
  71  * @see elm_index_active_get()
  72  *
  73  * @ingroup Index
  74  */
  75 EAPI void                  elm_index_active_set(Evas_Object *obj, Eina_Bool active);
  76
  77 /**
  78  * Get whether auto hiding feature is enabled or not for a given index widget.
  79  *
  80  * @param obj The index object
  81  * @return @c EINA_TRUE, if auto hiding is enabled, @c EINA_FALSE otherwise
  82  *
  83  * @see elm_index_active_set() for more details
  84  *
  85  * @ingroup Index
  86  */
  87 EAPI Eina_Bool             elm_index_active_get(const Evas_Object *obj);
  88
  89 /**
  90  * Set the items level for a given index widget.
  91  *
  92  * @param obj The index object.
  93  * @param level @c 0 or @c 1, the currently implemented levels.
  94  *
  95  * @see elm_index_item_level_get()
  96  *
  97  * @ingroup Index
  98  */
  99 EAPI void                  elm_index_item_level_set(Evas_Object *obj, int level);
 100
 101 /**
 102  * Get the items level set for a given index widget.
 103  *
 104  * @param obj The index object.
 105  * @return @c 0 or @c 1, which are the levels @p obj might be at.
 106  *
 107  * @see elm_index_item_level_set() for more information
 108  *
 109  * @ingroup Index
 110  */
 111 EAPI int                   elm_index_item_level_get(const Evas_Object *obj);
 112
 113 /**
 114  * Returns the last selected item, for a given index widget.
 115  *
 116  * @param obj The index object.
 117  * @return The last item @b selected on @p obj (or @c NULL, on errors).
 118  *
 119  * @ingroup Index
 120  */
 121 EAPI Elm_Object_Item      *elm_index_item_selected_get(const Evas_Object *obj, int level);
 122
 123 /**
 124  * Append a new item on a given index widget.
 125  *
 126  * @param obj The index object.
 127  * @param letter Letter under which the item should be indexed
 128  * @param item The item data to set for the index's item
 129  *
 130  * Despite the most common usage of the @p letter argument is for
 131  * single char strings, one could use arbitrary strings as index
 132  * entries.
 133  *
 134  * @c item will be the pointer returned back on @c "changed", @c
 135  * "delay,changed" and @c "selected" smart events.
 136  *
 137  * @ingroup Index
 138  */
 139 //XXX: Should be changed like Elm_Object_Item *elm_index_item_append(Evas_Object *obj, const char* letter, const void *data);
 140 EAPI void                  elm_index_item_append(Evas_Object *obj, const char *letter, const void *item);
 141
 142 /**
 143  * Prepend a new item on a given index widget.
 144  *
 145  * @param obj The index object.
 146  * @param letter Letter under which the item should be indexed
 147  * @param item The item data to set for the index's item
 148  *
 149  * Despite the most common usage of the @p letter argument is for
 150  * single char strings, one could use arbitrary strings as index
 151  * entries.
 152  *
 153  * @c item will be the pointer returned back on @c "changed", @c
 154  * "delay,changed" and @c "selected" smart events.
 155  *
 156  * @ingroup Index
 157  */
 158 //XXX: Should be changed like Elm_Object_Item *elm_index_item_prepend(Evas_Object *obj, const char* letter, const void *data);
 159 EAPI void                  elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item);
 160
 161 /**
 162  * Append a new item, on a given index widget, <b>after the item
 163  * having @p relative as data</b>.
 164  *
 165  * @param obj The index object.
 166  * @param letter Letter under which the item should be indexed
 167  * @param item The item data to set for the index's item
 168  * @param relative The index item to be the predecessor of this new one
 169  *
 170  * Despite the most common usage of the @p letter argument is for
 171  * single char strings, one could use arbitrary strings as index
 172  * entries.
 173  *
 174  * @c item will be the pointer returned back on @c "changed", @c
 175  * "delay,changed" and @c "selected" smart events.
 176  *
 177  * @note If @p relative is @c NULL this function will behave as
 178  * elm_index_item_append().
 179  *
 180  * @ingroup Index
 181  */
 182 //XXX: Should be changed like Elm_Object_Item *elm_index_item_insert_after(Evas_Object *obj, const Elm_Object_Item *after, const char* letter, const void *data);
 183 EAPI void                  elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
 184
 185 /**
 186  * Prepend a new item, on a given index widget, <b>after the item
 187  * having @p relative as data</b>.
 188  *
 189  * @param obj The index object.
 190  * @param letter Letter under which the item should be indexed
 191  * @param item The item data to set for the index's item
 192  * @param relative The index item to be the successor of this new one
 193  *
 194  * Despite the most common usage of the @p letter argument is for
 195  * single char strings, one could use arbitrary strings as index
 196  * entries.
 197  *
 198  * @c item will be the pointer returned back on @c "changed", @c
 199  * "delay,changed" and @c "selected" smart events.
 200  *
 201  * @note If @p relative is @c NULL this function will behave as
 202  * elm_index_item_prepend().
 203  *
 204  * @ingroup Index
 205  */
 206 //XXX: Should be changed like Elm_Object_Item *elm_index_item_insert_before(Evas_Object *obj, const Elm_Object_Item *before, const char* letter, const void *data);
 207 EAPI void                  elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
 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 //XXX: Should be changed like Elm_Object_Item *elm_index_item_sorted_insert(Evas_Object *obj, const char* letter, const void *data, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func);
 241 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);
 242
 243 /**
 244  * Find a given index widget's item, <b>using item data</b>.
 245  *
 246  * @param obj The index object
 247  * @param item The item data pointed to by the desired index item
 248  * @return The index item handle, if found, or @c NULL otherwise
 249  *
 250  * @ingroup Index
 251  */
 252 //XXX: After changing above APIs, this should be deprecated.
 253 EAPI Elm_Object_Item      *elm_index_item_find(Evas_Object *obj, const void *item);
 254
 255 /**
 256  * Removes @b all items from a given index widget.
 257  *
 258  * @param obj The index object.
 259  *
 260  * If deletion callbacks are set, via elm_object_item_del_cb_set(),
 261  * that callback function will be called for each item in @p obj.
 262  *
 263  * @ingroup Index
 264  */
 265 EAPI void                  elm_index_item_clear(Evas_Object *obj);
 266
 267 /**
 268  * Go to a given items level on a index widget
 269  *
 270  * @param obj The index object
 271  * @param level The index level (one of @c 0 or @c 1)
 272  *
 273  * @ingroup Index
 274  */
 275 //XXX: how about elm_index_level_go ??
 276 EAPI void                  elm_index_item_go(Evas_Object *obj, int level);
 277
 278 /**
 279  * Get the letter (string) set on a given index widget item.
 280  *
 281  * @param item The index item handle
 282  * @return The letter string set on @p it
 283  *
 284  * @ingroup Index
 285  */
 286 EAPI const char           *elm_index_item_letter_get(const Elm_Object_Item *item);
 287
 288 /**
 289  * Set the indicator as to be disabled.
 290  *
 291  * @param obj The index object
 292  * @param disabled  @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
 293  *
 294  * In Index widget, Indicator notes popup text, which shows a letter has been selecting.
 295  *
 296  * @see elm_index_indicator_disabled_get()
 297  *
 298  * @ingroup Index
 299  */
 300 EAPI void                 elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 301
 302 /**
 303  * Get the value of indicator's disabled status.
 304  *
 305  * @param obj The index object
 306  * @return EINA_TRUE if the indicator is disabled.
 307  *
 308  * @see elm_index_indicator_disabled_set()
 309  *
 310  * @ingroup Index
 311  */
 312 EAPI Eina_Bool                 elm_index_indicator_disabled_get(const Evas_Object *obj);
 313
 314 /**
 315  * @}
 316  */