wearable/src/lib/elm_list.h

   1 /**
   2  * @defgroup List List
   3  * @ingroup Elementary
   4  *
   5  * @image html list_inheritance_tree.png
   6  * @image latex list_inheritance_tree.eps
   7  *
   8  * @image html img/widget/list/preview-00.png
   9  * @image latex img/widget/list/preview-00.eps width=\textwidth
  10  *
  11  * @image html img/list.png
  12  * @image latex img/list.eps width=\textwidth
  13  *
  14  * A list widget is a container whose children are displayed
  15  * vertically or horizontally, in order, and can be selected. The list
  16  * can accept only one or multiple item selections. Also has many
  17  * modes of items displaying.
  18  *
  19  * A list is a very simple type of list widget. For more robust lists,
  20  * @ref Genlist should probably be used.
  21  *
  22  * This widget inherits from the @ref Layout one, so that all the
  23  * functions acting on it also work for list objects.
  24  *
  25  * This widget emits the following signals, besides the ones sent from
  26  * @ref Layout:
  27  * - @c "activated" - The user has double-clicked or pressed
  28  *   (enter|return|spacebar) on an item. The @c event_info parameter
  29  *   is the item that was activated.
  30  * - @c "clicked,double" - The user has double-clicked an item.
  31  *   The @c event_info parameter is the item that was double-clicked.
  32  * - @c "selected" - when the user selected an item
  33  * - @c "unselected" - when the user unselected an item
  34  * - @c "longpressed" - an item in the list is long-pressed
  35  * - @c "edge,top" - the list is scrolled until the top edge
  36  * - @c "edge,bottom" - the list is scrolled until the bottom edge
  37  * - @c "edge,left" - the list is scrolled until the left edge
  38  * - @c "edge,right" - the list is scrolled until the right edge
  39  * - @c "language,changed" - the program's language changed
  40  * - @c "highlighted" - an item in the list is pressed and highlighted.
  41  *   The %c event_info parameter is the item that was highlighted.
  42  * - @c "unhighlighted" - an item in the list is unpressed and unhighlighted.
  43  *   The %c event_info parameter is the item that was unhighlighted.
  44  *
  45  *
  46  *
  47  * Available styles for it are:
  48  * - @c "default"
  49  *
  50  * Default content parts of the list items that you can use are:
  51  * @li @c "start" - A start position object in the list item
  52  * @li @c "end" - An end position object in the list item
  53  *
  54  * Default text parts of the list items that you can use are:
  55  * @li @c "default" - label in the list item
  56  *
  57  * Supported @c elm_object_item common APIs.
  58  * @li @ref elm_object_item_disabled_set
  59  * @li @ref elm_object_item_disabled_get
  60  * @li @ref elm_object_item_part_text_set
  61  * @li @ref elm_object_item_part_text_get
  62  * @li @ref elm_object_item_part_content_set
  63  * @li @ref elm_object_item_part_content_get
  64  * @li @ref elm_object_item_part_content_unset
  65  *
  66  * This widget implements the @b @ref elm-scrollable-interface
  67  * interface, so that all (non-deprecated) functions for the base @ref
  68  * Scroller widget also work for lists.
  69  *
  70  * Some calls on the list's API are marked as @b deprecated, as they
  71  * just wrap the scrollable widgets counterpart functions. Use the
  72  * ones we point you to, for each case of deprecation here, instead --
  73  * eventually the deprecated ones will be discarded (next major
  74  * release).
  75  *
  76  * List of examples:
  77  * @li @ref list_example_01
  78  * @li @ref list_example_02
  79  * @li @ref list_example_03
  80  */
  81
  82 /**
  83  * @addtogroup List
  84  * @{
  85  */
  86
  87 /**
  88  * @enum Elm_List_Mode
  89  * @typedef Elm_List_Mode
  90  *
  91  * Set list's resizing behavior, transverse axis scrolling and items
  92  * cropping. See each mode's description for more details.
  93  *
  94  * @note Default value is #ELM_LIST_SCROLL.
  95  *
  96  * Values here @b don't work as bitmasks -- only one can be chosen at
  97  * a time.
  98  *
  99  * @see elm_list_mode_set()
 100  * @see elm_list_mode_get()
 101  *
 102  * @ingroup List
 103  */
 104 typedef enum
 105 {
 106    ELM_LIST_COMPRESS = 0, /**< The list @b won't set any of its size hints to inform how a possible container should resize it. Then, if it's not created as a "resize object", it might end with zeroed dimensions. The list will respect the container's geometry and, if any of its items won't fit into its @b transverse axis, one won't be able to scroll it in that direction. */
 107    ELM_LIST_SCROLL, /**< Default value. This is the same as #ELM_LIST_COMPRESS, with the exception that if any of its items won't fit into its transverse axis, one @b will be able to scroll it in that direction. */
 108    ELM_LIST_LIMIT, /**< Sets a minimum size hint on the list object, so that containers may respect it (and resize itself to fit the child properly). More specifically, a @b minimum size hint will be set for its @b transverse axis, so that the @b largest item in that direction fits well. This is naturally bound by the list object's maximum size hints, set externally. */
 109    ELM_LIST_EXPAND, /**< Besides setting a minimum size on the transverse axis, just like on #ELM_LIST_LIMIT, the list will set a minimum size on the @b longitudinal axis, trying to reserve space to all its children to be visible at a time. . This is naturally bound by the list object's maximum size hints, set externally. */
 110    ELM_LIST_LAST /**< Indicates error if returned by elm_list_mode_get() */
 111 } Elm_List_Mode;
 112
 113 /**
 114  * Add a new list widget to the given parent Elementary
 115  * (container) object.
 116  *
 117  * @param parent The parent object.
 118  * @return a new list widget handle or @c NULL, on errors.
 119  *
 120  * This function inserts a new list widget on the canvas.
 121  *
 122  * @ingroup List
 123  */
 124 EAPI Evas_Object                 *elm_list_add(Evas_Object *parent);
 125
 126 /**
 127  * Starts the list.
 128  *
 129  * @param obj The list object
 130  *
 131  * @note Call before running show() on the list object.
 132  * @warning If not called, it won't display the list properly.
 133  *
 134  * @code
 135  * li = elm_list_add(win);
 136  * elm_list_item_append(li, "First", NULL, NULL, NULL, NULL);
 137  * elm_list_item_append(li, "Second", NULL, NULL, NULL, NULL);
 138  * elm_list_go(li);
 139  * evas_object_show(li);
 140  * @endcode
 141  *
 142  * @ingroup List
 143  */
 144 EAPI void                         elm_list_go(Evas_Object *obj);
 145
 146 /**
 147  * Enable or disable multiple items selection on the list object.
 148  *
 149  * @param obj The list object
 150  * @param multi @c EINA_TRUE to enable multi selection or @c EINA_FALSE to
 151  * disable it.
 152  *
 153  * Disabled by default. If disabled, the user can select a single item of
 154  * the list each time. Selected items are highlighted on list.
 155  * If enabled, many items can be selected.
 156  *
 157  * If a selected item is selected again, it will be unselected.
 158  *
 159  * @see elm_list_multi_select_get()
 160  *
 161  * @ingroup List
 162  */
 163 EAPI void                         elm_list_multi_select_set(Evas_Object *obj, Eina_Bool multi);
 164
 165 /**
 166  * Get a value whether multiple items selection is enabled or not.
 167  *
 168  * @see elm_list_multi_select_set() for details.
 169  *
 170  * @param obj The list object.
 171  * @return @c EINA_TRUE means multiple items selection is enabled.
 172  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 173  * @c EINA_FALSE is returned.
 174  *
 175  * @ingroup List
 176  */
 177 EAPI Eina_Bool                    elm_list_multi_select_get(const Evas_Object *obj);
 178
 179 /**
 180  * Set which mode to use for the list object.
 181  *
 182  * @param obj The list object
 183  * @param mode One of #Elm_List_Mode: #ELM_LIST_COMPRESS,
 184  * #ELM_LIST_SCROLL, #ELM_LIST_LIMIT or #ELM_LIST_EXPAND.
 185  *
 186  * Set list's resize behavior, transverse axis scroll and
 187  * items cropping. See each mode's description for more details.
 188  *
 189  * @note Default value is #ELM_LIST_SCROLL.
 190  *
 191  * Only one mode at a time can be set. If a previous one was set, it
 192  * will be changed by the new mode after this call. Bitmasks won't
 193  * work here as well.
 194  *
 195  * @warning This function's behavior will clash with those of
 196  * elm_scroller_content_min_limit(), so use either one of them, but
 197  * not both.
 198  *
 199  * @see elm_list_mode_get()
 200  *
 201  * @ingroup List
 202  */
 203 EAPI void                         elm_list_mode_set(Evas_Object *obj, Elm_List_Mode mode);
 204
 205 /**
 206  * Get the mode the list is at.
 207  *
 208  * @param obj The list object
 209  * @return One of #Elm_List_Mode: #ELM_LIST_COMPRESS, #ELM_LIST_SCROLL, #ELM_LIST_LIMIT, #ELM_LIST_EXPAND or #ELM_LIST_LAST on errors.
 210  *
 211  * @note see elm_list_mode_set() for more information.
 212  *
 213  * @ingroup List
 214  */
 215 EAPI Elm_List_Mode                elm_list_mode_get(const Evas_Object *obj);
 216
 217 /**
 218  * Enable or disable horizontal mode on the list object.
 219  *
 220  * @param obj The list object.
 221  * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
 222  * disable it, i.e., to enable vertical mode.
 223  *
 224  * @note Vertical mode is set by default.
 225  *
 226  * On horizontal mode items are displayed on list from left to right,
 227  * instead of from top to bottom. Also, the list will scroll horizontally.
 228  * Each item will presents left icon on top and right icon, or end, at
 229  * the bottom.
 230  *
 231  * @see elm_list_horizontal_get()
 232  *
 233  * @ingroup List
 234  */
 235 EAPI void                         elm_list_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 236
 237 /**
 238  * Get a value whether horizontal mode is enabled or not.
 239  *
 240  * @param obj The list object.
 241  * @return @c EINA_TRUE means horizontal mode selection is enabled.
 242  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 243  * @c EINA_FALSE is returned.
 244  *
 245  * @see elm_list_horizontal_set() for details.
 246  *
 247  * @ingroup List
 248  */
 249 EAPI Eina_Bool                    elm_list_horizontal_get(const Evas_Object *obj);
 250
 251 /**
 252  * Set the list select mode.
 253  *
 254  * @param obj The list object
 255  * @param mode The select mode
 256  *
 257  * elm_list_select_mode_set() changes item select mode in the list widget.
 258  * - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will only call their selection func and
 259  *      callback when first becoming selected. Any further clicks will
 260  *      do nothing, unless you set always select mode.
 261  * - ELM_OBJECT_SELECT_MODE_ALWAYS :  This means that, even if selected,
 262  *      every click will make the selected callbacks be called.
 263  * - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items
 264  *      entirely and they will neither appear selected nor call selected
 265  *      callback functions.
 266  *
 267  * @see elm_list_select_mode_get()
 268  *
 269  * @ingroup List
 270  */
 271 EAPI void
 272 elm_list_select_mode_set(Evas_Object *obj, Elm_Object_Select_Mode mode);
 273
 274 /**
 275  * Get the list select mode.
 276  *
 277  * @param obj The list object
 278  * @return The select mode
 279  * (If getting mode is failed, it returns ELM_OBJECT_SELECT_MODE_MAX)
 280  *
 281  * @see elm_list_select_mode_set()
 282  *
 283  * @ingroup List
 284  */
 285 EAPI Elm_Object_Select_Mode
 286 elm_list_select_mode_get(const Evas_Object *obj);
 287
 288 /**
 289  * Set bouncing behaviour when the scrolled content reaches an edge.
 290  *
 291  * Tell the internal scroller object whether it should bounce or not
 292  * when it reaches the respective edges for each axis.
 293  *
 294  * @param obj The list object
 295  * @param h_bounce Whether to bounce or not in the horizontal axis.
 296  * @param v_bounce Whether to bounce or not in the vertical axis.
 297  *
 298  * @deprecated Use elm_scroller_bounce_set() instead.
 299  *
 300  * @see elm_scroller_bounce_set()
 301  *
 302  * @ingroup List
 303  */
 304 EINA_DEPRECATED EAPI void         elm_list_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 305
 306 /**
 307  * Get the bouncing behaviour of the internal scroller.
 308  *
 309  * Get whether the internal scroller should bounce when the edge of each
 310  * axis is reached scrolling.
 311  *
 312  * @param obj The list object.
 313  * @param h_bounce Pointer to store the bounce state of the horizontal
 314  * axis.
 315  * @param v_bounce Pointer to store the bounce state of the vertical
 316  * axis.
 317  *
 318  * @deprecated Use elm_scroller_bounce_get() instead.
 319  *
 320  * @see elm_scroller_bounce_get()
 321  * @see elm_list_bounce_set()
 322  *
 323  * @ingroup List
 324  */
 325 EINA_DEPRECATED EAPI void         elm_list_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 326
 327 /**
 328  * Set the scrollbar policy.
 329  *
 330  * @param obj The list object
 331  * @param policy_h Horizontal scrollbar policy.
 332  * @param policy_v Vertical scrollbar policy.
 333  *
 334  * This sets the scrollbar visibility policy for the given
 335  * scroller. #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made
 336  * visible if it is needed, and otherwise kept
 337  * hidden. #ELM_SCROLLER_POLICY_ON turns it on all the time, and
 338  * #ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
 339  * respectively for the horizontal and vertical scrollbars.
 340  *
 341  * The both are disabled by default, i.e., are set to
 342  * #ELM_SCROLLER_POLICY_OFF.
 343  *
 344  * @deprecated Use elm_scroller_policy_set() instead.
 345  *
 346  * @ingroup List
 347  */
 348 EINA_DEPRECATED EAPI void         elm_list_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
 349
 350 /**
 351  * Get the scrollbar policy.
 352  *
 353  * @see elm_list_scroller_policy_get() for details.
 354  *
 355  * @param obj The list object.
 356  * @param policy_h Pointer to store horizontal scrollbar policy.
 357  * @param policy_v Pointer to store vertical scrollbar policy.
 358  *
 359  * @deprecated Use elm_scroller_policy_get() instead.
 360  *
 361  * @ingroup List
 362  */
 363 EINA_DEPRECATED EAPI void         elm_list_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
 364
 365 /**
 366  * Append a new item to the list object.
 367  *
 368  * @param obj The list object.
 369  * @param label The label of the list item.
 370  * @param icon The icon object to use for the left side of the item. An
 371  * icon can be any Evas object, but usually it is an icon created
 372  * with elm_icon_add().
 373  * @param end The icon object to use for the right side of the item. An
 374  * icon can be any Evas object.
 375  * @param func The function to call when the item is clicked.
 376  * @param data The data to associate with the item for related callbacks.
 377  *
 378  * @return The created item or @c NULL upon failure.
 379  *
 380  * A new item will be created and appended to the list, i.e., will
 381  * be set as @b last item.
 382  *
 383  * Items created with this method can be deleted with elm_object_item_del().
 384  *
 385  * Associated @p data can be properly freed when item is deleted if a
 386  * callback function is set with elm_object_item_del_cb_set().
 387  *
 388  * If a function is passed as argument, it will be called every time this item
 389  * is selected, i.e., the user clicks over an unselected item.
 390  * If always select is enabled it will call this function every time
 391  * user clicks over an item (already selected or not).
 392  * If such function isn't needed, just passing
 393  * @c NULL as @p func is enough. The same should be done for @p data.
 394  *
 395  * Simple example (with no function callback or data associated):
 396  * @code
 397  * li = elm_list_add(win);
 398  * ic = elm_icon_add(win);
 399  * elm_image_file_set(ic, "path/to/image", NULL);
 400  * elm_icon_resizable_set(ic, EINA_TRUE, EINA_TRUE);
 401  * elm_list_item_append(li, "label", ic, NULL, NULL, NULL);
 402  * elm_list_go(li);
 403  * evas_object_show(li);
 404  * @endcode
 405  *
 406  * @see elm_list_select_mode_set()
 407  * @see elm_object_item_del()
 408  * @see elm_object_item_del_cb_set()
 409  * @see elm_list_clear()
 410  * @see elm_icon_add()
 411  *
 412  * @ingroup List
 413  */
 414 EAPI Elm_Object_Item               *elm_list_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 415
 416 /**
 417  * Prepend a new item to the list object.
 418  *
 419  * @param obj The list object.
 420  * @param label The label of the list item.
 421  * @param icon The icon object to use for the left side of the item. An
 422  * icon can be any Evas object, but usually it is an icon created
 423  * with elm_icon_add().
 424  * @param end The icon object to use for the right side of the item. An
 425  * icon can be any Evas object.
 426  * @param func The function to call when the item is clicked.
 427  * @param data The data to associate with the item for related callbacks.
 428  *
 429  * @return The created item or @c NULL upon failure.
 430  *
 431  * A new item will be created and prepended to the list, i.e., will
 432  * be set as @b first item.
 433  *
 434  * Items created with this method can be deleted with elm_object_item_del().
 435  *
 436  * Associated @p data can be properly freed when item is deleted if a
 437  * callback function is set with elm_object_item_del_cb_set().
 438  *
 439  * If a function is passed as argument, it will be called every time this item
 440  * is selected, i.e., the user clicks over an unselected item.
 441  * If always select is enabled it will call this function every time
 442  * user clicks over an item (already selected or not).
 443  * If such function isn't needed, just passing
 444  * @c NULL as @p func is enough. The same should be done for @p data.
 445  *
 446  * @see elm_list_item_append() for a simple code example.
 447  * @see elm_list_select_mode_set()
 448  * @see elm_object_item_del()
 449  * @see elm_object_item_del_cb_set()
 450  * @see elm_list_clear()
 451  * @see elm_icon_add()
 452  *
 453  * @ingroup List
 454  */
 455 EAPI Elm_Object_Item               *elm_list_item_prepend(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 456
 457 /**
 458  * Insert a new item into the list object before item @p before.
 459  *
 460  * @param obj The list object.
 461  * @param before The list item to insert before.
 462  * @param label The label of the list item.
 463  * @param icon The icon object to use for the left side of the item. An
 464  * icon can be any Evas object, but usually it is an icon created
 465  * with elm_icon_add().
 466  * @param end The icon object to use for the right side of the item. An
 467  * icon can be any Evas object.
 468  * @param func The function to call when the item is clicked.
 469  * @param data The data to associate with the item for related callbacks.
 470  *
 471  * @return The created item or @c NULL upon failure.
 472  *
 473  * A new item will be created and added to the list. Its position in
 474  * this list will be just before item @p before.
 475  *
 476  * Items created with this method can be deleted with elm_object_item_del().
 477  *
 478  * Associated @p data can be properly freed when item is deleted if a
 479  * callback function is set with elm_object_item_del_cb_set().
 480  *
 481  * If a function is passed as argument, it will be called every time this item
 482  * is selected, i.e., the user clicks over an unselected item.
 483  * If always select is enabled it will call this function every time
 484  * user clicks over an item (already selected or not).
 485  * If such function isn't needed, just passing
 486  * @c NULL as @p func is enough. The same should be done for @p data.
 487  *
 488  * @see elm_list_item_append() for a simple code example.
 489  * @see elm_list_select_mode_set()
 490  * @see elm_object_item_del()
 491  * @see elm_object_item_del_cb_set()
 492  * @see elm_list_clear()
 493  * @see elm_icon_add()
 494  *
 495  * @ingroup List
 496  */
 497 EAPI Elm_Object_Item               *elm_list_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 498
 499 /**
 500  * Insert a new item into the list object after item @p after.
 501  *
 502  * @param obj The list object.
 503  * @param after The list item to insert after.
 504  * @param label The label of the list item.
 505  * @param icon The icon object to use for the left side of the item. An
 506  * icon can be any Evas object, but usually it is an icon created
 507  * with elm_icon_add().
 508  * @param end The icon object to use for the right side of the item. An
 509  * icon can be any Evas object.
 510  * @param func The function to call when the item is clicked.
 511  * @param data The data to associate with the item for related callbacks.
 512  *
 513  * @return The created item or @c NULL upon failure.
 514  *
 515  * A new item will be created and added to the list. Its position in
 516  * this list will be just after item @p after.
 517  *
 518  * Items created with this method can be deleted with elm_object_item_del().
 519  *
 520  * Associated @p data can be properly freed when item is deleted if a
 521  * callback function is set with elm_object_item_del_cb_set().
 522  *
 523  * If a function is passed as argument, it will be called every time this item
 524  * is selected, i.e., the user clicks over an unselected item.
 525  * If always select is enabled it will call this function every time
 526  * user clicks over an item (already selected or not).
 527  * If such function isn't needed, just passing
 528  * @c NULL as @p func is enough. The same should be done for @p data.
 529  *
 530  * @see elm_list_item_append() for a simple code example.
 531  * @see elm_list_select_mode_set()
 532  * @see elm_object_item_del()
 533  * @see elm_object_item_del_cb_set()
 534  * @see elm_list_clear()
 535  * @see elm_icon_add()
 536  *
 537  * @ingroup List
 538  */
 539 EAPI Elm_Object_Item               *elm_list_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 540
 541 /**
 542  * Insert a new item into the sorted list object.
 543  *
 544  * @param obj The list object.
 545  * @param label The label of the list item.
 546  * @param icon The icon object to use for the left side of the item. An
 547  * icon can be any Evas object, but usually it is an icon created
 548  * with elm_icon_add().
 549  * @param end The icon object to use for the right side of the item. An
 550  * icon can be any Evas object.
 551  * @param func The function to call when the item is clicked.
 552  * @param data The data to associate with the item for related callbacks.
 553  * @param cmp_func The comparing function to be used to sort list
 554  * items <b>by #Elm_Object_Item item handles</b>. This function will
 555  * receive two items and compare them, returning a non-negative integer
 556  * if the second item should be place after the first, or negative value
 557  * if should be placed before.
 558  *
 559  * @return The created item or @c NULL upon failure.
 560  *
 561  * @note This function inserts values into a list object assuming it was
 562  * sorted and the result will be sorted.
 563  *
 564  * A new item will be created and added to the list. Its position in
 565  * this list will be found comparing the new item with previously inserted
 566  * items using function @p cmp_func.
 567  *
 568  * Items created with this method can be deleted with elm_object_item_del().
 569  *
 570  * Associated @p data can be properly freed when item is deleted if a
 571  * callback function is set with elm_object_item_del_cb_set().
 572  *
 573  * If a function is passed as argument, it will be called every time this item
 574  * is selected, i.e., the user clicks over an unselected item.
 575  * If always select is enabled it will call this function every time
 576  * user clicks over an item (already selected or not).
 577  * If such function isn't needed, just passing
 578  * @c NULL as @p func is enough. The same should be done for @p data.
 579  *
 580  * @see elm_list_item_append() for a simple code example.
 581  * @see elm_list_select_mode_set()
 582  * @see elm_object_item_del()
 583  * @see elm_object_item_del_cb_set()
 584  * @see elm_list_clear()
 585  * @see elm_icon_add()
 586  *
 587  * @ingroup List
 588  */
 589 EAPI Elm_Object_Item               *elm_list_item_sorted_insert(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data, Eina_Compare_Cb cmp_func);
 590
 591 /**
 592  * Remove all list's items.
 593  *
 594  * @param obj The list object
 595  *
 596  * @see elm_object_item_del()
 597  * @see elm_list_item_append()
 598  *
 599  * @ingroup List
 600  */
 601 EAPI void                         elm_list_clear(Evas_Object *obj);
 602
 603 /**
 604  * Get a list of all the list items.
 605  *
 606  * @param obj The list object
 607  * @return An @c Eina_List of list items, #Elm_Object_Item,
 608  * or @c NULL on failure.
 609  *
 610  * @see elm_list_item_append()
 611  * @see elm_object_item_del()
 612  * @see elm_list_clear()
 613  *
 614  * @ingroup List
 615  */
 616 EAPI const Eina_List             *elm_list_items_get(const Evas_Object *obj);
 617
 618 /**
 619  * Get the selected item.
 620  *
 621  * @param obj The list object.
 622  * @return The selected list item.
 623  *
 624  * The selected item can be unselected with function
 625  * elm_list_item_selected_set().
 626  *
 627  * The selected item always will be highlighted on list.
 628  *
 629  * @see elm_list_selected_items_get()
 630  *
 631  * @ingroup List
 632  */
 633 EAPI Elm_Object_Item               *elm_list_selected_item_get(const Evas_Object *obj);
 634
 635 /**
 636  * Return a list of the currently selected list items.
 637  *
 638  * @param obj The list object.
 639  * @return An @c Eina_List of list items, #Elm_Object_Item,
 640  * or @c NULL on failure.
 641  *
 642  * Multiple items can be selected if multi select is enabled. It can be
 643  * done with elm_list_multi_select_set().
 644  *
 645  * @see elm_list_selected_item_get()
 646  * @see elm_list_multi_select_set()
 647  *
 648  * @ingroup List
 649  */
 650 EAPI const Eina_List             *elm_list_selected_items_get(const Evas_Object *obj);
 651
 652 /**
 653  * Set the selected state of an item.
 654  *
 655  * @param it The list item
 656  * @param selected The selected state
 657  *
 658  * This sets the selected state of the given item @p it.
 659  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 660  *
 661  * If a new item is selected the previously selected will be unselected,
 662  * unless multiple selection is enabled with elm_list_multi_select_set().
 663  * Previously selected item can be get with function
 664  * elm_list_selected_item_get().
 665  *
 666  * Selected items will be highlighted.
 667  *
 668  * @see elm_list_item_selected_get()
 669  * @see elm_list_selected_item_get()
 670  * @see elm_list_multi_select_set()
 671  *
 672  * @ingroup List
 673  */
 674 EAPI void                         elm_list_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 675
 676 /*
 677  * Get whether the @p item is selected or not.
 678  *
 679  * @param it The list item.
 680  * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 681  * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 682  *
 683  * @see elm_list_selected_item_set() for details.
 684  * @see elm_list_item_selected_get()
 685  *
 686  * @ingroup List
 687  */
 688 EAPI Eina_Bool                    elm_list_item_selected_get(const Elm_Object_Item *it);
 689
 690 /**
 691  * Set or unset item as a separator.
 692  *
 693  * @param it The list item.
 694  * @param setting @c EINA_TRUE to set item @p it as separator or
 695  * @c EINA_FALSE to unset, i.e., item will be used as a regular item.
 696  *
 697  * Items aren't set as separator by default.
 698  *
 699  * If set as separator it will display separator theme, so won't display
 700  * icons or label.
 701  *
 702  * @see elm_list_item_separator_get()
 703  *
 704  * @ingroup List
 705  */
 706 EAPI void                         elm_list_item_separator_set(Elm_Object_Item *it, Eina_Bool setting);
 707
 708 /**
 709  * Get a value whether item is a separator or not.
 710  *
 711  * @see elm_list_item_separator_set() for details.
 712  *
 713  * @param it The list item.
 714  * @return @c EINA_TRUE means item @p it is a separator. @c EINA_FALSE
 715  * indicates it's not. If @p it is @c NULL, @c EINA_FALSE is returned.
 716  *
 717  * @ingroup List
 718  */
 719 EAPI Eina_Bool                    elm_list_item_separator_get(const Elm_Object_Item *it);
 720
 721 /**
 722  * Show @p item in the list view.
 723  *
 724  * @param it The list item to be shown.
 725  *
 726  * It won't animate list until item is visible. If such behavior is wanted,
 727  * use elm_list_bring_in() instead.
 728  *
 729  * @ingroup List
 730  */
 731 EAPI void                         elm_list_item_show(Elm_Object_Item *it);
 732
 733 /**
 734  * Bring in the given item to list view.
 735  *
 736  * @param it The item.
 737  *
 738  * This causes list to jump to the given item @p item and show it
 739  * (by scrolling), if it is not fully visible.
 740  *
 741  * This may use animation to do so and take a period of time.
 742  *
 743  * If animation isn't wanted, elm_list_item_show() can be used.
 744  *
 745  * @ingroup List
 746  */
 747 EAPI void                         elm_list_item_bring_in(Elm_Object_Item *it);
 748
 749 /**
 750  * Gets the base object of the item.
 751  *
 752  * @param it The list item
 753  * @return The base object associated with @p item
 754  *
 755  * Base object is the @c Evas_Object that represents that item.
 756  *
 757  * @ingroup List
 758  */
 759 EAPI Evas_Object                 *elm_list_item_object_get(const Elm_Object_Item *it);
 760
 761 /**
 762  * Get the item before @p it in list.
 763  *
 764  * @param it The list item.
 765  * @return The item before @p it, or @c NULL if none or on failure.
 766  *
 767  * @note If it is the first item, @c NULL will be returned.
 768  *
 769  * @see elm_list_item_append()
 770  * @see elm_list_items_get()
 771  *
 772  * @ingroup List
 773  */
 774 EAPI Elm_Object_Item               *elm_list_item_prev(const Elm_Object_Item *it);
 775
 776 /**
 777  * Get the item after @p it in list.
 778  *
 779  * @param it The list item.
 780  * @return The item after @p it, or @c NULL if none or on failure.
 781  *
 782  * @note If it is the last item, @c NULL will be returned.
 783  *
 784  * @see elm_list_item_append()
 785  * @see elm_list_items_get()
 786  *
 787  * @ingroup List
 788  */
 789 EAPI Elm_Object_Item               *elm_list_item_next(const Elm_Object_Item *it);
 790
 791 /**
 792  * Get the first item in the list
 793  *
 794  * This returns the first item in the list.
 795  *
 796  * @param obj The list object
 797  * @return The first item, or NULL if none
 798  *
 799  * @ingroup List
 800  */
 801 EAPI Elm_Object_Item             *elm_list_first_item_get(const Evas_Object *obj);
 802
 803 /**
 804  * Get the last item in the list
 805  *
 806  * This returns the last item in the list.
 807  *
 808  * @return The last item, or NULL if none
 809  *
 810  * @ingroup List
 811  */
 812 EAPI Elm_Object_Item             *elm_list_last_item_get(const Evas_Object *obj);
 813
 814 /**
 815  * Get the item that is at the x, y canvas coords.
 816  *
 817  * @param obj The list object.
 818  * @param x The input x coordinate
 819  * @param y The input y coordinate
 820  * @param posret The position relative to the item returned here
 821  * @return The item at the coordinates or NULL if none
 822  *
 823  * This returns the item at the given coordinates (which are canvas
 824  * relative, not object-relative). If an item is at that coordinate,
 825  * that item handle is returned, and if @p posret is not NULL, the
 826  * integer pointed to is set to a value of -1, 0 or 1, depending if
 827  * the coordinate is on the upper portion of that item (-1), on the
 828  * middle section (0) or on the lower part (1). If NULL is returned as
 829  * an item (no item found there), then posret may indicate -1 or 1
 830  * based if the coordinate is above or below all items respectively in
 831  * the list.
 832  *
 833  *
 834  * @ingroup List
 835  */
 836 EAPI Elm_Object_Item             *elm_list_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret);
 837
 838 /**
 839  * @}
 840  */