tests/debian/tmp/usr/include/elementary-0/elm_list.h

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