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