src/lib/elm_genlist.h

   1 /**
   2  * @defgroup Genlist Genlist
   3  *
   4  * @image html img/widget/genlist/preview-00.png
   5  * @image latex img/widget/genlist/preview-00.eps
   6  * @image html img/genlist.png
   7  * @image latex img/genlist.eps
   8  *
   9  * This widget aims to have more expansive list than the simple list in
  10  * Elementary that could have more flexible items and allow many more entries
  11  * while still being fast and low on memory usage. At the same time it was
  12  * also made to be able to do tree structures. But the price to pay is more
  13  * complexity when it comes to usage. If all you want is a simple list with
  14  * icons and a single text, use the normal @ref List object.
  15  *
  16  * Genlist has a fairly large API, mostly because it's relatively complex,
  17  * trying to be both expansive, powerful and efficient. First we will begin
  18  * an overview on the theory behind genlist.
  19  *
  20  * @section Genlist_Item_Class Genlist item classes - creating items
  21  *
  22  * In order to have the ability to add and delete items on the fly, genlist
  23  * implements a class (callback) system where the application provides a
  24  * structure with information about that type of item (genlist may contain
  25  * multiple different items with different classes, states and styles).
  26  * Genlist will call the functions in this struct (methods) when an item is
  27  * "realized" (i.e., created dynamically, while the user is scrolling the
  28  * grid). All objects will simply be deleted when no longer needed with
  29  * evas_object_del(). The #Elm_Genlist_Item_Class structure contains the
  30  * following members:
  31  * - @c item_style - This is a constant string and simply defines the name
  32  *   of the item style. It @b must be specified and the default should be @c
  33  *   "default".
  34  *
  35  * - @c func - A struct with pointers to functions that will be called when
  36  *   an item is going to be actually created. All of them receive a @c data
  37  *   parameter that will point to the same data passed to
  38  *   elm_genlist_item_append() and related item creation functions, and a @c
  39  *   obj parameter that points to the genlist object itself.
  40  *
  41  * The function pointers inside @c func are @c text_get, @c content_get, @c
  42  * state_get and @c del. The 3 first functions also receive a @c part
  43  * parameter described below. A brief description of these functions follows:
  44  *
  45  * - @c text_get - The @c part parameter is the name string of one of the
  46  *   existing text parts in the Edje group implementing the item's theme.
  47  *   This function @b must return a strdup'()ed string, as the caller will
  48  *   free() it when done. See #Elm_Genlist_Item_Text_Get_Cb.
  49  * - @c content_get - The @c part parameter is the name string of one of the
  50  *   existing (content) swallow parts in the Edje group implementing the item's
  51  *   theme. It must return @c NULL, when no content is desired, or a valid
  52  *   object handle, otherwise.  The object will be deleted by the genlist on
  53  *   its deletion or when the item is "unrealized".  See
  54  *   #Elm_Genlist_Item_Content_Get_Cb.
  55  * - @c func.state_get - The @c part parameter is the name string of one of
  56  *   the state parts in the Edje group implementing the item's theme. Return
  57  *   @c EINA_FALSE for false/off or @c EINA_TRUE for true/on. Genlists will
  58  *   emit a signal to its theming Edje object with @c "elm,state,XXX,active"
  59  *   and @c "elm" as "emission" and "source" arguments, respectively, when
  60  *   the state is true (the default is false), where @c XXX is the name of
  61  *   the (state) part.  See #Elm_Genlist_Item_State_Get_Cb.
  62  * - @c func.del - This is intended for use when genlist items are deleted,
  63  *   so any data attached to the item (e.g. its data parameter on creation)
  64  *   can be deleted. See #Elm_Genlist_Item_Del_Cb.
  65  *
  66  * available item styles:
  67  * - default
  68  * - default_style - The text part is a textblock
  69  *
  70  * @image html img/widget/genlist/preview-04.png
  71  * @image latex img/widget/genlist/preview-04.eps
  72  *
  73  * - double_label
  74  *
  75  * @image html img/widget/genlist/preview-01.png
  76  * @image latex img/widget/genlist/preview-01.eps
  77  *
  78  * - icon_top_text_bottom
  79  *
  80  * @image html img/widget/genlist/preview-02.png
  81  * @image latex img/widget/genlist/preview-02.eps
  82  *
  83  * - group_index
  84  *
  85  * @image html img/widget/genlist/preview-03.png
  86  * @image latex img/widget/genlist/preview-03.eps
  87  *
  88  * @section Genlist_Items Structure of items
  89  *
  90  * An item in a genlist can have 0 or more texts (they can be regular
  91  * text or textblock Evas objects - that's up to the style to determine), 0
  92  * or more contents (which are simply objects swallowed into the genlist item's
  93  * theming Edje object) and 0 or more <b>boolean states</b>, which have the
  94  * behavior left to the user to define. The Edje part names for each of
  95  * these properties will be looked up, in the theme file for the genlist,
  96  * under the Edje (string) data items named @c "labels", @c "contents" and @c
  97  * "states", respectively. For each of those properties, if more than one
  98  * part is provided, they must have names listed separated by spaces in the
  99  * data fields. For the default genlist item theme, we have @b one text
 100  * part (@c "elm.text"), @b two content parts (@c "elm.swalllow.icon" and @c
 101  * "elm.swallow.end") and @b no state parts.
 102  *
 103  * A genlist item may be at one of several styles. Elementary provides one
 104  * by default - "default", but this can be extended by system or application
 105  * custom themes/overlays/extensions (see @ref Theme "themes" for more
 106  * details).
 107  *
 108  * @section Genlist_Manipulation Editing and Navigating
 109  *
 110  * Items can be added by several calls. All of them return a @ref
 111  * Elm_Genlist_Item handle that is an internal member inside the genlist.
 112  * They all take a data parameter that is meant to be used for a handle to
 113  * the applications internal data (eg the struct with the original item
 114  * data). The parent parameter is the parent genlist item this belongs to if
 115  * it is a tree or an indexed group, and NULL if there is no parent. The
 116  * flags can be a bitmask of #ELM_GENLIST_ITEM_NONE,
 117  * #ELM_GENLIST_ITEM_SUBITEMS and #ELM_GENLIST_ITEM_GROUP. If
 118  * #ELM_GENLIST_ITEM_SUBITEMS is set then this item is displayed as an item
 119  * that is able to expand and have child items.  If ELM_GENLIST_ITEM_GROUP
 120  * is set then this item is group index item that is displayed at the top
 121  * until the next group comes. The func parameter is a convenience callback
 122  * that is called when the item is selected and the data parameter will be
 123  * the func_data parameter, obj be the genlist object and event_info will be
 124  * the genlist item.
 125  *
 126  * elm_genlist_item_append() adds an item to the end of the list, or if
 127  * there is a parent, to the end of all the child items of the parent.
 128  * elm_genlist_item_prepend() is the same but adds to the beginning of
 129  * the list or children list. elm_genlist_item_insert_before() inserts at
 130  * item before another item and elm_genlist_item_insert_after() inserts after
 131  * the indicated item.
 132  *
 133  * The application can clear the list with elm_genlist_clear() which deletes
 134  * all the items in the list and elm_genlist_item_del() will delete a specific
 135  * item. elm_genlist_item_subitems_clear() will clear all items that are
 136  * children of the indicated parent item.
 137  *
 138  * To help inspect list items you can jump to the item at the top of the list
 139  * with elm_genlist_first_item_get() which will return the item pointer, and
 140  * similarly elm_genlist_last_item_get() gets the item at the end of the list.
 141  * elm_genlist_item_next_get() and elm_genlist_item_prev_get() get the next
 142  * and previous items respectively relative to the indicated item. Using
 143  * these calls you can walk the entire item list/tree. Note that as a tree
 144  * the items are flattened in the list, so elm_genlist_item_parent_get() will
 145  * let you know which item is the parent (and thus know how to skip them if
 146  * wanted).
 147  *
 148  * @section Genlist_Muti_Selection Multi-selection
 149  *
 150  * If the application wants multiple items to be able to be selected,
 151  * elm_genlist_multi_select_set() can enable this. If the list is
 152  * single-selection only (the default), then elm_genlist_selected_item_get()
 153  * will return the selected item, if any, or NULL if none is selected. If the
 154  * list is multi-select then elm_genlist_selected_items_get() will return a
 155  * list (that is only valid as long as no items are modified (added, deleted,
 156  * selected or unselected)).
 157  *
 158  * @section Genlist_Usage_Hints Usage hints
 159  *
 160  * There are also convenience functions. elm_genlist_item_genlist_get() will
 161  * return the genlist object the item belongs to. elm_genlist_item_show()
 162  * will make the scroller scroll to show that specific item so its visible.
 163  * elm_genlist_item_data_get() returns the data pointer set by the item
 164  * creation functions.
 165  *
 166  * If an item changes (state of boolean changes, text or contents change),
 167  * then use elm_genlist_item_update() to have genlist update the item with
 168  * the new state. Genlist will re-realize the item thus call the functions
 169  * in the _Elm_Genlist_Item_Class for that item.
 170  *
 171  * To programmatically (un)select an item use elm_genlist_item_selected_set().
 172  * To get its selected state use elm_genlist_item_selected_get(). Similarly
 173  * to expand/contract an item and get its expanded state, use
 174  * elm_genlist_item_expanded_set() and elm_genlist_item_expanded_get(). And
 175  * again to make an item disabled (unable to be selected and appear
 176  * differently) use elm_genlist_item_disabled_set() to set this and
 177  * elm_genlist_item_disabled_get() to get the disabled state.
 178  *
 179  * In general to indicate how the genlist should expand items horizontally to
 180  * fill the list area, use elm_genlist_horizontal_set(). Valid modes are
 181  * ELM_LIST_LIMIT and ELM_LIST_SCROLL. The default is ELM_LIST_SCROLL. This
 182  * mode means that if items are too wide to fit, the scroller will scroll
 183  * horizontally. Otherwise items are expanded to fill the width of the
 184  * viewport of the scroller. If it is ELM_LIST_LIMIT, items will be expanded
 185  * to the viewport width and limited to that size. This can be combined with
 186  * a different style that uses edjes' ellipsis feature (cutting text off like
 187  * this: "tex...").
 188  *
 189  * Items will only call their selection func and callback when first becoming
 190  * selected. Any further clicks will do nothing, unless you enable always
 191  * select with elm_genlist_always_select_mode_set(). This means even if
 192  * selected, every click will make the selected callbacks be called.
 193  * elm_genlist_no_select_mode_set() will turn off the ability to select
 194  * items entirely and they will neither appear selected nor call selected
 195  * callback functions.
 196  *
 197  * Remember that you can create new styles and add your own theme augmentation
 198  * per application with elm_theme_extension_add(). If you absolutely must
 199  * have a specific style that overrides any theme the user or system sets up
 200  * you can use elm_theme_overlay_add() to add such a file.
 201  *
 202  * @section Genlist_Implementation Implementation
 203  *
 204  * Evas tracks every object you create. Every time it processes an event
 205  * (mouse move, down, up etc.) it needs to walk through objects and find out
 206  * what event that affects. Even worse every time it renders display updates,
 207  * in order to just calculate what to re-draw, it needs to walk through many
 208  * many many objects. Thus, the more objects you keep active, the more
 209  * overhead Evas has in just doing its work. It is advisable to keep your
 210  * active objects to the minimum working set you need. Also remember that
 211  * object creation and deletion carries an overhead, so there is a
 212  * middle-ground, which is not easily determined. But don't keep massive lists
 213  * of objects you can't see or use. Genlist does this with list objects. It
 214  * creates and destroys them dynamically as you scroll around. It groups them
 215  * into blocks so it can determine the visibility etc. of a whole block at
 216  * once as opposed to having to walk the whole list. This 2-level list allows
 217  * for very large numbers of items to be in the list (tests have used up to
 218  * 2,000,000 items). Also genlist employs a queue for adding items. As items
 219  * may be different sizes, every item added needs to be calculated as to its
 220  * size and thus this presents a lot of overhead on populating the list, this
 221  * genlist employs a queue. Any item added is queued and spooled off over
 222  * time, actually appearing some time later, so if your list has many members
 223  * you may find it takes a while for them to all appear, with your process
 224  * consuming a lot of CPU while it is busy spooling.
 225  *
 226  * Genlist also implements a tree structure, but it does so with callbacks to
 227  * the application, with the application filling in tree structures when
 228  * requested (allowing for efficient building of a very deep tree that could
 229  * even be used for file-management). See the above smart signal callbacks for
 230  * details.
 231  *
 232  * @section Genlist_Smart_Events Genlist smart events
 233  *
 234  * Signals that you can add callbacks for are:
 235  * - @c "activated" - The user has double-clicked or pressed
 236  *   (enter|return|spacebar) on an item. The @c event_info parameter is the
 237  *   item that was activated.
 238  * - @c "clicked,double" - The user has double-clicked an item.  The @c
 239  *   event_info parameter is the item that was double-clicked.
 240  * - @c "selected" - This is called when a user has made an item selected.
 241  *   The event_info parameter is the genlist item that was selected.
 242  * - @c "unselected" - This is called when a user has made an item
 243  *   unselected. The event_info parameter is the genlist item that was
 244  *   unselected.
 245  * - @c "expanded" - This is called when elm_genlist_item_expanded_set() is
 246  *   called and the item is now meant to be expanded. The event_info
 247  *   parameter is the genlist item that was indicated to expand.  It is the
 248  *   job of this callback to then fill in the child items.
 249  * - @c "contracted" - This is called when elm_genlist_item_expanded_set() is
 250  *   called and the item is now meant to be contracted. The event_info
 251  *   parameter is the genlist item that was indicated to contract. It is the
 252  *   job of this callback to then delete the child items.
 253  * - @c "expand,request" - This is called when a user has indicated they want
 254  *   to expand a tree branch item. The callback should decide if the item can
 255  *   expand (has any children) and then call elm_genlist_item_expanded_set()
 256  *   appropriately to set the state. The event_info parameter is the genlist
 257  *   item that was indicated to expand.
 258  * - @c "contract,request" - This is called when a user has indicated they
 259  *   want to contract a tree branch item. The callback should decide if the
 260  *   item can contract (has any children) and then call
 261  *   elm_genlist_item_expanded_set() appropriately to set the state. The
 262  *   event_info parameter is the genlist item that was indicated to contract.
 263  * - @c "realized" - This is called when the item in the list is created as a
 264  *   real evas object. event_info parameter is the genlist item that was
 265  *   created. The object may be deleted at any time, so it is up to the
 266  *   caller to not use the object pointer from elm_genlist_item_object_get()
 267  *   in a way where it may point to freed objects.
 268  * - @c "unrealized" - This is called just before an item is unrealized.
 269  *   After this call content objects provided will be deleted and the item
 270  *   object itself delete or be put into a floating cache.
 271  * - @c "drag,start,up" - This is called when the item in the list has been
 272  *   dragged (not scrolled) up.
 273  * - @c "drag,start,down" - This is called when the item in the list has been
 274  *   dragged (not scrolled) down.
 275  * - @c "drag,start,left" - This is called when the item in the list has been
 276  *   dragged (not scrolled) left.
 277  * - @c "drag,start,right" - This is called when the item in the list has
 278  *   been dragged (not scrolled) right.
 279  * - @c "drag,stop" - This is called when the item in the list has stopped
 280  *   being dragged.
 281  * - @c "drag" - This is called when the item in the list is being dragged.
 282  * - @c "longpressed" - This is called when the item is pressed for a certain
 283  *   amount of time. By default it's 1 second.
 284  * - @c "scroll,anim,start" - This is called when scrolling animation has
 285  *   started.
 286  * - @c "scroll,anim,stop" - This is called when scrolling animation has
 287  *   stopped.
 288  * - @c "scroll,drag,start" - This is called when dragging the content has
 289  *   started.
 290  * - @c "scroll,drag,stop" - This is called when dragging the content has
 291  *   stopped.
 292  * - @c "edge,top" - This is called when the genlist is scrolled until
 293  *   the top edge.
 294  * - @c "edge,bottom" - This is called when the genlist is scrolled
 295  *   until the bottom edge.
 296  * - @c "edge,left" - This is called when the genlist is scrolled
 297  *   until the left edge.
 298  * - @c "edge,right" - This is called when the genlist is scrolled
 299  *   until the right edge.
 300  * - @c "multi,swipe,left" - This is called when the genlist is multi-touch
 301  *   swiped left.
 302  * - @c "multi,swipe,right" - This is called when the genlist is multi-touch
 303  *   swiped right.
 304  * - @c "multi,swipe,up" - This is called when the genlist is multi-touch
 305  *   swiped up.
 306  * - @c "multi,swipe,down" - This is called when the genlist is multi-touch
 307  *   swiped down.
 308  * - @c "multi,pinch,out" - This is called when the genlist is multi-touch
 309  *   pinched out.  "- @c multi,pinch,in" - This is called when the genlist is
 310  *   multi-touch pinched in.
 311  * - @c "swipe" - This is called when the genlist is swiped.
 312  * - @c "moved" - This is called when a genlist item is moved.
 313  * - @c "language,changed" - This is called when the program's language is
 314  *   changed.
 315  *
 316  * @section Genlist_Examples Examples
 317  *
 318  * Here is a list of examples that use the genlist, trying to show some of
 319  * its capabilities:
 320  * - @ref genlist_example_01
 321  * - @ref genlist_example_02
 322  * - @ref genlist_example_03
 323  * - @ref genlist_example_04
 324  * - @ref genlist_example_05
 325  */
 326
 327 /**
 328  * @addtogroup Genlist
 329  * @{
 330  */
 331
 332 /**
 333  * @enum _Elm_Genlist_Item_Flags
 334  * @typedef Elm_Genlist_Item_Flags
 335  *
 336  * Defines if the item is of any special type (has subitems or it's the
 337  * index of a group), or is just a simple item.
 338  *
 339  * @ingroup Genlist
 340  */
 341 typedef enum _Elm_Genlist_Item_Flags
 342 {
 343    ELM_GENLIST_ITEM_NONE = 0, /**< simple item */
 344    ELM_GENLIST_ITEM_SUBITEMS = (1 << 0), /**< may expand and have child items */
 345    ELM_GENLIST_ITEM_GROUP = (1 << 1) /**< index of a group of items */
 346 } Elm_Genlist_Item_Flags;
 347 typedef enum _Elm_Genlist_Item_Field_Flags
 348 {
 349    ELM_GENLIST_ITEM_FIELD_ALL = 0,
 350    ELM_GENLIST_ITEM_FIELD_LABEL = (1 << 0),
 351    ELM_GENLIST_ITEM_FIELD_CONTENT = (1 << 1),
 352    ELM_GENLIST_ITEM_FIELD_STATE = (1 << 2)
 353 } Elm_Genlist_Item_Field_Flags;
 354 typedef struct _Elm_Genlist_Item_Class      Elm_Genlist_Item_Class; /**< Genlist item class definition structs */
 355 #define Elm_Genlist_Item_Class Elm_Gen_Item_Class
 356 typedef struct _Elm_Genlist_Item            Elm_Genlist_Item; /**< Item of Elm_Genlist. Sub-type of Elm_Widget_Item */
 357 #define Elm_Genlist_Item       Elm_Gen_Item /**< Item of Elm_Genlist. Sub-type of Elm_Widget_Item */
 358 typedef struct _Elm_Genlist_Item_Class_Func Elm_Genlist_Item_Class_Func;    /**< Class functions for genlist item class */
 359
 360 /**
 361  * Text fetching class function for Elm_Gen_Item_Class.
 362  * @param data The data passed in the item creation function
 363  * @param obj The base widget object
 364  * @param part The part name of the swallow
 365  * @return The allocated (NOT stringshared) string to set as the text
 366  */
 367 typedef char *(*Elm_Genlist_Item_Text_Get_Cb)(void *data, Evas_Object *obj, const char *part);
 368
 369 /**
 370  * Content (swallowed object) fetching class function for Elm_Gen_Item_Class.
 371  * @param data The data passed in the item creation function
 372  * @param obj The base widget object
 373  * @param part The part name of the swallow
 374  * @return The content object to swallow
 375  */
 376 typedef Evas_Object *(*Elm_Genlist_Item_Content_Get_Cb)(void *data, Evas_Object *obj, const char *part);
 377
 378 /**
 379  * State fetching class function for Elm_Gen_Item_Class.
 380  * @param data The data passed in the item creation function
 381  * @param obj The base widget object
 382  * @param part The part name of the swallow
 383  * @return The hell if I know
 384  */
 385 typedef Eina_Bool (*Elm_Genlist_Item_State_Get_Cb)(void *data, Evas_Object *obj, const char *part);
 386
 387 /**
 388  * Deletion class function for Elm_Gen_Item_Class.
 389  * @param data The data passed in the item creation function
 390  * @param obj The base widget object
 391  */
 392 typedef void (*Elm_Genlist_Item_Del_Cb)(void *data, Evas_Object *obj);
 393
 394 /**
 395  * @struct _Elm_Genlist_Item_Class
 396  *
 397  * Genlist item class definition structs.
 398  *
 399  * This struct contains the style and fetching functions that will define the
 400  * contents of each item.
 401  *
 402  * @see @ref Genlist_Item_Class
 403  */
 404 struct _Elm_Genlist_Item_Class
 405 {
 406    const char *item_style; /**< style of this class. */
 407    struct Elm_Genlist_Item_Class_Func
 408    {
 409       Elm_Genlist_Item_Text_Get_Cb    text_get; /**< Text fetching class function for genlist item classes.*/
 410       Elm_Genlist_Item_Content_Get_Cb content_get; /**< Content fetching class function for genlist item classes. */
 411       Elm_Genlist_Item_State_Get_Cb   state_get; /**< State fetching class function for genlist item classes. */
 412       Elm_Genlist_Item_Del_Cb         del; /**< Deletion class function for genlist item classes. */
 413    } func;
 414 };
 415 #define Elm_Genlist_Item_Class_Func Elm_Gen_Item_Class_Func
 416 /**
 417  * Add a new genlist widget to the given parent Elementary
 418  * (container) object
 419  *
 420  * @param parent The parent object
 421  * @return a new genlist widget handle or @c NULL, on errors
 422  *
 423  * This function inserts a new genlist widget on the canvas.
 424  *
 425  * @see elm_genlist_item_append()
 426  * @see elm_genlist_item_del()
 427  * @see elm_genlist_clear()
 428  *
 429  * @ingroup Genlist
 430  */
 431 EAPI Evas_Object *
 432                                    elm_genlist_add(Evas_Object *parent)
 433 EINA_ARG_NONNULL(1);
 434
 435 /**
 436  * Remove all items from a given genlist widget.
 437  *
 438  * @param obj The genlist object
 439  *
 440  * This removes (and deletes) all items in @p obj, leaving it empty.
 441  *
 442  * @see elm_genlist_item_del(), to remove just one item.
 443  *
 444  * @ingroup Genlist
 445  */
 446 EAPI void                          elm_genlist_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 447
 448 /**
 449  * Enable or disable multi-selection in the genlist
 450  *
 451  * @param obj The genlist object
 452  * @param multi Multi-select enable/disable. Default is disabled.
 453  *
 454  * This enables (@c EINA_TRUE) or disables (@c EINA_FALSE) multi-selection in
 455  * the list. This allows more than 1 item to be selected. To retrieve the list
 456  * of selected items, use elm_genlist_selected_items_get().
 457  *
 458  * @see elm_genlist_selected_items_get()
 459  * @see elm_genlist_multi_select_get()
 460  *
 461  * @ingroup Genlist
 462  */
 463 EAPI void                          elm_genlist_multi_select_set(Evas_Object *obj, Eina_Bool multi) EINA_ARG_NONNULL(1);
 464
 465 /**
 466  * Gets if multi-selection in genlist is enabled or disabled.
 467  *
 468  * @param obj The genlist object
 469  * @return Multi-select enabled/disabled
 470  * (@c EINA_TRUE = enabled/@c EINA_FALSE = disabled). Default is @c EINA_FALSE.
 471  *
 472  * @see elm_genlist_multi_select_set()
 473  *
 474  * @ingroup Genlist
 475  */
 476 EAPI Eina_Bool                     elm_genlist_multi_select_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 477
 478 /**
 479  * This sets the horizontal stretching mode.
 480  *
 481  * @param obj The genlist object
 482  * @param mode The mode to use (one of #ELM_LIST_SCROLL or #ELM_LIST_LIMIT).
 483  *
 484  * This sets the mode used for sizing items horizontally. Valid modes
 485  * are #ELM_LIST_LIMIT and #ELM_LIST_SCROLL. The default is
 486  * ELM_LIST_SCROLL. This mode means that if items are too wide to fit,
 487  * the scroller will scroll horizontally. Otherwise items are expanded
 488  * to fill the width of the viewport of the scroller. If it is
 489  * ELM_LIST_LIMIT, items will be expanded to the viewport width and
 490  * limited to that size.
 491  *
 492  * @see elm_genlist_horizontal_get()
 493  *
 494  * @ingroup Genlist
 495  */
 496 EAPI void                          elm_genlist_horizontal_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
 497 EINA_DEPRECATED EAPI void          elm_genlist_horizontal_mode_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
 498
 499 /**
 500  * Gets the horizontal stretching mode.
 501  *
 502  * @param obj The genlist object
 503  * @return The mode to use
 504  * (#ELM_LIST_LIMIT, #ELM_LIST_SCROLL)
 505  *
 506  * @see elm_genlist_horizontal_set()
 507  *
 508  * @ingroup Genlist
 509  */
 510 EAPI Elm_List_Mode                 elm_genlist_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 511 EINA_DEPRECATED EAPI Elm_List_Mode elm_genlist_horizontal_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 512
 513 /**
 514  * Set the always select mode.
 515  *
 516  * @param obj The genlist object
 517  * @param always_select The always select mode (@c EINA_TRUE = on, @c
 518  * EINA_FALSE = off). Default is @c EINA_FALSE.
 519  *
 520  * Items will only call their selection func and callback when first
 521  * becoming selected. Any further clicks will do nothing, unless you
 522  * enable always select with elm_genlist_always_select_mode_set().
 523  * This means that, even if selected, every click will make the selected
 524  * callbacks be called.
 525  *
 526  * @see elm_genlist_always_select_mode_get()
 527  *
 528  * @ingroup Genlist
 529  */
 530 EAPI void                          elm_genlist_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
 531
 532 /**
 533  * Get the always select mode.
 534  *
 535  * @param obj The genlist object
 536  * @return The always select mode
 537  * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 538  *
 539  * @see elm_genlist_always_select_mode_set()
 540  *
 541  * @ingroup Genlist
 542  */
 543 EAPI Eina_Bool                     elm_genlist_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 544
 545 /**
 546  * Enable/disable the no select mode.
 547  *
 548  * @param obj The genlist object
 549  * @param no_select The no select mode
 550  * (EINA_TRUE = on, EINA_FALSE = off)
 551  *
 552  * This will turn off the ability to select items entirely and they
 553  * will neither appear selected nor call selected callback functions.
 554  *
 555  * @see elm_genlist_no_select_mode_get()
 556  *
 557  * @ingroup Genlist
 558  */
 559 EAPI void                          elm_genlist_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select) EINA_ARG_NONNULL(1);
 560
 561 /**
 562  * Gets whether the no select mode is enabled.
 563  *
 564  * @param obj The genlist object
 565  * @return The no select mode
 566  * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 567  *
 568  * @see elm_genlist_no_select_mode_set()
 569  *
 570  * @ingroup Genlist
 571  */
 572 EAPI Eina_Bool                     elm_genlist_no_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 573
 574 /**
 575  * Enable/disable compress mode.
 576  *
 577  * @param obj The genlist object
 578  * @param compress The compress mode
 579  * (@c EINA_TRUE = on, @c EINA_FALSE = off). Default is @c EINA_FALSE.
 580  *
 581  * This will enable the compress mode where items are "compressed"
 582  * horizontally to fit the genlist scrollable viewport width. This is
 583  * special for genlist.  Do not rely on
 584  * elm_genlist_horizontal_set() being set to @c ELM_LIST_COMPRESS to
 585  * work as genlist needs to handle it specially.
 586  *
 587  * @see elm_genlist_compress_mode_get()
 588  *
 589  * @ingroup Genlist
 590  */
 591 EAPI void                          elm_genlist_compress_mode_set(Evas_Object *obj, Eina_Bool compress) EINA_ARG_NONNULL(1);
 592
 593 /**
 594  * Get whether the compress mode is enabled.
 595  *
 596  * @param obj The genlist object
 597  * @return The compress mode
 598  * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 599  *
 600  * @see elm_genlist_compress_mode_set()
 601  *
 602  * @ingroup Genlist
 603  */
 604 EAPI Eina_Bool                     elm_genlist_compress_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 605
 606 /**
 607  * Enable/disable height-for-width mode.
 608  *
 609  * @param obj The genlist object
 610  * @param setting The height-for-width mode (@c EINA_TRUE = on,
 611  * @c EINA_FALSE = off). Default is @c EINA_FALSE.
 612  *
 613  * With height-for-width mode the item width will be fixed (restricted
 614  * to a minimum of) to the list width when calculating its size in
 615  * order to allow the height to be calculated based on it. This allows,
 616  * for instance, text block to wrap lines if the Edje part is
 617  * configured with "text.min: 0 1".
 618  *
 619  * @note This mode will make list resize slower as it will have to
 620  *       recalculate every item height again whenever the list width
 621  *       changes!
 622  *
 623  * @note When height-for-width mode is enabled, it also enables
 624  *       compress mode (see elm_genlist_compress_mode_set()) and
 625  *       disables homogeneous (see elm_genlist_homogeneous_set()).
 626  *
 627  * @ingroup Genlist
 628  */
 629 EAPI void                          elm_genlist_height_for_width_mode_set(Evas_Object *obj, Eina_Bool height_for_width) EINA_ARG_NONNULL(1);
 630
 631 /**
 632  * Get whether the height-for-width mode is enabled.
 633  *
 634  * @param obj The genlist object
 635  * @return The height-for-width mode (@c EINA_TRUE = on, @c EINA_FALSE =
 636  * off)
 637  *
 638  * @ingroup Genlist
 639  */
 640 EAPI Eina_Bool                     elm_genlist_height_for_width_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 641
 642 /**
 643  * Enable/disable horizontal and vertical bouncing effect.
 644  *
 645  * @param obj The genlist object
 646  * @param h_bounce Allow bounce horizontally (@c EINA_TRUE = on, @c
 647  * EINA_FALSE = off). Default is @c EINA_FALSE.
 648  * @param v_bounce Allow bounce vertically (@c EINA_TRUE = on, @c
 649  * EINA_FALSE = off). Default is @c EINA_TRUE.
 650  *
 651  * This will enable or disable the scroller bouncing effect for the
 652  * genlist. See elm_scroller_bounce_set() for details.
 653  *
 654  * @see elm_scroller_bounce_set()
 655  * @see elm_genlist_bounce_get()
 656  *
 657  * @ingroup Genlist
 658  */
 659 EAPI void                          elm_genlist_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
 660
 661 /**
 662  * Get whether the horizontal and vertical bouncing effect is enabled.
 663  *
 664  * @param obj The genlist object
 665  * @param h_bounce Pointer to a bool to receive if the bounce horizontally
 666  * option is set.
 667  * @param v_bounce Pointer to a bool to receive if the bounce vertically
 668  * option is set.
 669  *
 670  * @see elm_genlist_bounce_set()
 671  *
 672  * @ingroup Genlist
 673  */
 674 EAPI void                          elm_genlist_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
 675
 676 /**
 677  * Enable/disable homogeneous mode.
 678  *
 679  * @param obj The genlist object
 680  * @param homogeneous Assume the items within the genlist are of the
 681  * same height and width (EINA_TRUE = on, EINA_FALSE = off). Default is @c
 682  * EINA_FALSE.
 683  *
 684  * This will enable the homogeneous mode where items are of the same
 685  * height and width so that genlist may do the lazy-loading at its
 686  * maximum (which increases the performance for scrolling the list). This
 687  * implies 'compressed' mode.
 688  *
 689  * @see elm_genlist_compress_mode_set()
 690  * @see elm_genlist_homogeneous_get()
 691  *
 692  * @ingroup Genlist
 693  */
 694 EAPI void                          elm_genlist_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
 695
 696 /**
 697  * Get whether the homogeneous mode is enabled.
 698  *
 699  * @param obj The genlist object
 700  * @return Assume the items within the genlist are of the same height
 701  * and width (EINA_TRUE = on, EINA_FALSE = off)
 702  *
 703  * @see elm_genlist_homogeneous_set()
 704  *
 705  * @ingroup Genlist
 706  */
 707 EAPI Eina_Bool                     elm_genlist_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 708
 709 /**
 710  * Set the maximum number of items within an item block
 711  *
 712  * @param obj The genlist object
 713  * @param n   Maximum number of items within an item block. Default is 32.
 714  *
 715  * This will configure the block count to tune to the target with
 716  * particular performance matrix.
 717  *
 718  * A block of objects will be used to reduce the number of operations due to
 719  * many objects in the screen. It can determine the visibility, or if the
 720  * object has changed, it theme needs to be updated, etc. doing this kind of
 721  * calculation to the entire block, instead of per object.
 722  *
 723  * The default value for the block count is enough for most lists, so unless
 724  * you know you will have a lot of objects visible in the screen at the same
 725  * time, don't try to change this.
 726  *
 727  * @see elm_genlist_block_count_get()
 728  * @see @ref Genlist_Implementation
 729  *
 730  * @ingroup Genlist
 731  */
 732 EAPI void                          elm_genlist_block_count_set(Evas_Object *obj, int n) EINA_ARG_NONNULL(1);
 733
 734 /**
 735  * Get the maximum number of items within an item block
 736  *
 737  * @param obj The genlist object
 738  * @return Maximum number of items within an item block
 739  *
 740  * @see elm_genlist_block_count_set()
 741  *
 742  * @ingroup Genlist
 743  */
 744 EAPI int                           elm_genlist_block_count_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 745
 746 /**
 747  * Set the timeout in seconds for the longpress event.
 748  *
 749  * @param obj The genlist object
 750  * @param timeout timeout in seconds. Default is 1.
 751  *
 752  * This option will change how long it takes to send an event "longpressed"
 753  * after the mouse down signal is sent to the list. If this event occurs, no
 754  * "clicked" event will be sent.
 755  *
 756  * @see elm_genlist_longpress_timeout_set()
 757  *
 758  * @ingroup Genlist
 759  */
 760 EAPI void                          elm_genlist_longpress_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
 761
 762 /**
 763  * Get the timeout in seconds for the longpress event.
 764  *
 765  * @param obj The genlist object
 766  * @return timeout in seconds
 767  *
 768  * @see elm_genlist_longpress_timeout_get()
 769  *
 770  * @ingroup Genlist
 771  */
 772 EAPI double                        elm_genlist_longpress_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 773
 774 /**
 775  * Append a new item in a given genlist widget.
 776  *
 777  * @param obj The genlist object
 778  * @param itc The item class for the item
 779  * @param data The item data
 780  * @param parent The parent item, or NULL if none
 781  * @param flags Item flags
 782  * @param func Convenience function called when the item is selected
 783  * @param func_data Data passed to @p func above.
 784  * @return A handle to the item added or @c NULL if not possible
 785  *
 786  * This adds the given item to the end of the list or the end of
 787  * the children list if the @p parent is given.
 788  *
 789  * @see elm_genlist_item_prepend()
 790  * @see elm_genlist_item_insert_before()
 791  * @see elm_genlist_item_insert_after()
 792  * @see elm_genlist_item_del()
 793  *
 794  * @ingroup Genlist
 795  */
 796 EAPI Elm_Genlist_Item             *elm_genlist_item_append(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
 797
 798 /**
 799  * Prepend a new item in a given genlist widget.
 800  *
 801  * @param obj The genlist object
 802  * @param itc The item class for the item
 803  * @param data The item data
 804  * @param parent The parent item, or NULL if none
 805  * @param flags Item flags
 806  * @param func Convenience function called when the item is selected
 807  * @param func_data Data passed to @p func above.
 808  * @return A handle to the item added or NULL if not possible
 809  *
 810  * This adds an item to the beginning of the list or beginning of the
 811  * children of the parent if given.
 812  *
 813  * @see elm_genlist_item_append()
 814  * @see elm_genlist_item_insert_before()
 815  * @see elm_genlist_item_insert_after()
 816  * @see elm_genlist_item_del()
 817  *
 818  * @ingroup Genlist
 819  */
 820 EAPI Elm_Genlist_Item             *elm_genlist_item_prepend(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
 821
 822 /**
 823  * Insert an item before another in a genlist widget
 824  *
 825  * @param obj The genlist object
 826  * @param itc The item class for the item
 827  * @param data The item data
 828  * @param before The item to place this new one before.
 829  * @param flags Item flags
 830  * @param func Convenience function called when the item is selected
 831  * @param func_data Data passed to @p func above.
 832  * @return A handle to the item added or @c NULL if not possible
 833  *
 834  * This inserts an item before another in the list. It will be in the
 835  * same tree level or group as the item it is inserted before.
 836  *
 837  * @see elm_genlist_item_append()
 838  * @see elm_genlist_item_prepend()
 839  * @see elm_genlist_item_insert_after()
 840  * @see elm_genlist_item_del()
 841  *
 842  * @ingroup Genlist
 843  */
 844 EAPI Elm_Genlist_Item             *elm_genlist_item_insert_before(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item *before, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1, 5);
 845
 846 /**
 847  * Insert an item after another in a genlist widget
 848  *
 849  * @param obj The genlist object
 850  * @param itc The item class for the item
 851  * @param data The item data
 852  * @param after The item to place this new one after.
 853  * @param flags Item flags
 854  * @param func Convenience function called when the item is selected
 855  * @param func_data Data passed to @p func above.
 856  * @return A handle to the item added or @c NULL if not possible
 857  *
 858  * This inserts an item after another in the list. It will be in the
 859  * same tree level or group as the item it is inserted after.
 860  *
 861  * @see elm_genlist_item_append()
 862  * @see elm_genlist_item_prepend()
 863  * @see elm_genlist_item_insert_before()
 864  * @see elm_genlist_item_del()
 865  *
 866  * @ingroup Genlist
 867  */
 868 EAPI Elm_Genlist_Item             *elm_genlist_item_insert_after(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item *after, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1, 5);
 869
 870 /**
 871  * Insert a new item into the sorted genlist object
 872  *
 873  * @param obj The genlist object
 874  * @param itc The item class for the item
 875  * @param data The item data
 876  * @param parent The parent item, or NULL if none
 877  * @param flags Item flags
 878  * @param comp The function called for the sort
 879  * @param func Convenience function called when item selected
 880  * @param func_data Data passed to @p func above.
 881  * @return A handle to the item added or NULL if not possible
 882  *
 883  * @ingroup Genlist
 884  */
 885 EAPI Elm_Genlist_Item             *elm_genlist_item_sorted_insert(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item_Flags flags, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
 886 EAPI Elm_Genlist_Item             *elm_genlist_item_direct_sorted_insert(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Genlist_Item *parent, Elm_Genlist_Item_Flags flags, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
 887
 888 /* operations to retrieve existing items */
 889 /**
 890  * Get the selectd item in the genlist.
 891  *
 892  * @param obj The genlist object
 893  * @return The selected item, or NULL if none is selected.
 894  *
 895  * This gets the selected item in the list (if multi-selection is enabled, only
 896  * the item that was first selected in the list is returned - which is not very
 897  * useful, so see elm_genlist_selected_items_get() for when multi-selection is
 898  * used).
 899  *
 900  * If no item is selected, NULL is returned.
 901  *
 902  * @see elm_genlist_selected_items_get()
 903  *
 904  * @ingroup Genlist
 905  */
 906 EAPI Elm_Genlist_Item             *elm_genlist_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 907
 908 /**
 909  * Get a list of selected items in the genlist.
 910  *
 911  * @param obj The genlist object
 912  * @return The list of selected items, or NULL if none are selected.
 913  *
 914  * It returns a list of the selected items. This list pointer is only valid so
 915  * long as the selection doesn't change (no items are selected or unselected, or
 916  * unselected implicitly by deletion). The list contains Elm_Genlist_Item
 917  * pointers. The order of the items in this list is the order which they were
 918  * selected, i.e. the first item in this list is the first item that was
 919  * selected, and so on.
 920  *
 921  * @note If not in multi-select mode, consider using function
 922  * elm_genlist_selected_item_get() instead.
 923  *
 924  * @see elm_genlist_multi_select_set()
 925  * @see elm_genlist_selected_item_get()
 926  *
 927  * @ingroup Genlist
 928  */
 929 EAPI const Eina_List              *elm_genlist_selected_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 930
 931 /**
 932  * Get the mode item style of items in the genlist
 933  * @param obj The genlist object
 934  * @return The mode item style string, or NULL if none is specified
 935  *
 936  * This is a constant string and simply defines the name of the
 937  * style that will be used for mode animations. It can be
 938  * @c NULL if you don't plan to use Genlist mode. See
 939  * elm_genlist_item_mode_set() for more info.
 940  *
 941  * @ingroup Genlist
 942  */
 943 EAPI const char                   *elm_genlist_mode_item_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 944
 945 /**
 946  * Set the mode item style of items in the genlist
 947  * @param obj The genlist object
 948  * @param style The mode item style string, or NULL if none is desired
 949  *
 950  * This is a constant string and simply defines the name of the
 951  * style that will be used for mode animations. It can be
 952  * @c NULL if you don't plan to use Genlist mode. See
 953  * elm_genlist_item_mode_set() for more info.
 954  *
 955  * @ingroup Genlist
 956  */
 957 EAPI void                          elm_genlist_mode_item_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
 958
 959 /**
 960  * Get a list of realized items in genlist
 961  *
 962  * @param obj The genlist object
 963  * @return The list of realized items, nor NULL if none are realized.
 964  *
 965  * This returns a list of the realized items in the genlist. The list
 966  * contains Elm_Genlist_Item pointers. The list must be freed by the
 967  * caller when done with eina_list_free(). The item pointers in the
 968  * list are only valid so long as those items are not deleted or the
 969  * genlist is not deleted.
 970  *
 971  * @see elm_genlist_realized_items_update()
 972  *
 973  * @ingroup Genlist
 974  */
 975 EAPI Eina_List                    *elm_genlist_realized_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 976
 977 /**
 978  * Get the item that is at the x, y canvas coords.
 979  *
 980  * @param obj The gelinst object.
 981  * @param x The input x coordinate
 982  * @param y The input y coordinate
 983  * @param posret The position relative to the item returned here
 984  * @return The item at the coordinates or NULL if none
 985  *
 986  * This returns the item at the given coordinates (which are canvas
 987  * relative, not object-relative). If an item is at that coordinate,
 988  * that item handle is returned, and if @p posret is not NULL, the
 989  * integer pointed to is set to a value of -1, 0 or 1, depending if
 990  * the coordinate is on the upper portion of that item (-1), on the
 991  * middle section (0) or on the lower part (1). If NULL is returned as
 992  * an item (no item found there), then posret may indicate -1 or 1
 993  * based if the coordinate is above or below all items respectively in
 994  * the genlist.
 995  *
 996  * @ingroup Genlist
 997  */
 998 EAPI Elm_Genlist_Item             *elm_genlist_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret) EINA_ARG_NONNULL(1);
 999
1000 /**
1001  * Get the first item in the genlist
1002  *
1003  * This returns the first item in the list.
1004  *
1005  * @param obj The genlist object
1006  * @return The first item, or NULL if none
1007  *
1008  * @ingroup Genlist
1009  */
1010 EAPI Elm_Genlist_Item             *elm_genlist_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1011
1012 /**
1013  * Get the last item in the genlist
1014  *
1015  * This returns the last item in the list.
1016  *
1017  * @return The last item, or NULL if none
1018  *
1019  * @ingroup Genlist
1020  */
1021 EAPI Elm_Genlist_Item             *elm_genlist_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1022
1023 /**
1024  * Set the scrollbar policy
1025  *
1026  * @param obj The genlist object
1027  * @param policy_h Horizontal scrollbar policy.
1028  * @param policy_v Vertical scrollbar policy.
1029  *
1030  * This sets the scrollbar visibility policy for the given genlist
1031  * scroller. #ELM_SMART_SCROLLER_POLICY_AUTO means the scrollbar is
1032  * made visible if it is needed, and otherwise kept hidden.
1033  * #ELM_SMART_SCROLLER_POLICY_ON turns it on all the time, and
1034  * #ELM_SMART_SCROLLER_POLICY_OFF always keeps it off. This applies
1035  * respectively for the horizontal and vertical scrollbars. Default is
1036  * #ELM_SMART_SCROLLER_POLICY_AUTO
1037  *
1038  * @see elm_genlist_scroller_policy_get()
1039  *
1040  * @ingroup Genlist
1041  */
1042 EAPI void                          elm_genlist_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v) EINA_ARG_NONNULL(1);
1043
1044 /**
1045  * Get the scrollbar policy
1046  *
1047  * @param obj The genlist object
1048  * @param policy_h Pointer to store the horizontal scrollbar policy.
1049  * @param policy_v Pointer to store the vertical scrollbar policy.
1050  *
1051  * @see elm_genlist_scroller_policy_set()
1052  *
1053  * @ingroup Genlist
1054  */
1055 EAPI void                          elm_genlist_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v) EINA_ARG_NONNULL(1);
1056
1057 /**
1058  * Get the @b next item in a genlist widget's internal list of items,
1059  * given a handle to one of those items.
1060  *
1061  * @param item The genlist item to fetch next from
1062  * @return The item after @p item, or @c NULL if there's none (and
1063  * on errors)
1064  *
1065  * This returns the item placed after the @p item, on the container
1066  * genlist.
1067  *
1068  * @see elm_genlist_item_prev_get()
1069  *
1070  * @ingroup Genlist
1071  */
1072 EAPI Elm_Genlist_Item             *elm_genlist_item_next_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1073
1074 /**
1075  * Get the @b previous item in a genlist widget's internal list of items,
1076  * given a handle to one of those items.
1077  *
1078  * @param item The genlist item to fetch previous from
1079  * @return The item before @p item, or @c NULL if there's none (and
1080  * on errors)
1081  *
1082  * This returns the item placed before the @p item, on the container
1083  * genlist.
1084  *
1085  * @see elm_genlist_item_next_get()
1086  *
1087  * @ingroup Genlist
1088  */
1089 EAPI Elm_Genlist_Item             *elm_genlist_item_prev_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1090
1091 /**
1092  * Get the genlist object's handle which contains a given genlist
1093  * item
1094  *
1095  * @param item The item to fetch the container from
1096  * @return The genlist (parent) object
1097  *
1098  * This returns the genlist object itself that an item belongs to.
1099  *
1100  * @ingroup Genlist
1101  */
1102 EAPI Evas_Object                  *elm_genlist_item_genlist_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1103
1104 /**
1105  * Get the parent item of the given item
1106  *
1107  * @param it The item
1108  * @return The parent of the item or @c NULL if it has no parent.
1109  *
1110  * This returns the item that was specified as parent of the item @p it on
1111  * elm_genlist_item_append() and insertion related functions.
1112  *
1113  * @ingroup Genlist
1114  */
1115 EAPI Elm_Genlist_Item             *elm_genlist_item_parent_get(const Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1116
1117 /**
1118  * Remove all sub-items (children) of the given item
1119  *
1120  * @param it The item
1121  *
1122  * This removes all items that are children (and their descendants) of the
1123  * given item @p it.
1124  *
1125  * @see elm_genlist_clear()
1126  * @see elm_genlist_item_del()
1127  *
1128  * @ingroup Genlist
1129  */
1130 EAPI void                          elm_genlist_item_subitems_clear(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1131
1132 /**
1133  * Set whether a given genlist item is selected or not
1134  *
1135  * @param it The item
1136  * @param selected Use @c EINA_TRUE, to make it selected, @c
1137  * EINA_FALSE to make it unselected
1138  *
1139  * This sets the selected state of an item. If multi selection is
1140  * not enabled on the containing genlist and @p selected is @c
1141  * EINA_TRUE, any other previously selected items will get
1142  * unselected in favor of this new one.
1143  *
1144  * @see elm_genlist_item_selected_get()
1145  *
1146  * @ingroup Genlist
1147  */
1148 EAPI void                          elm_genlist_item_selected_set(Elm_Genlist_Item *item, Eina_Bool selected) EINA_ARG_NONNULL(1);
1149
1150 /**
1151  * Get whether a given genlist item is selected or not
1152  *
1153  * @param it The item
1154  * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
1155  *
1156  * @see elm_genlist_item_selected_set() for more details
1157  *
1158  * @ingroup Genlist
1159  */
1160 EAPI Eina_Bool                     elm_genlist_item_selected_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1161
1162 /**
1163  * Sets the expanded state of an item.
1164  *
1165  * @param it The item
1166  * @param expanded The expanded state (@c EINA_TRUE expanded, @c EINA_FALSE not expanded).
1167  *
1168  * This function flags the item of type #ELM_GENLIST_ITEM_SUBITEMS as
1169  * expanded or not.
1170  *
1171  * The theme will respond to this change visually, and a signal "expanded" or
1172  * "contracted" will be sent from the genlist with a pointer to the item that
1173  * has been expanded/contracted.
1174  *
1175  * Calling this function won't show or hide any child of this item (if it is
1176  * a parent). You must manually delete and create them on the callbacks fo
1177  * the "expanded" or "contracted" signals.
1178  *
1179  * @see elm_genlist_item_expanded_get()
1180  *
1181  * @ingroup Genlist
1182  */
1183 EAPI void                          elm_genlist_item_expanded_set(Elm_Genlist_Item *item, Eina_Bool expanded) EINA_ARG_NONNULL(1);
1184
1185 /**
1186  * Get the expanded state of an item
1187  *
1188  * @param it The item
1189  * @return The expanded state
1190  *
1191  * This gets the expanded state of an item.
1192  *
1193  * @see elm_genlist_item_expanded_set()
1194  *
1195  * @ingroup Genlist
1196  */
1197 EAPI Eina_Bool                     elm_genlist_item_expanded_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1198
1199 /**
1200  * Get the depth of expanded item
1201  *
1202  * @param it The genlist item object
1203  * @return The depth of expanded item
1204  *
1205  * @ingroup Genlist
1206  */
1207 EAPI int                           elm_genlist_item_expanded_depth_get(const Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1208
1209 /**
1210  * Set whether a given genlist item is disabled or not.
1211  *
1212  * @param it The item
1213  * @param disabled Use @c EINA_TRUE, true disable it, @c EINA_FALSE
1214  * to enable it back.
1215  *
1216  * A disabled item cannot be selected or unselected. It will also
1217  * change its appearance, to signal the user it's disabled.
1218  *
1219  * @see elm_genlist_item_disabled_get()
1220  *
1221  * @ingroup Genlist
1222  */
1223 EAPI void                          elm_genlist_item_disabled_set(Elm_Genlist_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
1224
1225 /**
1226  * Get whether a given genlist item is disabled or not.
1227  *
1228  * @param it The item
1229  * @return @c EINA_TRUE, if it's disabled, @c EINA_FALSE otherwise
1230  * (and on errors).
1231  *
1232  * @see elm_genlist_item_disabled_set() for more details
1233  *
1234  * @ingroup Genlist
1235  */
1236 EAPI Eina_Bool                     elm_genlist_item_disabled_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1237
1238 /**
1239  * Sets the display only state of an item.
1240  *
1241  * @param it The item
1242  * @param display_only @c EINA_TRUE if the item is display only, @c
1243  * EINA_FALSE otherwise.
1244  *
1245  * A display only item cannot be selected or unselected. It is for
1246  * display only and not selecting or otherwise clicking, dragging
1247  * etc. by the user, thus finger size rules will not be applied to
1248  * this item.
1249  *
1250  * It's good to set group index items to display only state.
1251  *
1252  * @see elm_genlist_item_display_only_get()
1253  *
1254  * @ingroup Genlist
1255  */
1256 EAPI void                          elm_genlist_item_display_only_set(Elm_Genlist_Item *it, Eina_Bool display_only) EINA_ARG_NONNULL(1);
1257
1258 /**
1259  * Get the display only state of an item
1260  *
1261  * @param it The item
1262  * @return @c EINA_TRUE if the item is display only, @c
1263  * EINA_FALSE otherwise.
1264  *
1265  * @see elm_genlist_item_display_only_set()
1266  *
1267  * @ingroup Genlist
1268  */
1269 EAPI Eina_Bool                     elm_genlist_item_display_only_get(const Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1270
1271 /**
1272  * Show the portion of a genlist's internal list containing a given
1273  * item, immediately.
1274  *
1275  * @param it The item to display
1276  *
1277  * This causes genlist to jump to the given item @p it and show it (by
1278  * immediately scrolling to that position), if it is not fully visible.
1279  *
1280  * @see elm_genlist_item_bring_in()
1281  * @see elm_genlist_item_top_show()
1282  * @see elm_genlist_item_middle_show()
1283  *
1284  * @ingroup Genlist
1285  */
1286 EAPI void                          elm_genlist_item_show(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1287
1288 /**
1289  * Animatedly bring in, to the visible are of a genlist, a given
1290  * item on it.
1291  *
1292  * @param it The item to display
1293  *
1294  * This causes genlist to jump to the given item @p it and show it (by
1295  * animatedly scrolling), if it is not fully visible. This may use animation
1296  * to do so and take a period of time
1297  *
1298  * @see elm_genlist_item_show()
1299  * @see elm_genlist_item_top_bring_in()
1300  * @see elm_genlist_item_middle_bring_in()
1301  *
1302  * @ingroup Genlist
1303  */
1304 EAPI void                          elm_genlist_item_bring_in(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1305
1306 /**
1307  * Show the portion of a genlist's internal list containing a given
1308  * item, immediately.
1309  *
1310  * @param it The item to display
1311  *
1312  * This causes genlist to jump to the given item @p it and show it (by
1313  * immediately scrolling to that position), if it is not fully visible.
1314  *
1315  * The item will be positioned at the top of the genlist viewport.
1316  *
1317  * @see elm_genlist_item_show()
1318  * @see elm_genlist_item_top_bring_in()
1319  *
1320  * @ingroup Genlist
1321  */
1322 EAPI void                          elm_genlist_item_top_show(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1323
1324 /**
1325  * Animatedly bring in, to the visible are of a genlist, a given
1326  * item on it.
1327  *
1328  * @param it The item
1329  *
1330  * This causes genlist to jump to the given item @p it and show it (by
1331  * animatedly scrolling), if it is not fully visible. This may use animation
1332  * to do so and take a period of time
1333  *
1334  * The item will be positioned at the top of the genlist viewport.
1335  *
1336  * @see elm_genlist_item_bring_in()
1337  * @see elm_genlist_item_top_show()
1338  *
1339  * @ingroup Genlist
1340  */
1341 EAPI void                          elm_genlist_item_top_bring_in(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1342
1343 /**
1344  * Show the portion of a genlist's internal list containing a given
1345  * item, immediately.
1346  *
1347  * @param it The item to display
1348  *
1349  * This causes genlist to jump to the given item @p it and show it (by
1350  * immediately scrolling to that position), if it is not fully visible.
1351  *
1352  * The item will be positioned at the middle of the genlist viewport.
1353  *
1354  * @see elm_genlist_item_show()
1355  * @see elm_genlist_item_middle_bring_in()
1356  *
1357  * @ingroup Genlist
1358  */
1359 EAPI void                          elm_genlist_item_middle_show(Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1360
1361 /**
1362  * Animatedly bring in, to the visible are of a genlist, a given
1363  * item on it.
1364  *
1365  * @param it The item
1366  *
1367  * This causes genlist to jump to the given item @p it and show it (by
1368  * animatedly scrolling), if it is not fully visible. This may use animation
1369  * to do so and take a period of time
1370  *
1371  * The item will be positioned at the middle of the genlist viewport.
1372  *
1373  * @see elm_genlist_item_bring_in()
1374  * @see elm_genlist_item_middle_show()
1375  *
1376  * @ingroup Genlist
1377  */
1378 EAPI void                          elm_genlist_item_middle_bring_in(Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1379
1380 /**
1381  * Remove a genlist item from the its parent, deleting it.
1382  *
1383  * @param item The item to be removed.
1384  * @return @c EINA_TRUE on success or @c EINA_FALSE, otherwise.
1385  *
1386  * @see elm_genlist_clear(), to remove all items in a genlist at
1387  * once.
1388  *
1389  * @ingroup Genlist
1390  */
1391 EAPI void                          elm_genlist_item_del(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1392
1393 /**
1394  * Return the data associated to a given genlist item
1395  *
1396  * @param item The genlist item.
1397  * @return the data associated to this item.
1398  *
1399  * This returns the @c data value passed on the
1400  * elm_genlist_item_append() and related item addition calls.
1401  *
1402  * @see elm_genlist_item_append()
1403  * @see elm_genlist_item_data_set()
1404  *
1405  * @ingroup Genlist
1406  */
1407 EAPI void                         *elm_genlist_item_data_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1408
1409 /**
1410  * Set the data associated to a given genlist item
1411  *
1412  * @param item The genlist item
1413  * @param data The new data pointer to set on it
1414  *
1415  * This @b overrides the @c data value passed on the
1416  * elm_genlist_item_append() and related item addition calls. This
1417  * function @b won't call elm_genlist_item_update() automatically,
1418  * so you'd issue it afterwards if you want to hove the item
1419  * updated to reflect the that new data.
1420  *
1421  * @see elm_genlist_item_data_get()
1422  *
1423  * @ingroup Genlist
1424  */
1425 EAPI void                          elm_genlist_item_data_set(Elm_Genlist_Item *it, const void *data) EINA_ARG_NONNULL(1);
1426
1427 /**
1428  * Tells genlist to "orphan" contents fetchs by the item class
1429  *
1430  * @param it The item
1431  *
1432  * This instructs genlist to release references to contents in the item,
1433  * meaning that they will no longer be managed by genlist and are
1434  * floating "orphans" that can be re-used elsewhere if the user wants
1435  * to.
1436  *
1437  * @ingroup Genlist
1438  */
1439 EAPI void                          elm_genlist_item_contents_orphan(Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1440 EINA_DEPRECATED EAPI void          elm_genlist_item_icons_orphan(Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1441
1442 /**
1443  * Get the real Evas object created to implement the view of a
1444  * given genlist item
1445  *
1446  * @param item The genlist item.
1447  * @return the Evas object implementing this item's view.
1448  *
1449  * This returns the actual Evas object used to implement the
1450  * specified genlist item's view. This may be @c NULL, as it may
1451  * not have been created or may have been deleted, at any time, by
1452  * the genlist. <b>Do not modify this object</b> (move, resize,
1453  * show, hide, etc.), as the genlist is controlling it. This
1454  * function is for querying, emitting custom signals or hooking
1455  * lower level callbacks for events on that object. Do not delete
1456  * this object under any circumstances.
1457  *
1458  * @see elm_genlist_item_data_get()
1459  *
1460  * @ingroup Genlist
1461  */
1462 EAPI const Evas_Object            *elm_genlist_item_object_get(const Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1463
1464 /**
1465  * Update the contents of an item
1466  *
1467  * @param it The item
1468  *
1469  * This updates an item by calling all the item class functions again
1470  * to get the contents, texts and states. Use this when the original
1471  * item data has changed and the changes are desired to be reflected.
1472  *
1473  * Use elm_genlist_realized_items_update() to update all already realized
1474  * items.
1475  *
1476  * @see elm_genlist_realized_items_update()
1477  *
1478  * @ingroup Genlist
1479  */
1480 EAPI void                          elm_genlist_item_update(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1481
1482 /**
1483  * Promote an item to the top of the list
1484  *
1485  * @param it The item
1486  *
1487  * @ingroup Genlist
1488  */
1489 EAPI void                          elm_genlist_item_promote(Elm_Gen_Item *it) EINA_ARG_NONNULL(1);
1490
1491 /**
1492  * Demote an item to the end of the list
1493  *
1494  * @param it The item
1495  *
1496  * @ingroup Genlist
1497  */
1498 EAPI void                          elm_genlist_item_demote(Elm_Gen_Item *it) EINA_ARG_NONNULL(1);
1499
1500 /**
1501  * Update the part of an item
1502  *
1503  * @param it The item
1504  * @param parts The name of item's part
1505  * @param itf The flags of item's part type
1506  *
1507  * This updates an item's part by calling item's fetching functions again
1508  * to get the contents, texts and states. Use this when the original
1509  * item data has changed and the changes are desired to be reflected.
1510  * Second parts argument is used for globbing to match '*', '?', and '.'
1511  * It can be used at updating multi fields.
1512  *
1513  * Use elm_genlist_realized_items_update() to update an item's all
1514  * property.
1515  *
1516  * @see elm_genlist_item_update()
1517  *
1518  * @ingroup Genlist
1519  */
1520 EAPI void                          elm_genlist_item_fields_update(Elm_Genlist_Item *it, const char *parts, Elm_Genlist_Item_Field_Flags itf) EINA_ARG_NONNULL(1);
1521
1522 /**
1523  * Update the item class of an item
1524  *
1525  * @param it The item
1526  * @param itc The item class for the item
1527  *
1528  * This sets another class fo the item, changing the way that it is
1529  * displayed. After changing the item class, elm_genlist_item_update() is
1530  * called on the item @p it.
1531  *
1532  * @ingroup Genlist
1533  */
1534 EAPI void                          elm_genlist_item_item_class_update(Elm_Genlist_Item *it, const Elm_Genlist_Item_Class *itc) EINA_ARG_NONNULL(1, 2);
1535 EAPI const Elm_Genlist_Item_Class *elm_genlist_item_item_class_get(const Elm_Genlist_Item *it) EINA_ARG_NONNULL(1);
1536
1537 /**
1538  * Set the text to be shown in a given genlist item's tooltips.
1539  *
1540  * @param item The genlist item
1541  * @param text The text to set in the content
1542  *
1543  * This call will setup the text to be used as tooltip to that item
1544  * (analogous to elm_object_tooltip_text_set(), but being item
1545  * tooltips with higher precedence than object tooltips). It can
1546  * have only one tooltip at a time, so any previous tooltip data
1547  * will get removed.
1548  *
1549  * In order to set a content or something else as a tooltip, look at
1550  * elm_genlist_item_tooltip_content_cb_set().
1551  *
1552  * @ingroup Genlist
1553  */
1554 EAPI void                          elm_genlist_item_tooltip_text_set(Elm_Genlist_Item *item, const char *text) EINA_ARG_NONNULL(1);
1555
1556 /**
1557  * Set the content to be shown in a given genlist item's tooltips
1558  *
1559  * @param item The genlist item.
1560  * @param func The function returning the tooltip contents.
1561  * @param data What to provide to @a func as callback data/context.
1562  * @param del_cb Called when data is not needed anymore, either when
1563  *        another callback replaces @p func, the tooltip is unset with
1564  *        elm_genlist_item_tooltip_unset() or the owner @p item
1565  *        dies. This callback receives as its first parameter the
1566  *        given @p data, being @c event_info the item handle.
1567  *
1568  * This call will setup the tooltip's contents to @p item
1569  * (analogous to elm_object_tooltip_content_cb_set(), but being
1570  * item tooltips with higher precedence than object tooltips). It
1571  * can have only one tooltip at a time, so any previous tooltip
1572  * content will get removed. @p func (with @p data) will be called
1573  * every time Elementary needs to show the tooltip and it should
1574  * return a valid Evas object, which will be fully managed by the
1575  * tooltip system, getting deleted when the tooltip is gone.
1576  *
1577  * In order to set just a text as a tooltip, look at
1578  * elm_genlist_item_tooltip_text_set().
1579  *
1580  * @ingroup Genlist
1581  */
1582 EAPI void                          elm_genlist_item_tooltip_content_cb_set(Elm_Genlist_Item *item, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb) EINA_ARG_NONNULL(1);
1583
1584 /**
1585  * Unset a tooltip from a given genlist item
1586  *
1587  * @param item genlist item to remove a previously set tooltip from.
1588  *
1589  * This call removes any tooltip set on @p item. The callback
1590  * provided as @c del_cb to
1591  * elm_genlist_item_tooltip_content_cb_set() will be called to
1592  * notify it is not used anymore (and have resources cleaned, if
1593  * need be).
1594  *
1595  * @see elm_genlist_item_tooltip_content_cb_set()
1596  *
1597  * @ingroup Genlist
1598  */
1599 EAPI void                          elm_genlist_item_tooltip_unset(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1600
1601 /**
1602  * Set a different @b style for a given genlist item's tooltip.
1603  *
1604  * @param item genlist item with tooltip set
1605  * @param style the <b>theme style</b> to use on tooltips (e.g. @c
1606  * "default", @c "transparent", etc)
1607  *
1608  * Tooltips can have <b>alternate styles</b> to be displayed on,
1609  * which are defined by the theme set on Elementary. This function
1610  * works analogously as elm_object_tooltip_style_set(), but here
1611  * applied only to genlist item objects. The default style for
1612  * tooltips is @c "default".
1613  *
1614  * @note before you set a style you should define a tooltip with
1615  *       elm_genlist_item_tooltip_content_cb_set() or
1616  *       elm_genlist_item_tooltip_text_set()
1617  *
1618  * @see elm_genlist_item_tooltip_style_get()
1619  *
1620  * @ingroup Genlist
1621  */
1622 EAPI void                          elm_genlist_item_tooltip_style_set(Elm_Genlist_Item *item, const char *style) EINA_ARG_NONNULL(1);
1623
1624 /**
1625  * Get the style set a given genlist item's tooltip.
1626  *
1627  * @param item genlist item with tooltip already set on.
1628  * @return style the theme style in use, which defaults to
1629  *         "default". If the object does not have a tooltip set,
1630  *         then @c NULL is returned.
1631  *
1632  * @see elm_genlist_item_tooltip_style_set() for more details
1633  *
1634  * @ingroup Genlist
1635  */
1636 EAPI const char                   *elm_genlist_item_tooltip_style_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1637
1638 /**
1639  * @brief Disable size restrictions on an object's tooltip
1640  * @param item The tooltip's anchor object
1641  * @param disable If EINA_TRUE, size restrictions are disabled
1642  * @return EINA_FALSE on failure, EINA_TRUE on success
1643  *
1644  * This function allows a tooltip to expand beyond its parant window's canvas.
1645  * It will instead be limited only by the size of the display.
1646  */
1647 EAPI Eina_Bool                     elm_genlist_item_tooltip_window_mode_set(Elm_Genlist_Item *item, Eina_Bool disable);
1648
1649 /**
1650  * @brief Retrieve size restriction state of an object's tooltip
1651  * @param item The tooltip's anchor object
1652  * @return If EINA_TRUE, size restrictions are disabled
1653  *
1654  * This function returns whether a tooltip is allowed to expand beyond
1655  * its parant window's canvas.
1656  * It will instead be limited only by the size of the display.
1657  */
1658 EAPI Eina_Bool                     elm_genlist_item_tooltip_window_mode_get(const Elm_Genlist_Item *item);
1659
1660 /**
1661  * Set the type of mouse pointer/cursor decoration to be shown,
1662  * when the mouse pointer is over the given genlist widget item
1663  *
1664  * @param item genlist item to customize cursor on
1665  * @param cursor the cursor type's name
1666  *
1667  * This function works analogously as elm_object_cursor_set(), but
1668  * here the cursor's changing area is restricted to the item's
1669  * area, and not the whole widget's. Note that that item cursors
1670  * have precedence over widget cursors, so that a mouse over @p
1671  * item will always show cursor @p type.
1672  *
1673  * If this function is called twice for an object, a previously set
1674  * cursor will be unset on the second call.
1675  *
1676  * @see elm_object_cursor_set()
1677  * @see elm_genlist_item_cursor_get()
1678  * @see elm_genlist_item_cursor_unset()
1679  *
1680  * @ingroup Genlist
1681  */
1682 EAPI void                          elm_genlist_item_cursor_set(Elm_Genlist_Item *item, const char *cursor) EINA_ARG_NONNULL(1);
1683
1684 /**
1685  * Get the type of mouse pointer/cursor decoration set to be shown,
1686  * when the mouse pointer is over the given genlist widget item
1687  *
1688  * @param item genlist item with custom cursor set
1689  * @return the cursor type's name or @c NULL, if no custom cursors
1690  * were set to @p item (and on errors)
1691  *
1692  * @see elm_object_cursor_get()
1693  * @see elm_genlist_item_cursor_set() for more details
1694  * @see elm_genlist_item_cursor_unset()
1695  *
1696  * @ingroup Genlist
1697  */
1698 EAPI const char                   *elm_genlist_item_cursor_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1699
1700 /**
1701  * Unset any custom mouse pointer/cursor decoration set to be
1702  * shown, when the mouse pointer is over the given genlist widget
1703  * item, thus making it show the @b default cursor again.
1704  *
1705  * @param item a genlist item
1706  *
1707  * Use this call to undo any custom settings on this item's cursor
1708  * decoration, bringing it back to defaults (no custom style set).
1709  *
1710  * @see elm_object_cursor_unset()
1711  * @see elm_genlist_item_cursor_set() for more details
1712  *
1713  * @ingroup Genlist
1714  */
1715 EAPI void                          elm_genlist_item_cursor_unset(Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1716
1717 /**
1718  * Set a different @b style for a given custom cursor set for a
1719  * genlist item.
1720  *
1721  * @param item genlist item with custom cursor set
1722  * @param style the <b>theme style</b> to use (e.g. @c "default",
1723  * @c "transparent", etc)
1724  *
1725  * This function only makes sense when one is using custom mouse
1726  * cursor decorations <b>defined in a theme file</b> , which can
1727  * have, given a cursor name/type, <b>alternate styles</b> on
1728  * it. It works analogously as elm_object_cursor_style_set(), but
1729  * here applied only to genlist item objects.
1730  *
1731  * @warning Before you set a cursor style you should have defined a
1732  *       custom cursor previously on the item, with
1733  *       elm_genlist_item_cursor_set()
1734  *
1735  * @see elm_genlist_item_cursor_engine_only_set()
1736  * @see elm_genlist_item_cursor_style_get()
1737  *
1738  * @ingroup Genlist
1739  */
1740 EAPI void                          elm_genlist_item_cursor_style_set(Elm_Genlist_Item *item, const char *style) EINA_ARG_NONNULL(1);
1741
1742 /**
1743  * Get the current @b style set for a given genlist item's custom
1744  * cursor
1745  *
1746  * @param item genlist item with custom cursor set.
1747  * @return style the cursor style in use. If the object does not
1748  *         have a cursor set, then @c NULL is returned.
1749  *
1750  * @see elm_genlist_item_cursor_style_set() for more details
1751  *
1752  * @ingroup Genlist
1753  */
1754 EAPI const char                   *elm_genlist_item_cursor_style_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1755
1756 /**
1757  * Set if the (custom) cursor for a given genlist item should be
1758  * searched in its theme, also, or should only rely on the
1759  * rendering engine.
1760  *
1761  * @param item item with custom (custom) cursor already set on
1762  * @param engine_only Use @c EINA_TRUE to have cursors looked for
1763  * only on those provided by the rendering engine, @c EINA_FALSE to
1764  * have them searched on the widget's theme, as well.
1765  *
1766  * @note This call is of use only if you've set a custom cursor
1767  * for genlist items, with elm_genlist_item_cursor_set().
1768  *
1769  * @note By default, cursors will only be looked for between those
1770  * provided by the rendering engine.
1771  *
1772  * @ingroup Genlist
1773  */
1774 EAPI void                          elm_genlist_item_cursor_engine_only_set(Elm_Genlist_Item *item, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
1775
1776 /**
1777  * Get if the (custom) cursor for a given genlist item is being
1778  * searched in its theme, also, or is only relying on the rendering
1779  * engine.
1780  *
1781  * @param item a genlist item
1782  * @return @c EINA_TRUE, if cursors are being looked for only on
1783  * those provided by the rendering engine, @c EINA_FALSE if they
1784  * are being searched on the widget's theme, as well.
1785  *
1786  * @see elm_genlist_item_cursor_engine_only_set(), for more details
1787  *
1788  * @ingroup Genlist
1789  */
1790 EAPI Eina_Bool                     elm_genlist_item_cursor_engine_only_get(const Elm_Genlist_Item *item) EINA_ARG_NONNULL(1);
1791
1792 /**
1793  * Get the index of the item. It is only valid once displayed.
1794  *
1795  * @param item a genlist item
1796  * @return the position inside the list of item.
1797  *
1798  * @ingroup Genlist
1799  */
1800 EAPI int                           elm_genlist_item_index_get(Elm_Gen_Item *it);
1801
1802 /**
1803  * Update the contents of all realized items.
1804  *
1805  * @param obj The genlist object.
1806  *
1807  * This updates all realized items by calling all the item class functions again
1808  * to get the contents, texts and states. Use this when the original
1809  * item data has changed and the changes are desired to be reflected.
1810  *
1811  * To update just one item, use elm_genlist_item_update().
1812  *
1813  * @see elm_genlist_realized_items_get()
1814  * @see elm_genlist_item_update()
1815  *
1816  * @ingroup Genlist
1817  */
1818 EAPI void                          elm_genlist_realized_items_update(Evas_Object *obj) EINA_ARG_NONNULL(1);
1819
1820 /**
1821  * Activate a genlist mode on an item
1822  *
1823  * @param item The genlist item
1824  * @param mode Mode name
1825  * @param mode_set Boolean to define set or unset mode.
1826  *
1827  * A genlist mode is a different way of selecting an item. Once a mode is
1828  * activated on an item, any other selected item is immediately unselected.
1829  * This feature provides an easy way of implementing a new kind of animation
1830  * for selecting an item, without having to entirely rewrite the item style
1831  * theme. However, the elm_genlist_selected_* API can't be used to get what
1832  * item is activate for a mode.
1833  *
1834  * The current item style will still be used, but applying a genlist mode to
1835  * an item will select it using a different kind of animation.
1836  *
1837  * The current active item for a mode can be found by
1838  * elm_genlist_mode_item_get().
1839  *
1840  * The characteristics of genlist mode are:
1841  * - Only one mode can be active at any time, and for only one item.
1842  * - Genlist handles deactivating other items when one item is activated.
1843  * - A mode is defined in the genlist theme (edc), and more modes can easily
1844  *   be added.
1845  * - A mode style and the genlist item style are different things. They
1846  *   can be combined to provide a default style to the item, with some kind
1847  *   of animation for that item when the mode is activated.
1848  *
1849  * When a mode is activated on an item, a new view for that item is created.
1850  * The theme of this mode defines the animation that will be used to transit
1851  * the item from the old view to the new view. This second (new) view will be
1852  * active for that item while the mode is active on the item, and will be
1853  * destroyed after the mode is totally deactivated from that item.
1854  *
1855  * @see elm_genlist_mode_get()
1856  * @see elm_genlist_mode_item_get()
1857  *
1858  * @ingroup Genlist
1859  */
1860 EAPI void                          elm_genlist_item_mode_set(Elm_Genlist_Item *it, const char *mode_type, Eina_Bool mode_set) EINA_ARG_NONNULL(1, 2);
1861
1862 /**
1863  * Get the last (or current) genlist mode used.
1864  *
1865  * @param obj The genlist object
1866  *
1867  * This function just returns the name of the last used genlist mode. It will
1868  * be the current mode if it's still active.
1869  *
1870  * @see elm_genlist_item_mode_set()
1871  * @see elm_genlist_mode_item_get()
1872  *
1873  * @ingroup Genlist
1874  */
1875 EAPI const char                   *elm_genlist_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1876
1877 /**
1878  * Get active genlist mode item
1879  *
1880  * @param obj The genlist object
1881  * @return The active item for that current mode. Or @c NULL if no item is
1882  * activated with any mode.
1883  *
1884  * This function returns the item that was activated with a mode, by the
1885  * function elm_genlist_item_mode_set().
1886  *
1887  * @see elm_genlist_item_mode_set()
1888  * @see elm_genlist_mode_get()
1889  *
1890  * @ingroup Genlist
1891  */
1892 EAPI const Elm_Genlist_Item       *elm_genlist_mode_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1893
1894 /**
1895  * Set reorder mode
1896  *
1897  * @param obj The genlist object
1898  * @param reorder_mode The reorder mode
1899  * (EINA_TRUE = on, EINA_FALSE = off)
1900  *
1901  * @ingroup Genlist
1902  */
1903 EAPI void                          elm_genlist_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode) EINA_ARG_NONNULL(1);
1904
1905 /**
1906  * Get the reorder mode
1907  *
1908  * @param obj The genlist object
1909  * @return The reorder mode
1910  * (EINA_TRUE = on, EINA_FALSE = off)
1911  *
1912  * @ingroup Genlist
1913  */
1914 EAPI Eina_Bool                     elm_genlist_reorder_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1915
1916 /**
1917  * @}
1918  */