src/lib/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  * List of examples:
  38  * @li @ref list_example_01
  39  * @li @ref list_example_02
  40  * @li @ref list_example_03
  41  */
  42
  43 /**
  44  * @addtogroup List
  45  * @{
  46  */
  47
  48 /**
  49  * @enum _Elm_List_Mode
  50  * @typedef Elm_List_Mode
  51  *
  52  * Set list's resize behavior, transverse axis scroll and
  53  * items cropping. See each mode's description for more details.
  54  *
  55  * @note Default value is #ELM_LIST_SCROLL.
  56  *
  57  * Values <b> don't </b> work as bitmask, only one can be choosen.
  58  *
  59  * @see elm_list_mode_set()
  60  * @see elm_list_mode_get()
  61  *
  62  * @ingroup List
  63  */
  64 typedef enum
  65 {
  66    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. */
  67    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). */
  68    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. */
  69    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. */
  70    ELM_LIST_LAST /**< Indicates error if returned by elm_list_mode_get() */
  71 } Elm_List_Mode;
  72
  73 typedef struct _Elm_List_Item Elm_List_Item;    /**< Item of Elm_List. Sub-type of Elm_Widget_Item. Can be created with elm_list_item_append(), elm_list_item_prepend() and functions to add items in relative positions, like elm_list_item_insert_before(), and deleted with elm_list_item_del().  */
  74
  75 /**
  76  * Add a new list widget to the given parent Elementary
  77  * (container) object.
  78  *
  79  * @param parent The parent object.
  80  * @return a new list widget handle or @c NULL, on errors.
  81  *
  82  * This function inserts a new list widget on the canvas.
  83  *
  84  * @ingroup List
  85  */
  86 EAPI Evas_Object                 *elm_list_add(Evas_Object *parent);
  87
  88 /**
  89  * Starts the list.
  90  *
  91  * @param obj The list object
  92  *
  93  * @note Call before running show() on the list object.
  94  * @warning If not called, it won't display the list properly.
  95  *
  96  * @code
  97  * li = elm_list_add(win);
  98  * elm_list_item_append(li, "First", NULL, NULL, NULL, NULL);
  99  * elm_list_item_append(li, "Second", NULL, NULL, NULL, NULL);
 100  * elm_list_go(li);
 101  * evas_object_show(li);
 102  * @endcode
 103  *
 104  * @ingroup List
 105  */
 106 EAPI void                         elm_list_go(Evas_Object *obj);
 107
 108 /**
 109  * Enable or disable multiple items selection on the list object.
 110  *
 111  * @param obj The list object
 112  * @param multi @c EINA_TRUE to enable multi selection or @c EINA_FALSE to
 113  * disable it.
 114  *
 115  * Disabled by default. If disabled, the user can select a single item of
 116  * the list each time. Selected items are highlighted on list.
 117  * If enabled, many items can be selected.
 118  *
 119  * If a selected item is selected again, it will be unselected.
 120  *
 121  * @see elm_list_multi_select_get()
 122  *
 123  * @ingroup List
 124  */
 125 EAPI void                         elm_list_multi_select_set(Evas_Object *obj, Eina_Bool multi);
 126
 127 /**
 128  * Get a value whether multiple items selection is enabled or not.
 129  *
 130  * @see elm_list_multi_select_set() for details.
 131  *
 132  * @param obj The list object.
 133  * @return @c EINA_TRUE means multiple items selection is enabled.
 134  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 135  * @c EINA_FALSE is returned.
 136  *
 137  * @ingroup List
 138  */
 139 EAPI Eina_Bool                    elm_list_multi_select_get(const Evas_Object *obj);
 140
 141 /**
 142  * Set which mode to use for the list object.
 143  *
 144  * @param obj The list object
 145  * @param mode One of #Elm_List_Mode: #ELM_LIST_COMPRESS, #ELM_LIST_SCROLL,
 146  * #ELM_LIST_LIMIT or #ELM_LIST_EXPAND.
 147  *
 148  * Set list's resize behavior, transverse axis scroll and
 149  * items cropping. See each mode's description for more details.
 150  *
 151  * @note Default value is #ELM_LIST_SCROLL.
 152  *
 153  * Only one can be set, if a previous one was set, it will be changed
 154  * by the new mode set. Bitmask won't work as well.
 155  *
 156  * @see elm_list_mode_get()
 157  *
 158  * @ingroup List
 159  */
 160 EAPI void                         elm_list_mode_set(Evas_Object *obj, Elm_List_Mode mode);
 161
 162 /**
 163  * Get the mode the list is at.
 164  *
 165  * @param obj The list object
 166  * @return One of #Elm_List_Mode: #ELM_LIST_COMPRESS, #ELM_LIST_SCROLL,
 167  * #ELM_LIST_LIMIT, #ELM_LIST_EXPAND or #ELM_LIST_LAST on errors.
 168  *
 169  * @note see elm_list_mode_set() for more information.
 170  *
 171  * @ingroup List
 172  */
 173 EAPI Elm_List_Mode                elm_list_mode_get(const Evas_Object *obj);
 174
 175 /**
 176  * Enable or disable horizontal mode on the list object.
 177  *
 178  * @param obj The list object.
 179  * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
 180  * disable it, i.e., to enable vertical mode.
 181  *
 182  * @note Vertical mode is set by default.
 183  *
 184  * On horizontal mode items are displayed on list from left to right,
 185  * instead of from top to bottom. Also, the list will scroll horizontally.
 186  * Each item will presents left icon on top and right icon, or end, at
 187  * the bottom.
 188  *
 189  * @see elm_list_horizontal_get()
 190  *
 191  * @ingroup List
 192  */
 193 EAPI void                         elm_list_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 194
 195 /**
 196  * Get a value whether horizontal mode is enabled or not.
 197  *
 198  * @param obj The list object.
 199  * @return @c EINA_TRUE means horizontal mode selection is enabled.
 200  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 201  * @c EINA_FALSE is returned.
 202  *
 203  * @see elm_list_horizontal_set() for details.
 204  *
 205  * @ingroup List
 206  */
 207 EAPI Eina_Bool                    elm_list_horizontal_get(const Evas_Object *obj);
 208
 209 /**
 210  * Enable or disable always select mode on the list object.
 211  *
 212  * @param obj The list object
 213  * @param always_select @c EINA_TRUE to enable always select mode or
 214  * @c EINA_FALSE to disable it.
 215  *
 216  * @note Always select mode is disabled by default.
 217  *
 218  * Default behavior of list items is to only call its callback function
 219  * the first time it's pressed, i.e., when it is selected. If a selected
 220  * item is pressed again, and multi-select is disabled, it won't call
 221  * this function (if multi-select is enabled it will unselect the item).
 222  *
 223  * If always select is enabled, it will call the callback function
 224  * everytime a item is pressed, so it will call when the item is selected,
 225  * and again when a selected item is pressed.
 226  *
 227  * @see elm_list_always_select_mode_get()
 228  * @see elm_list_multi_select_set()
 229  *
 230  * @ingroup List
 231  */
 232 EAPI void                         elm_list_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select);
 233
 234 /**
 235  * Get a value whether always select mode is enabled or not, meaning that
 236  * an item will always call its callback function, even if already selected.
 237  *
 238  * @param obj The list object
 239  * @return @c EINA_TRUE means horizontal mode selection is enabled.
 240  * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
 241  * @c EINA_FALSE is returned.
 242  *
 243  * @see elm_list_always_select_mode_set() for details.
 244  *
 245  * @ingroup List
 246  */
 247 EAPI Eina_Bool                    elm_list_always_select_mode_get(const Evas_Object *obj);
 248
 249 /**
 250  * Set bouncing behaviour when the scrolled content reaches an edge.
 251  *
 252  * Tell the internal scroller object whether it should bounce or not
 253  * when it reaches the respective edges for each axis.
 254  *
 255  * @param obj The list object
 256  * @param h_bounce Whether to bounce or not in the horizontal axis.
 257  * @param v_bounce Whether to bounce or not in the vertical axis.
 258  *
 259  * @see elm_scroller_bounce_set()
 260  *
 261  * @ingroup List
 262  */
 263 EAPI void                         elm_list_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 264
 265 /**
 266  * Get the bouncing behaviour of the internal scroller.
 267  *
 268  * Get whether the internal scroller should bounce when the edge of each
 269  * axis is reached scrolling.
 270  *
 271  * @param obj The list object.
 272  * @param h_bounce Pointer where to store the bounce state of the horizontal
 273  * axis.
 274  * @param v_bounce Pointer where to store the bounce state of the vertical
 275  * axis.
 276  *
 277  * @see elm_scroller_bounce_get()
 278  * @see elm_list_bounce_set()
 279  *
 280  * @ingroup List
 281  */
 282 EAPI void                         elm_list_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 283
 284 /**
 285  * Set the scrollbar policy.
 286  *
 287  * @param obj The list object
 288  * @param policy_h Horizontal scrollbar policy.
 289  * @param policy_v Vertical scrollbar policy.
 290  *
 291  * This sets the scrollbar visibility policy for the given scroller.
 292  * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
 293  * is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
 294  * it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
 295  * This applies respectively for the horizontal and vertical scrollbars.
 296  *
 297  * The both are disabled by default, i.e., are set to
 298  * #ELM_SCROLLER_POLICY_OFF.
 299  *
 300  * @ingroup List
 301  */
 302 EAPI void                         elm_list_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
 303
 304 /**
 305  * Get the scrollbar policy.
 306  *
 307  * @see elm_list_scroller_policy_get() for details.
 308  *
 309  * @param obj The list object.
 310  * @param policy_h Pointer where to store horizontal scrollbar policy.
 311  * @param policy_v Pointer where to store vertical scrollbar policy.
 312  *
 313  * @ingroup List
 314  */
 315 EAPI void                         elm_list_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
 316
 317 /**
 318  * Append a new item to the list object.
 319  *
 320  * @param obj The list object.
 321  * @param label The label of the list item.
 322  * @param icon The icon object to use for the left side of the item. An
 323  * icon can be any Evas object, but usually it is an icon created
 324  * with elm_icon_add().
 325  * @param end The icon object to use for the right side of the item. An
 326  * icon can be any Evas object.
 327  * @param func The function to call when the item is clicked.
 328  * @param data The data to associate with the item for related callbacks.
 329  *
 330  * @return The created item or @c NULL upon failure.
 331  *
 332  * A new item will be created and appended to the list, i.e., will
 333  * be set as @b last item.
 334  *
 335  * Items created with this method can be deleted with
 336  * elm_list_item_del().
 337  *
 338  * Associated @p data can be properly freed when item is deleted if a
 339  * callback function is set with elm_widget_item_del_cb_set().
 340  *
 341  * If a function is passed as argument, it will be called everytime this item
 342  * is selected, i.e., the user clicks over an unselected item.
 343  * If always select is enabled it will call this function every time
 344  * user clicks over an item (already selected or not).
 345  * If such function isn't needed, just passing
 346  * @c NULL as @p func is enough. The same should be done for @p data.
 347  *
 348  * Simple example (with no function callback or data associated):
 349  * @code
 350  * li = elm_list_add(win);
 351  * ic = elm_icon_add(win);
 352  * elm_icon_file_set(ic, "path/to/image", NULL);
 353  * elm_icon_scale_set(ic, EINA_TRUE, EINA_TRUE);
 354  * elm_list_item_append(li, "label", ic, NULL, NULL, NULL);
 355  * elm_list_go(li);
 356  * evas_object_show(li);
 357  * @endcode
 358  *
 359  * @see elm_list_always_select_mode_set()
 360  * @see elm_list_item_del()
 361  * @see elm_widget_item_del_cb_set()
 362  * @see elm_list_clear()
 363  * @see elm_icon_add()
 364  *
 365  * @ingroup List
 366  */
 367 EAPI Elm_List_Item               *elm_list_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 368
 369 /**
 370  * Prepend a new item to the list object.
 371  *
 372  * @param obj The list object.
 373  * @param label The label of the list item.
 374  * @param icon The icon object to use for the left side of the item. An
 375  * icon can be any Evas object, but usually it is an icon created
 376  * with elm_icon_add().
 377  * @param end The icon object to use for the right side of the item. An
 378  * icon can be any Evas object.
 379  * @param func The function to call when the item is clicked.
 380  * @param data The data to associate with the item for related callbacks.
 381  *
 382  * @return The created item or @c NULL upon failure.
 383  *
 384  * A new item will be created and prepended to the list, i.e., will
 385  * be set as @b first item.
 386  *
 387  * Items created with this method can be deleted with
 388  * elm_list_item_del().
 389  *
 390  * Associated @p data can be properly freed when item is deleted if a
 391  * callback function is set with elm_widget_item_del_cb_set().
 392  *
 393  * If a function is passed as argument, it will be called everytime this item
 394  * is selected, i.e., the user clicks over an unselected item.
 395  * If always select is enabled it will call this function every time
 396  * user clicks over an item (already selected or not).
 397  * If such function isn't needed, just passing
 398  * @c NULL as @p func is enough. The same should be done for @p data.
 399  *
 400  * @see elm_list_item_append() for a simple code example.
 401  * @see elm_list_always_select_mode_set()
 402  * @see elm_list_item_del()
 403  * @see elm_widget_item_del_cb_set()
 404  * @see elm_list_clear()
 405  * @see elm_icon_add()
 406  *
 407  * @ingroup List
 408  */
 409 EAPI Elm_List_Item               *elm_list_item_prepend(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 410
 411 /**
 412  * Insert a new item into the list object before item @p before.
 413  *
 414  * @param obj The list object.
 415  * @param before The list item to insert before.
 416  * @param label The label of the list item.
 417  * @param icon The icon object to use for the left side of the item. An
 418  * icon can be any Evas object, but usually it is an icon created
 419  * with elm_icon_add().
 420  * @param end The icon object to use for the right side of the item. An
 421  * icon can be any Evas object.
 422  * @param func The function to call when the item is clicked.
 423  * @param data The data to associate with the item for related callbacks.
 424  *
 425  * @return The created item or @c NULL upon failure.
 426  *
 427  * A new item will be created and added to the list. Its position in
 428  * this list will be just before item @p before.
 429  *
 430  * Items created with this method can be deleted with
 431  * elm_list_item_del().
 432  *
 433  * Associated @p data can be properly freed when item is deleted if a
 434  * callback function is set with elm_widget_item_del_cb_set().
 435  *
 436  * If a function is passed as argument, it will be called everytime this item
 437  * is selected, i.e., the user clicks over an unselected item.
 438  * If always select is enabled it will call this function every time
 439  * user clicks over an item (already selected or not).
 440  * If such function isn't needed, just passing
 441  * @c NULL as @p func is enough. The same should be done for @p data.
 442  *
 443  * @see elm_list_item_append() for a simple code example.
 444  * @see elm_list_always_select_mode_set()
 445  * @see elm_list_item_del()
 446  * @see elm_widget_item_del_cb_set()
 447  * @see elm_list_clear()
 448  * @see elm_icon_add()
 449  *
 450  * @ingroup List
 451  */
 452 EAPI Elm_List_Item               *elm_list_item_insert_before(Evas_Object *obj, Elm_List_Item *before, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 453
 454 /**
 455  * Insert a new item into the list object after item @p after.
 456  *
 457  * @param obj The list object.
 458  * @param after The list item to insert after.
 459  * @param label The label of the list item.
 460  * @param icon The icon object to use for the left side of the item. An
 461  * icon can be any Evas object, but usually it is an icon created
 462  * with elm_icon_add().
 463  * @param end The icon object to use for the right side of the item. An
 464  * icon can be any Evas object.
 465  * @param func The function to call when the item is clicked.
 466  * @param data The data to associate with the item for related callbacks.
 467  *
 468  * @return The created item or @c NULL upon failure.
 469  *
 470  * A new item will be created and added to the list. Its position in
 471  * this list will be just after item @p after.
 472  *
 473  * Items created with this method can be deleted with
 474  * elm_list_item_del().
 475  *
 476  * Associated @p data can be properly freed when item is deleted if a
 477  * callback function is set with elm_widget_item_del_cb_set().
 478  *
 479  * If a function is passed as argument, it will be called everytime this item
 480  * is selected, i.e., the user clicks over an unselected item.
 481  * If always select is enabled it will call this function every time
 482  * user clicks over an item (already selected or not).
 483  * If such function isn't needed, just passing
 484  * @c NULL as @p func is enough. The same should be done for @p data.
 485  *
 486  * @see elm_list_item_append() for a simple code example.
 487  * @see elm_list_always_select_mode_set()
 488  * @see elm_list_item_del()
 489  * @see elm_widget_item_del_cb_set()
 490  * @see elm_list_clear()
 491  * @see elm_icon_add()
 492  *
 493  * @ingroup List
 494  */
 495 EAPI Elm_List_Item               *elm_list_item_insert_after(Evas_Object *obj, Elm_List_Item *after, const char *label, Evas_Object *icon, Evas_Object *end, Evas_Smart_Cb func, const void *data);
 496
 497 /**
 498  * Insert a new item into the sorted list object.
 499  *
 500  * @param obj The list object.
 501  * @param label The label of the list item.
 502  * @param icon The icon object to use for the left side of the item. An
 503  * icon can be any Evas object, but usually it is an icon created
 504  * with elm_icon_add().
 505  * @param end The icon object to use for the right side of the item. An
 506  * icon can be any Evas object.
 507  * @param func The function to call when the item is clicked.
 508  * @param data The data to associate with the item for related callbacks.
 509  * @param cmp_func The comparing function to be used to sort list
 510  * items <b>by #Elm_List_Item item handles</b>. This function will
 511  * receive two items and compare them, returning a non-negative integer
 512  * if the second item should be place after the first, or negative value
 513  * if should be placed before.
 514  *
 515  * @return The created item or @c NULL upon failure.
 516  *
 517  * @note This function inserts values into a list object assuming it was
 518  * sorted and the result will be sorted.
 519  *
 520  * A new item will be created and added to the list. Its position in
 521  * this list will be found comparing the new item with previously inserted
 522  * items using function @p cmp_func.
 523  *
 524  * Items created with this method can be deleted with
 525  * elm_list_item_del().
 526  *
 527  * Associated @p data can be properly freed when item is deleted if a
 528  * callback function is set with elm_widget_item_del_cb_set().
 529  *
 530  * If a function is passed as argument, it will be called everytime this item
 531  * is selected, i.e., the user clicks over an unselected item.
 532  * If always select is enabled it will call this function every time
 533  * user clicks over an item (already selected or not).
 534  * If such function isn't needed, just passing
 535  * @c NULL as @p func is enough. The same should be done for @p data.
 536  *
 537  * @see elm_list_item_append() for a simple code example.
 538  * @see elm_list_always_select_mode_set()
 539  * @see elm_list_item_del()
 540  * @see elm_widget_item_del_cb_set()
 541  * @see elm_list_clear()
 542  * @see elm_icon_add()
 543  *
 544  * @ingroup List
 545  */
 546 EAPI Elm_List_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);
 547
 548 /**
 549  * Remove all list's items.
 550  *
 551  * @param obj The list object
 552  *
 553  * @see elm_list_item_del()
 554  * @see elm_list_item_append()
 555  *
 556  * @ingroup List
 557  */
 558 EAPI void                         elm_list_clear(Evas_Object *obj);
 559
 560 /**
 561  * Get a list of all the list items.
 562  *
 563  * @param obj The list object
 564  * @return An @c Eina_List of list items, #Elm_List_Item,
 565  * or @c NULL on failure.
 566  *
 567  * @see elm_list_item_append()
 568  * @see elm_list_item_del()
 569  * @see elm_list_clear()
 570  *
 571  * @ingroup List
 572  */
 573 EAPI const Eina_List             *elm_list_items_get(const Evas_Object *obj);
 574
 575 /**
 576  * Get the selected item.
 577  *
 578  * @param obj The list object.
 579  * @return The selected list item.
 580  *
 581  * The selected item can be unselected with function
 582  * elm_list_item_selected_set().
 583  *
 584  * The selected item always will be highlighted on list.
 585  *
 586  * @see elm_list_selected_items_get()
 587  *
 588  * @ingroup List
 589  */
 590 EAPI Elm_List_Item               *elm_list_selected_item_get(const Evas_Object *obj);
 591
 592 /**
 593  * Return a list of the currently selected list items.
 594  *
 595  * @param obj The list object.
 596  * @return An @c Eina_List of list items, #Elm_List_Item,
 597  * or @c NULL on failure.
 598  *
 599  * Multiple items can be selected if multi select is enabled. It can be
 600  * done with elm_list_multi_select_set().
 601  *
 602  * @see elm_list_selected_item_get()
 603  * @see elm_list_multi_select_set()
 604  *
 605  * @ingroup List
 606  */
 607 EAPI const Eina_List             *elm_list_selected_items_get(const Evas_Object *obj);
 608
 609 /**
 610  * Set the selected state of an item.
 611  *
 612  * @param item The list item
 613  * @param selected The selected state
 614  *
 615  * This sets the selected state of the given item @p it.
 616  * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
 617  *
 618  * If a new item is selected the previosly selected will be unselected,
 619  * unless multiple selection is enabled with elm_list_multi_select_set().
 620  * Previoulsy selected item can be get with function
 621  * elm_list_selected_item_get().
 622  *
 623  * Selected items will be highlighted.
 624  *
 625  * @see elm_list_item_selected_get()
 626  * @see elm_list_selected_item_get()
 627  * @see elm_list_multi_select_set()
 628  *
 629  * @ingroup List
 630  */
 631 EAPI void                         elm_list_item_selected_set(Elm_List_Item *item, Eina_Bool selected);
 632
 633 /*
 634  * Get whether the @p item is selected or not.
 635  *
 636  * @param item The list item.
 637  * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
 638  * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 639  *
 640  * @see elm_list_selected_item_set() for details.
 641  * @see elm_list_item_selected_get()
 642  *
 643  * @ingroup List
 644  */
 645 EAPI Eina_Bool                    elm_list_item_selected_get(const Elm_List_Item *item);
 646
 647 /**
 648  * Set or unset item as a separator.
 649  *
 650  * @param it The list item.
 651  * @param setting @c EINA_TRUE to set item @p it as separator or
 652  * @c EINA_FALSE to unset, i.e., item will be used as a regular item.
 653  *
 654  * Items aren't set as separator by default.
 655  *
 656  * If set as separator it will display separator theme, so won't display
 657  * icons or label.
 658  *
 659  * @see elm_list_item_separator_get()
 660  *
 661  * @ingroup List
 662  */
 663 EAPI void                         elm_list_item_separator_set(Elm_List_Item *it, Eina_Bool setting);
 664
 665 /**
 666  * Get a value whether item is a separator or not.
 667  *
 668  * @see elm_list_item_separator_set() for details.
 669  *
 670  * @param it The list item.
 671  * @return @c EINA_TRUE means item @p it is a separator. @c EINA_FALSE
 672  * indicates it's not. If @p it is @c NULL, @c EINA_FALSE is returned.
 673  *
 674  * @ingroup List
 675  */
 676 EAPI Eina_Bool                    elm_list_item_separator_get(const Elm_List_Item *it);
 677
 678 /**
 679  * Show @p item in the list view.
 680  *
 681  * @param item The list item to be shown.
 682  *
 683  * It won't animate list until item is visible. If such behavior is wanted,
 684  * use elm_list_bring_in() intead.
 685  *
 686  * @ingroup List
 687  */
 688 EAPI void                         elm_list_item_show(Elm_List_Item *item);
 689
 690 /**
 691  * Bring in the given item to list view.
 692  *
 693  * @param item The item.
 694  *
 695  * This causes list to jump to the given item @p item and show it
 696  * (by scrolling), if it is not fully visible.
 697  *
 698  * This may use animation to do so and take a period of time.
 699  *
 700  * If animation isn't wanted, elm_list_item_show() can be used.
 701  *
 702  * @ingroup List
 703  */
 704 EAPI void                         elm_list_item_bring_in(Elm_List_Item *item);
 705
 706 /**
 707  * Delete them item from the list.
 708  *
 709  * @param item The item of list to be deleted.
 710  *
 711  * If deleting all list items is required, elm_list_clear()
 712  * should be used instead of getting items list and deleting each one.
 713  *
 714  * @see elm_list_clear()
 715  * @see elm_list_item_append()
 716  * @see elm_widget_item_del_cb_set()
 717  *
 718  * @ingroup List
 719  */
 720 EAPI void                         elm_list_item_del(Elm_List_Item *item);
 721
 722 /**
 723  * Gets the base object of the item.
 724  *
 725  * @param item The list item
 726  * @return The base object associated with @p item
 727  *
 728  * Base object is the @c Evas_Object that represents that item.
 729  *
 730  * @ingroup List
 731  */
 732 EAPI Evas_Object                 *elm_list_item_object_get(const Elm_List_Item *item);
 733
 734 /**
 735  * Get the item before @p it in list.
 736  *
 737  * @param it The list item.
 738  * @return The item before @p it, or @c NULL if none or on failure.
 739  *
 740  * @note If it is the first item, @c NULL will be returned.
 741  *
 742  * @see elm_list_item_append()
 743  * @see elm_list_items_get()
 744  *
 745  * @ingroup List
 746  */
 747 EAPI Elm_List_Item               *elm_list_item_prev(const Elm_List_Item *it);
 748
 749 /**
 750  * Get the item after @p it in list.
 751  *
 752  * @param it The list item.
 753  * @return The item after @p it, or @c NULL if none or on failure.
 754  *
 755  * @note If it is the last item, @c NULL will be returned.
 756  *
 757  * @see elm_list_item_append()
 758  * @see elm_list_items_get()
 759  *
 760  * @ingroup List
 761  */
 762 EAPI Elm_List_Item               *elm_list_item_next(const Elm_List_Item *it);
 763
 764 /**
 765  * Set the text to be shown in a given list item's tooltips.
 766  *
 767  * @param item Target item.
 768  * @param text The text to set in the content.
 769  *
 770  * Setup the text as tooltip to object. The item can have only one tooltip,
 771  * so any previous tooltip data - set with this function or
 772  * elm_list_item_tooltip_content_cb_set() - is removed.
 773  *
 774  * @see elm_object_tooltip_text_set() for more details.
 775  *
 776  * @ingroup List
 777  */
 778 EAPI void                         elm_list_item_tooltip_text_set(Elm_List_Item *item, const char *text);
 779
 780 /**
 781  * @brief Disable size restrictions on an object's tooltip
 782  * @param item The tooltip's anchor object
 783  * @param disable If EINA_TRUE, size restrictions are disabled
 784  * @return EINA_FALSE on failure, EINA_TRUE on success
 785  *
 786  * This function allows a tooltip to expand beyond its parant window's canvas.
 787  * It will instead be limited only by the size of the display.
 788  */
 789 EAPI Eina_Bool                    elm_list_item_tooltip_window_mode_set(Elm_List_Item *item, Eina_Bool disable);
 790
 791 /**
 792  * @brief Retrieve size restriction state of an object's tooltip
 793  * @param obj The tooltip's anchor object
 794  * @return If EINA_TRUE, size restrictions are disabled
 795  *
 796  * This function returns whether a tooltip is allowed to expand beyond
 797  * its parant window's canvas.
 798  * It will instead be limited only by the size of the display.
 799  */
 800 EAPI Eina_Bool                    elm_list_item_tooltip_window_mode_get(const Elm_List_Item *item);
 801
 802 /**
 803  * Set the content to be shown in the tooltip item.
 804  *
 805  * Setup the tooltip to item. The item can have only one tooltip,
 806  * so any previous tooltip data is removed. @p func(with @p data) will
 807  * be called every time that need show the tooltip and it should
 808  * return a valid Evas_Object. This object is then managed fully by
 809  * tooltip system and is deleted when the tooltip is gone.
 810  *
 811  * @param item the list item being attached a tooltip.
 812  * @param func the function used to create the tooltip contents.
 813  * @param data what to provide to @a func as callback data/context.
 814  * @param del_cb called when data is not needed anymore, either when
 815  *        another callback replaces @a func, the tooltip is unset with
 816  *        elm_list_item_tooltip_unset() or the owner @a item
 817  *        dies. This callback receives as the first parameter the
 818  *        given @a data, and @c event_info is the item.
 819  *
 820  * @see elm_object_tooltip_content_cb_set() for more details.
 821  *
 822  * @ingroup List
 823  */
 824 EAPI void                         elm_list_item_tooltip_content_cb_set(Elm_List_Item *item, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
 825
 826 /**
 827  * Unset tooltip from item.
 828  *
 829  * @param item list item to remove previously set tooltip.
 830  *
 831  * Remove tooltip from item. The callback provided as del_cb to
 832  * elm_list_item_tooltip_content_cb_set() will be called to notify
 833  * it is not used anymore.
 834  *
 835  * @see elm_object_tooltip_unset() for more details.
 836  * @see elm_list_item_tooltip_content_cb_set()
 837  *
 838  * @ingroup List
 839  */
 840 EAPI void                         elm_list_item_tooltip_unset(Elm_List_Item *item);
 841
 842 /**
 843  * Sets a different style for this item tooltip.
 844  *
 845  * @note before you set a style you should define a tooltip with
 846  *       elm_list_item_tooltip_content_cb_set() or
 847  *       elm_list_item_tooltip_text_set()
 848  *
 849  * @param item list item with tooltip already set.
 850  * @param style the theme style to use (default, transparent, ...)
 851  *
 852  * @see elm_object_tooltip_style_set() for more details.
 853  *
 854  * @ingroup List
 855  */
 856 EAPI void                         elm_list_item_tooltip_style_set(Elm_List_Item *item, const char *style);
 857
 858 /**
 859  * Get the style for this item tooltip.
 860  *
 861  * @param item list item with tooltip already set.
 862  * @return style the theme style in use, defaults to "default". If the
 863  *         object does not have a tooltip set, then NULL is returned.
 864  *
 865  * @see elm_object_tooltip_style_get() for more details.
 866  * @see elm_list_item_tooltip_style_set()
 867  *
 868  * @ingroup List
 869  */
 870 EAPI const char                  *elm_list_item_tooltip_style_get(const Elm_List_Item *item);
 871
 872 /**
 873  * Set the type of mouse pointer/cursor decoration to be shown,
 874  * when the mouse pointer is over the given list widget item
 875  *
 876  * @param item list item to customize cursor on
 877  * @param cursor the cursor type's name
 878  *
 879  * This function works analogously as elm_object_cursor_set(), but
 880  * here the cursor's changing area is restricted to the item's
 881  * area, and not the whole widget's. Note that that item cursors
 882  * have precedence over widget cursors, so that a mouse over an
 883  * item with custom cursor set will always show @b that cursor.
 884  *
 885  * If this function is called twice for an object, a previously set
 886  * cursor will be unset on the second call.
 887  *
 888  * @see elm_object_cursor_set()
 889  * @see elm_list_item_cursor_get()
 890  * @see elm_list_item_cursor_unset()
 891  *
 892  * @ingroup List
 893  */
 894 EAPI void                         elm_list_item_cursor_set(Elm_List_Item *item, const char *cursor);
 895
 896 /*
 897  * Get the type of mouse pointer/cursor decoration set to be shown,
 898  * when the mouse pointer is over the given list widget item
 899  *
 900  * @param item list item with custom cursor set
 901  * @return the cursor type's name or @c NULL, if no custom cursors
 902  * were set to @p item (and on errors)
 903  *
 904  * @see elm_object_cursor_get()
 905  * @see elm_list_item_cursor_set()
 906  * @see elm_list_item_cursor_unset()
 907  *
 908  * @ingroup List
 909  */
 910 EAPI const char                  *elm_list_item_cursor_get(const Elm_List_Item *item);
 911
 912 /**
 913  * Unset any custom mouse pointer/cursor decoration set to be
 914  * shown, when the mouse pointer is over the given list widget
 915  * item, thus making it show the @b default cursor again.
 916  *
 917  * @param item a list item
 918  *
 919  * Use this call to undo any custom settings on this item's cursor
 920  * decoration, bringing it back to defaults (no custom style set).
 921  *
 922  * @see elm_object_cursor_unset()
 923  * @see elm_list_item_cursor_set()
 924  *
 925  * @ingroup List
 926  */
 927 EAPI void                         elm_list_item_cursor_unset(Elm_List_Item *item);
 928
 929 /**
 930  * Set a different @b style for a given custom cursor set for a
 931  * list item.
 932  *
 933  * @param item list item with custom cursor set
 934  * @param style the <b>theme style</b> to use (e.g. @c "default",
 935  * @c "transparent", etc)
 936  *
 937  * This function only makes sense when one is using custom mouse
 938  * cursor decorations <b>defined in a theme file</b>, which can have,
 939  * given a cursor name/type, <b>alternate styles</b> on it. It
 940  * works analogously as elm_object_cursor_style_set(), but here
 941  * applyed only to list item objects.
 942  *
 943  * @warning Before you set a cursor style you should have definen a
 944  *       custom cursor previously on the item, with
 945  *       elm_list_item_cursor_set()
 946  *
 947  * @see elm_list_item_cursor_engine_only_set()
 948  * @see elm_list_item_cursor_style_get()
 949  *
 950  * @ingroup List
 951  */
 952 EAPI void                         elm_list_item_cursor_style_set(Elm_List_Item *item, const char *style);
 953
 954 /**
 955  * Get the current @b style set for a given list item's custom
 956  * cursor
 957  *
 958  * @param item list item with custom cursor set.
 959  * @return style the cursor style in use. If the object does not
 960  *         have a cursor set, then @c NULL is returned.
 961  *
 962  * @see elm_list_item_cursor_style_set() for more details
 963  *
 964  * @ingroup List
 965  */
 966 EAPI const char                  *elm_list_item_cursor_style_get(const Elm_List_Item *item);
 967
 968 /**
 969  * Set if the (custom)cursor for a given list item should be
 970  * searched in its theme, also, or should only rely on the
 971  * rendering engine.
 972  *
 973  * @param item item with custom (custom) cursor already set on
 974  * @param engine_only Use @c EINA_TRUE to have cursors looked for
 975  * only on those provided by the rendering engine, @c EINA_FALSE to
 976  * have them searched on the widget's theme, as well.
 977  *
 978  * @note This call is of use only if you've set a custom cursor
 979  * for list items, with elm_list_item_cursor_set().
 980  *
 981  * @note By default, cursors will only be looked for between those
 982  * provided by the rendering engine.
 983  *
 984  * @ingroup List
 985  */
 986 EAPI void                         elm_list_item_cursor_engine_only_set(Elm_List_Item *item, Eina_Bool engine_only);
 987
 988 /**
 989  * Get if the (custom) cursor for a given list item is being
 990  * searched in its theme, also, or is only relying on the rendering
 991  * engine.
 992  *
 993  * @param item a list item
 994  * @return @c EINA_TRUE, if cursors are being looked for only on
 995  * those provided by the rendering engine, @c EINA_FALSE if they
 996  * are being searched on the widget's theme, as well.
 997  *
 998  * @see elm_list_item_cursor_engine_only_set(), for more details
 999  *
1000  * @ingroup List
1001  */
1002 EAPI Eina_Bool                    elm_list_item_cursor_engine_only_get(const Elm_List_Item *item);
1003
1004 /**
1005  * @}
1006  */