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 <<<<<<< HEAD
  70  * @param active @c EINA_TRUE to enable auto hiding, @c EINA_FALSE to disable
  71  *
  72  * @see elm_index_active_get()
  73  *
  74  * @ingroup Index
  75  */
  76 EAPI void                  elm_index_active_set(Evas_Object *obj, Eina_Bool active);
  77 =======
  78  * @param disabled @c EINA_TRUE to disable auto hiding, @c EINA_FALSE to enable
  79  *
  80  * @see elm_index_autohide_disabled_get()
  81  *
  82  * @ingroup Index
  83  */
  84 EAPI void                  elm_index_autohide_disabled_set(Evas_Object *obj, Eina_Bool disabled);
  85 >>>>>>> remotes/origin/upstream
  86
  87 /**
  88  * Get whether auto hiding feature is enabled or not for a given index widget.
  89  *
  90  * @param obj The index object
  91 <<<<<<< HEAD
  92  * @return @c EINA_TRUE, if auto hiding is enabled, @c EINA_FALSE otherwise
  93 =======
  94  * @return @c EINA_TRUE, if auto hiding is disabled, @c EINA_FALSE otherwise
  95 >>>>>>> remotes/origin/upstream
  96  *
  97  * @see elm_index_active_set() for more details
  98  *
  99  * @ingroup Index
 100  */
 101 <<<<<<< HEAD
 102 EAPI Eina_Bool             elm_index_active_get(const Evas_Object *obj);
 103 =======
 104 EAPI Eina_Bool             elm_index_autohide_disabled_get(const Evas_Object *obj);
 105 >>>>>>> remotes/origin/upstream
 106
 107 /**
 108  * Set the items level for a given index widget.
 109  *
 110  * @param obj The index object.
 111  * @param level @c 0 or @c 1, the currently implemented levels.
 112  *
 113  * @see elm_index_item_level_get()
 114  *
 115  * @ingroup Index
 116  */
 117 EAPI void                  elm_index_item_level_set(Evas_Object *obj, int level);
 118
 119 /**
 120  * Get the items level set for a given index widget.
 121  *
 122  * @param obj The index object.
 123  * @return @c 0 or @c 1, which are the levels @p obj might be at.
 124  *
 125  * @see elm_index_item_level_set() for more information
 126  *
 127  * @ingroup Index
 128  */
 129 EAPI int                   elm_index_item_level_get(const Evas_Object *obj);
 130
 131 /**
 132 <<<<<<< HEAD
 133 =======
 134  * Set the selected state of an item.
 135  *
 136  * @param it The index item
 137  * @param selected The selected state
 138  *
 139  * This sets the selected state of the given item @p it.
 140  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 141  *
 142  * If a new item is selected the previously selected will be unselected.
 143  * Previously selected item can be get with function
 144  * elm_index_selected_item_get().
 145  *
 146  * Selected items will be highlighted.
 147  *
 148  * @see elm_index_item_selected_get()
 149  * @see elm_index_selected_item_get()
 150  *
 151  * @ingroup Index
 152  */
 153 EAPI void                  elm_index_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 154
 155 /**
 156 >>>>>>> remotes/origin/upstream
 157  * Returns the last selected item, for a given index widget.
 158  *
 159  * @param obj The index object.
 160  * @return The last item @b selected on @p obj (or @c NULL, on errors).
 161  *
 162  * @ingroup Index
 163  */
 164 <<<<<<< HEAD
 165 EAPI Elm_Object_Item      *elm_index_item_selected_get(const Evas_Object *obj, int level);
 166 =======
 167 EAPI Elm_Object_Item      *elm_index_selected_item_get(const Evas_Object *obj, int level);
 168 >>>>>>> remotes/origin/upstream
 169
 170 /**
 171  * Append 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 <<<<<<< HEAD
 176  * @param item The item data to set for the index's item
 177 =======
 178  * @param func The function to call when the item is selected.
 179  * @param data The item data to set for the index's item
 180  * @return A handle to the item added or @c NULL, on errors
 181 >>>>>>> remotes/origin/upstream
 182  *
 183  * Despite the most common usage of the @p letter argument is for
 184  * single char strings, one could use arbitrary strings as index
 185  * entries.
 186  *
 187  * @c item will be the pointer returned back on @c "changed", @c
 188  * "delay,changed" and @c "selected" smart events.
 189  *
 190  * @ingroup Index
 191  */
 192 <<<<<<< HEAD
 193 EAPI void                  elm_index_item_append(Evas_Object *obj, const char *letter, const void *item);
 194 =======
 195 EAPI Elm_Object_Item      *elm_index_item_append(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
 196 >>>>>>> remotes/origin/upstream
 197
 198 /**
 199  * Prepend a new item on a given index widget.
 200  *
 201  * @param obj The index object.
 202  * @param letter Letter under which the item should be indexed
 203 <<<<<<< HEAD
 204  * @param item The item data to set for the index's item
 205 =======
 206  * @param func The function to call when the item is selected.
 207  * @param data The item data to set for the index's item
 208  * @return A handle to the item added or @c NULL, on errors
 209 >>>>>>> remotes/origin/upstream
 210  *
 211  * Despite the most common usage of the @p letter argument is for
 212  * single char strings, one could use arbitrary strings as index
 213  * entries.
 214  *
 215  * @c item will be the pointer returned back on @c "changed", @c
 216  * "delay,changed" and @c "selected" smart events.
 217  *
 218  * @ingroup Index
 219  */
 220 <<<<<<< HEAD
 221 EAPI void                  elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item);
 222
 223 /**
 224  * Append a new item, on a given index widget, <b>after the item
 225  * having @p relative as data</b>.
 226  *
 227  * @param obj The index object.
 228  * @param letter Letter under which the item should be indexed
 229  * @param item The item data to set for the index's item
 230  * @param relative The index item to be the predecessor of this new one
 231 =======
 232 EAPI Elm_Object_Item      *elm_index_item_prepend(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
 233
 234 /**
 235  * Insert a new item into the index object after item @p after.
 236  *
 237  * @param obj The index object.
 238  * @param after The index item to insert after.
 239  * @param letter Letter under which the item should be indexed
 240  * @param func The function to call when the item is clicked.
 241  * @param data The item data to set for the index's item
 242  * @return A handle to the item added or @c NULL, on errors
 243 >>>>>>> remotes/origin/upstream
 244  *
 245  * Despite the most common usage of the @p letter argument is for
 246  * single char strings, one could use arbitrary strings as index
 247  * entries.
 248  *
 249  * @c item will be the pointer returned back on @c "changed", @c
 250  * "delay,changed" and @c "selected" smart events.
 251  *
 252  * @note If @p relative is @c NULL this function will behave as
 253  * elm_index_item_append().
 254  *
 255  * @ingroup Index
 256  */
 257 <<<<<<< HEAD
 258 EAPI void                  elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
 259
 260 /**
 261  * Prepend a new item, on a given index widget, <b>after the item
 262  * having @p relative as data</b>.
 263  *
 264  * @param obj The index object.
 265  * @param letter Letter under which the item should be indexed
 266  * @param item The item data to set for the index's item
 267  * @param relative The index item to be the successor of this new one
 268 =======
 269 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);
 270
 271 /**
 272  * Insert a new item into the index object before item @p before.
 273  *
 274  * @param obj The index object.
 275  * @param before The index item to insert after.
 276  * @param letter Letter under which the item should be indexed
 277  * @param func The function to call when the item is clicked.
 278  * @param data The item data to set for the index's item
 279  * @return A handle to the item added or @c NULL, on errors
 280 >>>>>>> remotes/origin/upstream
 281  *
 282  * Despite the most common usage of the @p letter argument is for
 283  * single char strings, one could use arbitrary strings as index
 284  * entries.
 285  *
 286  * @c item will be the pointer returned back on @c "changed", @c
 287  * "delay,changed" and @c "selected" smart events.
 288  *
 289  * @note If @p relative is @c NULL this function will behave as
 290  * elm_index_item_prepend().
 291  *
 292  * @ingroup Index
 293  */
 294 <<<<<<< HEAD
 295 EAPI void                  elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
 296 =======
 297 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);
 298 >>>>>>> remotes/origin/upstream
 299
 300 /**
 301  * Insert a new item into the given index widget, using @p cmp_func
 302  * function to sort items (by item handles).
 303  *
 304  * @param obj The index object.
 305  * @param letter Letter under which the item should be indexed
 306 <<<<<<< HEAD
 307  * @param item The item data to set for the index's item
 308 =======
 309  * @param func The function to call when the item is clicked.
 310  * @param data The item data to set for the index's item
 311 >>>>>>> remotes/origin/upstream
 312  * @param cmp_func The comparing function to be used to sort index
 313  * items <b>by #index item handles</b>
 314  * @param cmp_data_func A @b fallback function to be called for the
 315  * sorting of index items <b>by item data</b>). It will be used
 316  * when @p cmp_func returns @c 0 (equality), which means an index
 317  * item with provided item data already exists. To decide which
 318  * data item should be pointed to by the index item in question, @p
 319  * cmp_data_func will be used. If @p cmp_data_func returns a
 320  * non-negative value, the previous index item data will be
 321  * replaced by the given @p item pointer. If the previous data need
 322  * to be freed, it should be done by the @p cmp_data_func function,
 323  * because all references to it will be lost. If this function is
 324  * not provided (@c NULL is given), index items will be @b
 325  * duplicated, if @p cmp_func returns @c 0.
 326 <<<<<<< HEAD
 327 =======
 328  * @return A handle to the item added or @c NULL, on errors
 329 >>>>>>> remotes/origin/upstream
 330  *
 331  * Despite the most common usage of the @p letter argument is for
 332  * single char strings, one could use arbitrary strings as index
 333  * entries.
 334  *
 335  * @c item will be the pointer returned back on @c "changed", @c
 336  * "delay,changed" and @c "selected" smart events.
 337  *
 338  * @ingroup Index
 339  */
 340 <<<<<<< HEAD
 341 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);
 342 =======
 343 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);
 344 >>>>>>> remotes/origin/upstream
 345
 346 /**
 347  * Find a given index widget's item, <b>using item data</b>.
 348  *
 349  * @param obj The index object
 350 <<<<<<< HEAD
 351  * @param item The item data pointed to by the desired index item
 352 =======
 353  * @param data The item data pointed to by the desired index item
 354 >>>>>>> remotes/origin/upstream
 355  * @return The index item handle, if found, or @c NULL otherwise
 356  *
 357  * @ingroup Index
 358  */
 359 <<<<<<< HEAD
 360 EAPI Elm_Object_Item      *elm_index_item_find(Evas_Object *obj, const void *item);
 361 =======
 362 EAPI Elm_Object_Item      *elm_index_item_find(Evas_Object *obj, const void *data);
 363 >>>>>>> remotes/origin/upstream
 364
 365 /**
 366  * Removes @b all items from a given index widget.
 367  *
 368  * @param obj The index object.
 369  *
 370  * If deletion callbacks are set, via elm_object_item_del_cb_set(),
 371  * that callback function will be called for each item in @p obj.
 372  *
 373  * @ingroup Index
 374  */
 375 EAPI void                  elm_index_item_clear(Evas_Object *obj);
 376
 377 /**
 378  * Go to a given items level on a index widget
 379  *
 380  * @param obj The index object
 381  * @param level The index level (one of @c 0 or @c 1)
 382  *
 383  * @ingroup Index
 384  */
 385 <<<<<<< HEAD
 386 EAPI void                  elm_index_item_go(Evas_Object *obj, int level);
 387 =======
 388 EAPI void                  elm_index_level_go(Evas_Object *obj, int level);
 389 >>>>>>> remotes/origin/upstream
 390
 391 /**
 392  * Get the letter (string) set on a given index widget item.
 393  *
 394  * @param item The index item handle
 395  * @return The letter string set on @p it
 396  *
 397  * @ingroup Index
 398  */
 399 EAPI const char           *elm_index_item_letter_get(const Elm_Object_Item *item);
 400
 401 /**
 402  * Set the indicator as to be disabled.
 403  *
 404  * @param obj The index object
 405  * @param disabled  @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
 406  *
 407  * In Index widget, Indicator notes popup text, which shows a letter has been selecting.
 408  *
 409  * @see elm_index_indicator_disabled_get()
 410  *
 411  * @ingroup Index
 412  */
 413 EAPI void                 elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled);
 414
 415 /**
 416  * Get the value of indicator's disabled status.
 417  *
 418  * @param obj The index object
 419  * @return EINA_TRUE if the indicator is disabled.
 420  *
 421  * @see elm_index_indicator_disabled_set()
 422  *
 423  * @ingroup Index
 424  */
 425 <<<<<<< HEAD
 426 EAPI Eina_Bool                 elm_index_indicator_disabled_get(const Evas_Object *obj);
 427
 428 EAPI void                  elm_index_button_image_invisible_set(Evas_Object *obj, Eina_Bool invisible);
 429 =======
 430 EAPI Eina_Bool            elm_index_indicator_disabled_get(const Evas_Object *obj);
 431
 432 /**
 433  * Enable or disable horizontal mode on the index object
 434  *
 435  * @param obj The index object.
 436  * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
 437  * disable it, i.e., to enable vertical mode. it's an area one @ref Fingers
 438  * "finger" wide on the bottom side of the index widget's container.
 439  *
 440  * @note Vertical mode is set by default.
 441  *
 442  * On horizontal mode items are displayed on index from left to right,
 443  * instead of from top to bottom. Also, the index will scroll horizontally.
 444  *
 445  * @see elm_index_horizontal_get()
 446  *
 447  * @ingroup Index
 448  */
 449 EAPI void                      elm_index_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 450
 451 /**
 452  * Get a value whether horizontal mode is enabled or not.
 453  *
 454  * @param obj The index object.
 455  * @return @c EINA_TRUE means horizontal mode selection is enabled.
 456  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 457  * @c EINA_FALSE is returned.
 458  *
 459  * @see elm_index_horizontal_set() for details.
 460  *
 461  * @ingroup Index
 462  */
 463 EAPI Eina_Bool                 elm_index_horizontal_get(const Evas_Object *obj);
 464 >>>>>>> remotes/origin/upstream
 465
 466 /**
 467  * @}
 468  */