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 label, 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 "texts", @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_Object_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_gen_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_gen_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_gen_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_TEXT = (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    typedef struct _Elm_Genlist_Item       Elm_Genlist_Item; /**< Item of Elm_Genlist. Sub-type of Elm_Widget_Item */
 356    typedef struct _Elm_Genlist_Item_Class_Func Elm_Genlist_Item_Class_Func;
 357    typedef char        *(*GenlistItemTextGetFunc) (void *data, Evas_Object *obj, const char *part);
 358    typedef Evas_Object *(*GenlistItemContentGetFunc)  (void *data, Evas_Object *obj, const char *part);
 359    typedef Eina_Bool    (*GenlistItemStateGetFunc) (void *data, Evas_Object *obj, const char *part);
 360    typedef void         (*GenlistItemDelFunc)      (void *data, Evas_Object *obj);
 361    typedef void         (*GenlistItemMovedFunc)    ( Evas_Object *genlist, Elm_Object_Item *item, Elm_Object_Item *rel_item, Eina_Bool move_after);
 362
 363    /**
 364     * @struct _Elm_Genlist_Item_Class
 365     *
 366     * Genlist item class definition structs.
 367     *
 368     * This struct contains the style and fetching functions that will define the
 369     * contents of each item.
 370     *
 371     * @see @ref Genlist_Item_Class
 372     */
 373    struct _Elm_Genlist_Item_Class
 374      {
 375         const char                *item_style;
 376         struct {
 377           GenlistItemTextGetFunc  text_get;
 378           GenlistItemContentGetFunc   content_get;
 379           GenlistItemStateGetFunc  state_get;
 380           GenlistItemDelFunc       del;
 381           GenlistItemMovedFunc     moved;
 382         } func;
 383         const char *edit_item_style;
 384         const char                *mode_item_style;
 385      };
 386    #define Elm_Genlist_Item_Class_Func Elm_Gen_Item_Class_Func
 387    /**
 388     * Add a new genlist widget to the given parent Elementary
 389     * (container) object
 390     *
 391     * @param parent The parent object
 392     * @return a new genlist widget handle or @c NULL, on errors
 393     *
 394     * This function inserts a new genlist widget on the canvas.
 395     *
 396     * @see elm_genlist_item_append()
 397     * @see elm_genlist_item_del()
 398     * @see elm_gen_clear()
 399     *
 400     * @ingroup Genlist
 401     */
 402    EAPI Evas_Object      *elm_genlist_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
 403    /**
 404     * Remove all items from a given genlist widget.
 405     *
 406     * @param obj The genlist object
 407     *
 408     * This removes (and deletes) all items in @p obj, leaving it empty.
 409     *
 410     * This is deprecated. Please use elm_gen_clear() instead.
 411     *
 412     * @see elm_genlist_item_del(), to remove just one item.
 413     *
 414     * @ingroup Genlist
 415     */
 416    EAPI void elm_genlist_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 417    /**
 418     * Enable or disable multi-selection in the genlist
 419     *
 420     * @param obj The genlist object
 421     * @param multi Multi-select enable/disable. Default is disabled.
 422     *
 423     * This enables (@c EINA_TRUE) or disables (@c EINA_FALSE) multi-selection in
 424     * the list. This allows more than 1 item to be selected. To retrieve the list
 425     * of selected items, use elm_genlist_selected_items_get().
 426     *
 427     * @see elm_genlist_selected_items_get()
 428     * @see elm_genlist_multi_select_get()
 429     *
 430     * @ingroup Genlist
 431     */
 432    EAPI void              elm_genlist_multi_select_set(Evas_Object *obj, Eina_Bool multi) EINA_ARG_NONNULL(1);
 433    /**
 434     * Gets if multi-selection in genlist is enabled or disabled.
 435     *
 436     * @param obj The genlist object
 437     * @return Multi-select enabled/disabled
 438     * (@c EINA_TRUE = enabled/@c EINA_FALSE = disabled). Default is @c EINA_FALSE.
 439     *
 440     * @see elm_genlist_multi_select_set()
 441     *
 442     * @ingroup Genlist
 443     */
 444    EAPI Eina_Bool         elm_genlist_multi_select_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 445    /**
 446     * This sets the horizontal stretching mode.
 447     *
 448     * @param obj The genlist object
 449     * @param mode The mode to use (one of #ELM_LIST_SCROLL or #ELM_LIST_LIMIT).
 450     *
 451     * This sets the mode used for sizing items horizontally. Valid modes
 452     * are #ELM_LIST_LIMIT and #ELM_LIST_SCROLL. The default is
 453     * ELM_LIST_SCROLL. This mode means that if items are too wide to fit,
 454     * the scroller will scroll horizontally. Otherwise items are expanded
 455     * to fill the width of the viewport of the scroller. If it is
 456     * ELM_LIST_LIMIT, items will be expanded to the viewport width and
 457     * limited to that size.
 458     *
 459     * @see elm_genlist_horizontal_get()
 460     *
 461     * @ingroup Genlist
 462     */
 463    EAPI void              elm_genlist_horizontal_mode_set(Evas_Object *obj, Elm_List_Mode mode) EINA_ARG_NONNULL(1);
 464    /**
 465     * Gets the horizontal stretching mode.
 466     *
 467     * @param obj The genlist object
 468     * @return The mode to use
 469     * (#ELM_LIST_LIMIT, #ELM_LIST_SCROLL)
 470     *
 471     * @see elm_genlist_horizontal_set()
 472     *
 473     * @ingroup Genlist
 474     */
 475    EAPI Elm_List_Mode     elm_genlist_horizontal_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 476    /**
 477     * Set the always select mode.
 478     *
 479     * @param obj The genlist object
 480     * @param always_select The always select mode (@c EINA_TRUE = on, @c
 481     * EINA_FALSE = off). Default is @c EINA_FALSE.
 482     *
 483     * Items will only call their selection func and callback when first
 484     * becoming selected. Any further clicks will do nothing, unless you
 485     * enable always select with elm_gen_always_select_mode_set().
 486     * This means that, even if selected, every click will make the selected
 487     * callbacks be called.
 488     *
 489     * This function is deprecated. please see elm_gen_always_select_mode_set()
 490     *
 491     * @see elm_genlist_always_select_mode_get()
 492     *
 493     * @ingroup Genlist
 494     */
 495    EAPI void              elm_genlist_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select) EINA_ARG_NONNULL(1);
 496    /**
 497     * Get the always select mode.
 498     *
 499     * @param obj The genlist object
 500     * @return The always select mode
 501     * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 502     *
 503     * @see elm_genlist_always_select_mode_set()
 504     *
 505     * @ingroup Genlist
 506     */
 507    EAPI Eina_Bool         elm_genlist_always_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 508    /**
 509     * Enable/disable the no select mode.
 510     *
 511     * @param obj The genlist object
 512     * @param no_select The no select mode
 513     * (EINA_TRUE = on, EINA_FALSE = off)
 514     *
 515     * This will turn off the ability to select items entirely and they
 516     * will neither appear selected nor call selected callback functions.
 517     *
 518     * @see elm_genlist_no_select_mode_get()
 519     *
 520     * @ingroup Genlist
 521     */
 522    EAPI void              elm_genlist_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select) EINA_ARG_NONNULL(1);
 523    /**
 524     * Gets whether the no select mode is enabled.
 525     *
 526     * @param obj The genlist object
 527     * @return The no select mode
 528     * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 529     *
 530     * @see elm_genlist_no_select_mode_set()
 531     *
 532     * @ingroup Genlist
 533     */
 534    EAPI Eina_Bool         elm_genlist_no_select_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 535    /**
 536     * Enable/disable compress mode.
 537     *
 538     * @param obj The genlist object
 539     * @param compress The compress mode
 540     * (@c EINA_TRUE = on, @c EINA_FALSE = off). Default is @c EINA_FALSE.
 541     *
 542     * This will enable the compress mode where items are "compressed"
 543     * horizontally to fit the genlist scrollable viewport width. This is
 544     * special for genlist.  Do not rely on
 545     * elm_genlist_horizontal_set() being set to @c ELM_LIST_COMPRESS to
 546     * work as genlist needs to handle it specially.
 547     *
 548     * @see elm_genlist_compress_mode_get()
 549     *
 550     * @ingroup Genlist
 551     */
 552    EAPI void              elm_genlist_compress_mode_set(Evas_Object *obj, Eina_Bool compress) EINA_ARG_NONNULL(1);
 553    /**
 554     * Get whether the compress mode is enabled.
 555     *
 556     * @param obj The genlist object
 557     * @return The compress mode
 558     * (@c EINA_TRUE = on, @c EINA_FALSE = off)
 559     *
 560     * @see elm_genlist_compress_mode_set()
 561     *
 562     * @ingroup Genlist
 563     */
 564    EAPI Eina_Bool         elm_genlist_compress_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 565    /**
 566     * Enable/disable height-for-width mode.
 567     *
 568     * @param obj The genlist object
 569     * @param setting The height-for-width mode (@c EINA_TRUE = on,
 570     * @c EINA_FALSE = off). Default is @c EINA_FALSE.
 571     *
 572     * With height-for-width mode the item width will be fixed (restricted
 573     * to a minimum of) to the list width when calculating its size in
 574     * order to allow the height to be calculated based on it. This allows,
 575     * for instance, text block to wrap lines if the Edje part is
 576     * configured with "text.min: 0 1".
 577     *
 578     * @note This mode will make list resize slower as it will have to
 579     *       recalculate every item height again whenever the list width
 580     *       changes!
 581     *
 582     * @note When height-for-width mode is enabled, it also enables
 583     *       compress mode (see elm_genlist_compress_mode_set()) and
 584     *       disables homogeneous (see elm_genlist_homogeneous_set()).
 585     *
 586     * @ingroup Genlist
 587     */
 588    EAPI void              elm_genlist_height_for_width_mode_set(Evas_Object *obj, Eina_Bool height_for_width) EINA_ARG_NONNULL(1);
 589    /**
 590     * Get whether the height-for-width mode is enabled.
 591     *
 592     * @param obj The genlist object
 593     * @return The height-for-width mode (@c EINA_TRUE = on, @c EINA_FALSE =
 594     * off)
 595     *
 596     * @ingroup Genlist
 597     */
 598    EAPI Eina_Bool         elm_genlist_height_for_width_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 599    /**
 600     * Enable/disable horizontal and vertical bouncing effect.
 601     *
 602     * @param obj The genlist object
 603     * @param h_bounce Allow bounce horizontally (@c EINA_TRUE = on, @c
 604     * EINA_FALSE = off). Default is @c EINA_FALSE.
 605     * @param v_bounce Allow bounce vertically (@c EINA_TRUE = on, @c
 606     * EINA_FALSE = off). Default is @c EINA_TRUE.
 607     *
 608     * This will enable or disable the scroller bouncing effect for the
 609     * genlist. See elm_scroller_bounce_set() for details.
 610     *
 611     * @see elm_scroller_bounce_set()
 612     * @see elm_genlist_bounce_get()
 613     *
 614     * @ingroup Genlist
 615     */
 616    EAPI void              elm_genlist_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
 617    /**
 618     * Get whether the horizontal and vertical bouncing effect is enabled.
 619     *
 620     * @param obj The genlist object
 621     * @param h_bounce Pointer to a bool to receive if the bounce horizontally
 622     * option is set.
 623     * @param v_bounce Pointer to a bool to receive if the bounce vertically
 624     * option is set.
 625     *
 626     * @see elm_genlist_bounce_set()
 627     *
 628     * @ingroup Genlist
 629     */
 630    EAPI void              elm_genlist_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
 631    /**
 632     * Enable/disable homogenous mode.
 633     *
 634     * @param obj The genlist object
 635     * @param homogeneous Assume the items within the genlist are of the
 636     * same height and width (EINA_TRUE = on, EINA_FALSE = off). Default is @c
 637     * EINA_FALSE.
 638     *
 639     * This will enable the homogeneous mode where items are of the same
 640     * height and width so that genlist may do the lazy-loading at its
 641     * maximum (which increases the performance for scrolling the list). This
 642     * implies 'compressed' mode.
 643     *
 644     * @see elm_genlist_compress_mode_set()
 645     * @see elm_genlist_homogeneous_get()
 646     *
 647     * @ingroup Genlist
 648     */
 649    EAPI void              elm_genlist_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1);
 650    /**
 651     * Get whether the homogenous mode is enabled.
 652     *
 653     * @param obj The genlist object
 654     * @return Assume the items within the genlist are of the same height
 655     * and width (EINA_TRUE = on, EINA_FALSE = off)
 656     *
 657     * @see elm_genlist_homogeneous_set()
 658     *
 659     * @ingroup Genlist
 660     */
 661    EAPI Eina_Bool         elm_genlist_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 662    /**
 663     * Set the maximum number of items within an item block
 664     *
 665     * @param obj The genlist object
 666     * @param n   Maximum number of items within an item block. Default is 32.
 667     *
 668     * This will configure the block count to tune to the target with
 669     * particular performance matrix.
 670     *
 671     * A block of objects will be used to reduce the number of operations due to
 672     * many objects in the screen. It can determine the visibility, or if the
 673     * object has changed, it theme needs to be updated, etc. doing this kind of
 674     * calculation to the entire block, instead of per object.
 675     *
 676     * The default value for the block count is enough for most lists, so unless
 677     * you know you will have a lot of objects visible in the screen at the same
 678     * time, don't try to change this.
 679     *
 680     * @see elm_genlist_block_count_get()
 681     * @see @ref Genlist_Implementation
 682     *
 683     * @ingroup Genlist
 684     */
 685    EAPI void              elm_genlist_block_count_set(Evas_Object *obj, int n) EINA_ARG_NONNULL(1);
 686    /**
 687     * Get the maximum number of items within an item block
 688     *
 689     * @param obj The genlist object
 690     * @return Maximum number of items within an item block
 691     *
 692     * @see elm_genlist_block_count_set()
 693     *
 694     * @ingroup Genlist
 695     */
 696    EAPI int               elm_genlist_block_count_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 697    /**
 698     * Set the timeout in seconds for the longpress event.
 699     *
 700     * @param obj The genlist object
 701     * @param timeout timeout in seconds. Default is 1.
 702     *
 703     * This option will change how long it takes to send an event "longpressed"
 704     * after the mouse down signal is sent to the list. If this event occurs, no
 705     * "clicked" event will be sent.
 706     *
 707     * @see elm_genlist_longpress_timeout_set()
 708     *
 709     * @ingroup Genlist
 710     */
 711    EAPI void              elm_genlist_longpress_timeout_set(Evas_Object *obj, double timeout) EINA_ARG_NONNULL(1);
 712    /**
 713     * Get the timeout in seconds for the longpress event.
 714     *
 715     * @param obj The genlist object
 716     * @return timeout in seconds
 717     *
 718     * @see elm_genlist_longpress_timeout_get()
 719     *
 720     * @ingroup Genlist
 721     */
 722    EAPI double            elm_genlist_longpress_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 723    /**
 724     * Append a new item in a given genlist widget.
 725     *
 726     * @param obj The genlist object
 727     * @param itc The item class for the item
 728     * @param data The item data
 729     * @param parent The parent item, or NULL if none
 730     * @param flags Item flags
 731     * @param func Convenience function called when the item is selected
 732     * @param func_data Data passed to @p func above.
 733     * @return A handle to the item added or @c NULL if not possible
 734     *
 735     * This adds the given item to the end of the list or the end of
 736     * the children list if the @p parent is given.
 737     *
 738     * @see elm_genlist_item_prepend()
 739     * @see elm_genlist_item_insert_before()
 740     * @see elm_genlist_item_insert_after()
 741     * @see elm_genlist_item_del()
 742     *
 743     * @ingroup Genlist
 744     */
 745    EAPI Elm_Object_Item *elm_genlist_item_append(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
 746    /**
 747     * Prepend a new item in a given genlist widget.
 748     *
 749     * @param obj The genlist object
 750     * @param itc The item class for the item
 751     * @param data The item data
 752     * @param parent The parent item, or NULL if none
 753     * @param flags Item flags
 754     * @param func Convenience function called when the item is selected
 755     * @param func_data Data passed to @p func above.
 756     * @return A handle to the item added or NULL if not possible
 757     *
 758     * This adds an item to the beginning of the list or beginning of the
 759     * children of the parent if given.
 760     *
 761     * @see elm_genlist_item_append()
 762     * @see elm_genlist_item_insert_before()
 763     * @see elm_genlist_item_insert_after()
 764     * @see elm_genlist_item_del()
 765     *
 766     * @ingroup Genlist
 767     */
 768    EAPI Elm_Object_Item *elm_genlist_item_prepend(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1);
 769    /**
 770     * Insert an item before another in a genlist widget
 771     *
 772     * @param obj The genlist object
 773     * @param itc The item class for the item
 774     * @param data The item data
 775     * @param before The item to place this new one before.
 776     * @param flags Item flags
 777     * @param func Convenience function called when the item is selected
 778     * @param func_data Data passed to @p func above.
 779     * @return A handle to the item added or @c NULL if not possible
 780     *
 781     * This inserts an item before another in the list. It will be in the
 782     * same tree level or group as the item it is inserted before.
 783     *
 784     * @see elm_genlist_item_append()
 785     * @see elm_genlist_item_prepend()
 786     * @see elm_genlist_item_insert_after()
 787     * @see elm_genlist_item_del()
 788     *
 789     * @ingroup Genlist
 790     */
 791    EAPI Elm_Object_Item *elm_genlist_item_insert_before(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Object_Item *before, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1, 5);
 792    /**
 793     * Insert an item after another in a genlist widget
 794     *
 795     * @param obj The genlist object
 796     * @param itc The item class for the item
 797     * @param data The item data
 798     * @param after The item to place this new one after.
 799     * @param flags Item flags
 800     * @param func Convenience function called when the item is selected
 801     * @param func_data Data passed to @p func above.
 802     * @return A handle to the item added or @c NULL if not possible
 803     *
 804     * This inserts an item after another in the list. It will be in the
 805     * same tree level or group as the item it is inserted after.
 806     *
 807     * @see elm_genlist_item_append()
 808     * @see elm_genlist_item_prepend()
 809     * @see elm_genlist_item_insert_before()
 810     * @see elm_genlist_item_del()
 811     *
 812     * @ingroup Genlist
 813     */
 814    EAPI Elm_Object_Item *elm_genlist_item_insert_after(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Object_Item *after, Elm_Genlist_Item_Flags flags, Evas_Smart_Cb func, const void *func_data) EINA_ARG_NONNULL(1, 5);
 815    /**
 816     * Insert a new item into the sorted genlist object
 817     *
 818     * @param obj The genlist object
 819     * @param itc The item class for the item
 820     * @param data The item data
 821     * @param parent The parent item, or NULL if none
 822     * @param flags Item flags
 823     * @param comp The function called for the sort
 824     * @param func Convenience function called when item selected
 825     * @param func_data Data passed to @p func above.
 826     * @return A handle to the item added or NULL if not possible
 827     *
 828     * @ingroup Genlist
 829     */
 830    EAPI Elm_Object_Item *elm_genlist_item_sorted_insert(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Genlist_Item_Flags flags, Eina_Compare_Cb comp, Evas_Smart_Cb func,const void *func_data);
 831    EAPI Elm_Object_Item *elm_genlist_item_direct_sorted_insert(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, const void *data, Elm_Object_Item *parent, Elm_Genlist_Item_Flags flags, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
 832    /* operations to retrieve existing items */
 833    /**
 834     * Get the selectd item in the genlist.
 835     *
 836     * @param obj The genlist object
 837     * @return The selected item, or NULL if none is selected.
 838     *
 839     * This gets the selected item in the list (if multi-selection is enabled, only
 840     * the item that was first selected in the list is returned - which is not very
 841     * useful, so see elm_genlist_selected_items_get() for when multi-selection is
 842     * used).
 843     *
 844     * If no item is selected, NULL is returned.
 845     *
 846     * @see elm_genlist_selected_items_get()
 847     *
 848     * @ingroup Genlist
 849     */
 850    EAPI Elm_Object_Item *elm_genlist_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 851    /**
 852     * Get a list of selected items in the genlist.
 853     *
 854     * @param obj The genlist object
 855     * @return The list of selected items, or NULL if none are selected.
 856     *
 857     * It returns a list of the selected items. This list pointer is only valid so
 858     * long as the selection doesn't change (no items are selected or unselected, or
 859     * unselected implicitly by deletion). The list contains Elm_Genlist_Item
 860     * pointers. The order of the items in this list is the order which they were
 861     * selected, i.e. the first item in this list is the first item that was
 862     * selected, and so on.
 863     *
 864     * @note If not in multi-select mode, consider using function
 865     * elm_genlist_selected_item_get() instead.
 866     *
 867     * @see elm_genlist_multi_select_set()
 868     * @see elm_genlist_selected_item_get()
 869     *
 870     * @ingroup Genlist
 871     */
 872    EAPI const Eina_List  *elm_genlist_selected_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 873    /**
 874     * Get the mode item style of items in the genlist
 875     * @param obj The genlist object
 876     * @return The mode item style string, or NULL if none is specified
 877     *
 878     * This is a constant string and simply defines the name of the
 879     * style that will be used for mode animations. It can be
 880     * @c NULL if you don't plan to use Genlist mode. See
 881     * elm_genlist_item_mode_set() for more info.
 882     *
 883     * @ingroup Genlist
 884     */
 885    EAPI const char       *elm_genlist_mode_item_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 886    /**
 887     * Set the mode item style of items in the genlist
 888     * @param obj The genlist object
 889     * @param style The mode item style string, or NULL if none is desired
 890     *
 891     * This is a constant string and simply defines the name of the
 892     * style that will be used for mode animations. It can be
 893     * @c NULL if you don't plan to use Genlist mode. See
 894     * elm_genlist_item_mode_set() for more info.
 895     *
 896     * @ingroup Genlist
 897     */
 898    EAPI void              elm_genlist_mode_item_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
 899    /**
 900     * Get a list of realized items in genlist
 901     *
 902     * @param obj The genlist object
 903     * @return The list of realized items, nor NULL if none are realized.
 904     *
 905     * This returns a list of the realized items in the genlist. The list
 906     * contains Elm_Genlist_Item pointers. The list must be freed by the
 907     * caller when done with eina_list_free(). The item pointers in the
 908     * list are only valid so long as those items are not deleted or the
 909     * genlist is not deleted.
 910     *
 911     * @see elm_genlist_realized_items_update()
 912     *
 913     * @ingroup Genlist
 914     */
 915    EAPI Eina_List        *elm_genlist_realized_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 916    /**
 917     * Get the item that is at the x, y canvas coords.
 918     *
 919     * @param obj The gelinst object.
 920     * @param x The input x coordinate
 921     * @param y The input y coordinate
 922     * @param posret The position relative to the item returned here
 923     * @return The item at the coordinates or NULL if none
 924     *
 925     * This returns the item at the given coordinates (which are canvas
 926     * relative, not object-relative). If an item is at that coordinate,
 927     * that item handle is returned, and if @p posret is not NULL, the
 928     * integer pointed to is set to a value of -1, 0 or 1, depending if
 929     * the coordinate is on the upper portion of that item (-1), on the
 930     * middle section (0) or on the lower part (1). If NULL is returned as
 931     * an item (no item found there), then posret may indicate -1 or 1
 932     * based if the coordinate is above or below all items respectively in
 933     * the genlist.
 934     *
 935     * @ingroup Genlist
 936     */
 937    EAPI Elm_Object_Item *elm_genlist_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret) EINA_ARG_NONNULL(1);
 938    /**
 939     * Get the first item in the genlist
 940     *
 941     * This returns the first item in the list.
 942     *
 943     * @param obj The genlist object
 944     * @return The first item, or NULL if none
 945     *
 946     * @ingroup Genlist
 947     */
 948    EAPI Elm_Object_Item *elm_genlist_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 949    /**
 950     * Get the last item in the genlist
 951     *
 952     * This returns the last item in the list.
 953     *
 954     * @return The last item, or NULL if none
 955     *
 956     * @ingroup Genlist
 957     */
 958    EAPI Elm_Object_Item *elm_genlist_last_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 959    /**
 960     * Set the scrollbar policy
 961     *
 962     * @param obj The genlist object
 963     * @param policy_h Horizontal scrollbar policy.
 964     * @param policy_v Vertical scrollbar policy.
 965     *
 966     * This sets the scrollbar visibility policy for the given genlist
 967     * scroller. #ELM_SMART_SCROLLER_POLICY_AUTO means the scrollbar is
 968     * made visible if it is needed, and otherwise kept hidden.
 969     * #ELM_SMART_SCROLLER_POLICY_ON turns it on all the time, and
 970     * #ELM_SMART_SCROLLER_POLICY_OFF always keeps it off. This applies
 971     * respectively for the horizontal and vertical scrollbars. Default is
 972     * #ELM_SMART_SCROLLER_POLICY_AUTO
 973     *
 974     * @see elm_genlist_scroller_policy_get()
 975     *
 976     * @ingroup Genlist
 977     */
 978    EAPI void              elm_genlist_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v) EINA_ARG_NONNULL(1);
 979    /**
 980     * Get the scrollbar policy
 981     *
 982     * @param obj The genlist object
 983     * @param policy_h Pointer to store the horizontal scrollbar policy.
 984     * @param policy_v Pointer to store the vertical scrollbar policy.
 985     *
 986     * @see elm_genlist_scroller_policy_set()
 987     *
 988     * @ingroup Genlist
 989     */
 990    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);
 991    /**
 992     * Get the @b next item in a genlist widget's internal list of items,
 993     * given a handle to one of those items.
 994     *
 995     * @param item The genlist item to fetch next from
 996     * @return The item after @p item, or @c NULL if there's none (and
 997     * on errors)
 998     *
 999     * This returns the item placed after the @p item, on the container
1000     * genlist.
1001     *
1002     * @see elm_genlist_item_prev_get()
1003     *
1004     * @ingroup Genlist
1005     */
1006    EAPI Elm_Object_Item  *elm_genlist_item_next_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1007    /**
1008     * Get the @b previous item in a genlist widget's internal list of items,
1009     * given a handle to one of those items.
1010     *
1011     * @param item The genlist item to fetch previous from
1012     * @return The item before @p item, or @c NULL if there's none (and
1013     * on errors)
1014     *
1015     * This returns the item placed before the @p item, on the container
1016     * genlist.
1017     *
1018     * @see elm_genlist_item_next_get()
1019     *
1020     * @ingroup Genlist
1021     */
1022    EAPI Elm_Object_Item  *elm_genlist_item_prev_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1023    /**
1024     * Get the genlist object's handle which contains a given genlist
1025     * item
1026     *
1027     * @param item The item to fetch the container from
1028     * @return The genlist (parent) object
1029     *
1030     * This returns the genlist object itself that an item belongs to.
1031     *
1032     * This function is deprecated. Please use elm_gen_item_widget_get()
1033     *
1034     * @ingroup Genlist
1035     */
1036    EAPI Evas_Object       *elm_genlist_item_genlist_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1037    /**
1038     * Get the parent item of the given item
1039     *
1040     * @param it The item
1041     * @return The parent of the item or @c NULL if it has no parent.
1042     *
1043     * This returns the item that was specified as parent of the item @p it on
1044     * elm_genlist_item_append() and insertion related functions.
1045     *
1046     * @ingroup Genlist
1047     */
1048    EAPI Elm_Object_Item  *elm_genlist_item_parent_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1049    /**
1050     * Remove all sub-items (children) of the given item
1051     *
1052     * @param it The item
1053     *
1054     * This removes all items that are children (and their descendants) of the
1055     * given item @p it.
1056     *
1057     * @see elm_genlist_clear()
1058     * @see elm_genlist_item_del()
1059     *
1060     * @ingroup Genlist
1061     */
1062    EAPI void               elm_genlist_item_subitems_clear(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1063    /**
1064     * Set whether a given genlist item is selected or not
1065     *
1066     * @param it The item
1067     * @param selected Use @c EINA_TRUE, to make it selected, @c
1068     * EINA_FALSE to make it unselected
1069     *
1070     * This sets the selected state of an item. If multi selection is
1071     * not enabled on the containing genlist and @p selected is @c
1072     * EINA_TRUE, any other previously selected items will get
1073     * unselected in favor of this new one.
1074     *
1075     * @see elm_genlist_item_selected_get()
1076     *
1077     * @ingroup Genlist
1078     */
1079    EAPI void elm_genlist_item_selected_set(Elm_Object_Item *item, Eina_Bool selected) EINA_ARG_NONNULL(1);
1080    /**
1081     * Get whether a given genlist item is selected or not
1082     *
1083     * @param it The item
1084     * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
1085     *
1086     * @see elm_genlist_item_selected_set() for more details
1087     *
1088     * @ingroup Genlist
1089     */
1090    EAPI Eina_Bool elm_genlist_item_selected_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1091    /**
1092     * Sets the expanded state of an item.
1093     *
1094     * @param it The item
1095     * @param expanded The expanded state (@c EINA_TRUE expanded, @c EINA_FALSE not expanded).
1096     *
1097     * This function flags the item of type #ELM_GENLIST_ITEM_SUBITEMS as
1098     * expanded or not.
1099     *
1100     * The theme will respond to this change visually, and a signal "expanded" or
1101     * "contracted" will be sent from the genlist with a pointer to the item that
1102     * has been expanded/contracted.
1103     *
1104     * Calling this function won't show or hide any child of this item (if it is
1105     * a parent). You must manually delete and create them on the callbacks fo
1106     * the "expanded" or "contracted" signals.
1107     *
1108     * @see elm_genlist_item_expanded_get()
1109     *
1110     * @ingroup Genlist
1111     */
1112    EAPI void               elm_genlist_item_expanded_set(Elm_Object_Item *item, Eina_Bool expanded) EINA_ARG_NONNULL(1);
1113    /**
1114     * Get the expanded state of an item
1115     *
1116     * @param it The item
1117     * @return The expanded state
1118     *
1119     * This gets the expanded state of an item.
1120     *
1121     * @see elm_genlist_item_expanded_set()
1122     *
1123     * @ingroup Genlist
1124     */
1125    EAPI Eina_Bool          elm_genlist_item_expanded_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1126    /**
1127     * Get the depth of expanded item
1128     *
1129     * @param it The genlist item object
1130     * @return The depth of expanded item
1131     *
1132     * @ingroup Genlist
1133     */
1134    EAPI int                elm_genlist_item_expanded_depth_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1135    /**
1136     * Set whether a given genlist item is disabled or not.
1137     *
1138     * @param it The item
1139     * @param disabled Use @c EINA_TRUE, true disable it, @c EINA_FALSE
1140     * to enable it back.
1141     *
1142     * A disabled item cannot be selected or unselected. It will also
1143     * change its appearance, to signal the user it's disabled.
1144     *
1145     * @see elm_genlist_item_disabled_get()
1146     *
1147     * @ingroup Genlist
1148     */
1149    EAPI void               elm_genlist_item_disabled_set(Elm_Object_Item *item, Eina_Bool disabled) EINA_ARG_NONNULL(1);
1150    /**
1151     * Get whether a given genlist item is disabled or not.
1152     *
1153     * @param it The item
1154     * @return @c EINA_TRUE, if it's disabled, @c EINA_FALSE otherwise
1155     * (and on errors).
1156     *
1157     * @see elm_genlist_item_disabled_set() for more details
1158     *
1159     * @ingroup Genlist
1160     */
1161    EAPI Eina_Bool          elm_genlist_item_disabled_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1162    /**
1163     * Sets the display only state of an item.
1164     *
1165     * @param it The item
1166     * @param display_only @c EINA_TRUE if the item is display only, @c
1167     * EINA_FALSE otherwise.
1168     *
1169     * A display only item cannot be selected or unselected. It is for
1170     * display only and not selecting or otherwise clicking, dragging
1171     * etc. by the user, thus finger size rules will not be applied to
1172     * this item.
1173     *
1174     * It's good to set group index items to display only state.
1175     *
1176     * @see elm_genlist_item_display_only_get()
1177     *
1178     * @ingroup Genlist
1179     */
1180    EAPI void               elm_genlist_item_display_only_set(Elm_Object_Item *it, Eina_Bool display_only) EINA_ARG_NONNULL(1);
1181    /**
1182     * Get the display only state of an item
1183     *
1184     * @param it The item
1185     * @return @c EINA_TRUE if the item is display only, @c
1186     * EINA_FALSE otherwise.
1187     *
1188     * @see elm_genlist_item_display_only_set()
1189     *
1190     * @ingroup Genlist
1191     */
1192    EAPI Eina_Bool          elm_genlist_item_display_only_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1193    /**
1194     * Show the portion of a genlist's internal list containing a given
1195     * item, immediately.
1196     *
1197     * @param it The item to display
1198     *
1199     * This causes genlist to jump to the given item @p it and show it (by
1200     * immediately scrolling to that position), if it is not fully visible.
1201     *
1202     * @see elm_genlist_item_bring_in()
1203     * @see elm_genlist_item_top_show()
1204     * @see elm_genlist_item_middle_show()
1205     *
1206     * @ingroup Genlist
1207     */
1208    EAPI void               elm_genlist_item_show(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1209    /**
1210     * Animatedly bring in, to the visible are of a genlist, a given
1211     * item on it.
1212     *
1213     * @param it The item to display
1214     *
1215     * This causes genlist to jump to the given item @p it and show it (by
1216     * animatedly scrolling), if it is not fully visible. This may use animation
1217     * to do so and take a period of time
1218     *
1219     * @see elm_genlist_item_show()
1220     * @see elm_genlist_item_top_bring_in()
1221     * @see elm_genlist_item_middle_bring_in()
1222     *
1223     * @ingroup Genlist
1224     */
1225    EAPI void               elm_genlist_item_bring_in(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1226    /**
1227     * Show the portion of a genlist's internal list containing a given
1228     * item, immediately.
1229     *
1230     * @param it The item to display
1231     *
1232     * This causes genlist to jump to the given item @p it and show it (by
1233     * immediately scrolling to that position), if it is not fully visible.
1234     *
1235     * The item will be positioned at the top of the genlist viewport.
1236     *
1237     * @see elm_genlist_item_show()
1238     * @see elm_genlist_item_top_bring_in()
1239     *
1240     * @ingroup Genlist
1241     */
1242    EAPI void               elm_genlist_item_top_show(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1243    /**
1244     * Animatedly bring in, to the visible are of a genlist, a given
1245     * item on it.
1246     *
1247     * @param it The item
1248     *
1249     * This causes genlist to jump to the given item @p it and show it (by
1250     * animatedly scrolling), if it is not fully visible. This may use animation
1251     * to do so and take a period of time
1252     *
1253     * The item will be positioned at the top of the genlist viewport.
1254     *
1255     * @see elm_genlist_item_bring_in()
1256     * @see elm_genlist_item_top_show()
1257     *
1258     * @ingroup Genlist
1259     */
1260    EAPI void               elm_genlist_item_top_bring_in(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1261    /**
1262     * Show the portion of a genlist's internal list containing a given
1263     * item, immediately.
1264     *
1265     * @param it The item to display
1266     *
1267     * This causes genlist to jump to the given item @p it and show it (by
1268     * immediately scrolling to that position), if it is not fully visible.
1269     *
1270     * The item will be positioned at the middle of the genlist viewport.
1271     *
1272     * @see elm_genlist_item_show()
1273     * @see elm_genlist_item_middle_bring_in()
1274     *
1275     * @ingroup Genlist
1276     */
1277    EAPI void               elm_genlist_item_middle_show(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1278    /**
1279     * Animatedly bring in, to the visible are of a genlist, a given
1280     * item on it.
1281     *
1282     * @param it The item
1283     *
1284     * This causes genlist to jump to the given item @p it and show it (by
1285     * animatedly scrolling), if it is not fully visible. This may use animation
1286     * to do so and take a period of time
1287     *
1288     * The item will be positioned at the middle of the genlist viewport.
1289     *
1290     * @see elm_genlist_item_bring_in()
1291     * @see elm_genlist_item_middle_show()
1292     *
1293     * @ingroup Genlist
1294     */
1295    EAPI void               elm_genlist_item_middle_bring_in(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1296    /**
1297     * Remove a genlist item from the its parent, deleting it.
1298     *
1299     * @param item The item to be removed.
1300     * @return @c EINA_TRUE on success or @c EINA_FALSE, otherwise.
1301     *
1302     * @see elm_genlist_clear(), to remove all items in a genlist at
1303     * once.
1304     *
1305     * @ingroup Genlist
1306     */
1307    EAPI void               elm_genlist_item_del(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1308    /**
1309     * Return the data associated to a given genlist item
1310     *
1311     * @param item The genlist item.
1312     * @return the data associated to this item.
1313     *
1314     * This returns the @c data value passed on the
1315     * elm_genlist_item_append() and related item addition calls.
1316     *
1317     * @see elm_genlist_item_append()
1318     * @see elm_genlist_item_data_set()
1319     *
1320     * @ingroup Genlist
1321     */
1322    EAPI void              *elm_genlist_item_data_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1323    /**
1324     * Set the data associated to a given genlist item
1325     *
1326     * @param item The genlist item
1327     * @param data The new data pointer to set on it
1328     *
1329     * This @b overrides the @c data value passed on the
1330     * elm_genlist_item_append() and related item addition calls. This
1331     * function @b won't call elm_genlist_item_update() automatically,
1332     * so you'd issue it afterwards if you want to hove the item
1333     * updated to reflect the that new data.
1334     *
1335     * @see elm_genlist_item_data_get()
1336     *
1337     * @ingroup Genlist
1338     */
1339    EAPI void               elm_genlist_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
1340    /**
1341     * Tells genlist to "orphan" contents fetchs by the item class
1342     *
1343     * @param it The item
1344     *
1345     * This instructs genlist to release references to contents in the item,
1346     * meaning that they will no longer be managed by genlist and are
1347     * floating "orphans" that can be re-used elsewhere if the user wants
1348     * to.
1349     *
1350     * @ingroup Genlist
1351     */
1352    EAPI void               elm_genlist_item_contents_orphan(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1353    /**
1354     * Get the real Evas object created to implement the view of a
1355     * given genlist item
1356     *
1357     * @param item The genlist item.
1358     * @return the Evas object implementing this item's view.
1359     *
1360     * This returns the actual Evas object used to implement the
1361     * specified genlist item's view. This may be @c NULL, as it may
1362     * not have been created or may have been deleted, at any time, by
1363     * the genlist. <b>Do not modify this object</b> (move, resize,
1364     * show, hide, etc.), as the genlist is controlling it. This
1365     * function is for querying, emitting custom signals or hooking
1366     * lower level callbacks for events on that object. Do not delete
1367     * this object under any circumstances.
1368     *
1369     * @see elm_genlist_item_data_get()
1370     *
1371     * @ingroup Genlist
1372     */
1373    EAPI const Evas_Object *elm_genlist_item_object_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1374    /**
1375     * Update the contents of an item
1376     *
1377     * @param it The item
1378     *
1379     * This updates an item by calling all the item class functions again
1380     * to get the contents, texts and states. Use this when the original
1381     * item data has changed and the changes are desired to be reflected.
1382     *
1383     * Use elm_genlist_realized_items_update() to update all already realized
1384     * items.
1385     *
1386     * @see elm_genlist_realized_items_update()
1387     *
1388     * @ingroup Genlist
1389     */
1390    EAPI void               elm_genlist_item_update(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1391    EAPI void               elm_genlist_item_fields_update(Elm_Object_Item *it, const char *parts, Elm_Genlist_Item_Field_Flags itf) EINA_ARG_NONNULL(1);
1392    /**
1393     * Update the item class of an item
1394     *
1395     * @param it The item
1396     * @param itc The item class for the item
1397     *
1398     * This sets another class fo the item, changing the way that it is
1399     * displayed. After changing the item class, elm_genlist_item_update() is
1400     * called on the item @p it.
1401     *
1402     * @ingroup Genlist
1403     */
1404    EAPI void               elm_genlist_item_item_class_update(Elm_Object_Item *it, const Elm_Genlist_Item_Class *itc) EINA_ARG_NONNULL(1, 2);
1405    EAPI const Elm_Genlist_Item_Class *elm_genlist_item_item_class_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1406    /**
1407     * Set the text to be shown in a given genlist item's tooltips.
1408     *
1409     * @param item The genlist item
1410     * @param text The text to set in the content
1411     *
1412     * This call will setup the text to be used as tooltip to that item
1413     * (analogous to elm_object_tooltip_text_set(), but being item
1414     * tooltips with higher precedence than object tooltips). It can
1415     * have only one tooltip at a time, so any previous tooltip data
1416     * will get removed.
1417     *
1418     * In order to set an icon or something else as a tooltip, look at
1419     * elm_genlist_item_tooltip_content_cb_set().
1420     *
1421     * @ingroup Genlist
1422     */
1423    EAPI void               elm_genlist_item_tooltip_text_set(Elm_Object_Item *item, const char *text) EINA_ARG_NONNULL(1);
1424    /**
1425     * Set the content to be shown in a given genlist item's tooltips
1426     *
1427     * @param item The genlist item.
1428     * @param func The function returning the tooltip contents.
1429     * @param data What to provide to @a func as callback data/context.
1430     * @param del_cb Called when data is not needed anymore, either when
1431     *        another callback replaces @p func, the tooltip is unset with
1432     *        elm_genlist_item_tooltip_unset() or the owner @p item
1433     *        dies. This callback receives as its first parameter the
1434     *        given @p data, being @c event_info the item handle.
1435     *
1436     * This call will setup the tooltip's contents to @p item
1437     * (analogous to elm_object_tooltip_content_cb_set(), but being
1438     * item tooltips with higher precedence than object tooltips). It
1439     * can have only one tooltip at a time, so any previous tooltip
1440     * content will get removed. @p func (with @p data) will be called
1441     * every time Elementary needs to show the tooltip and it should
1442     * return a valid Evas object, which will be fully managed by the
1443     * tooltip system, getting deleted when the tooltip is gone.
1444     *
1445     * In order to set just a text as a tooltip, look at
1446     * elm_genlist_item_tooltip_text_set().
1447     *
1448     * @ingroup Genlist
1449     */
1450    EAPI void               elm_genlist_item_tooltip_content_cb_set(Elm_Object_Item *item, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb) EINA_ARG_NONNULL(1);
1451    /**
1452     * Unset a tooltip from a given genlist item
1453     *
1454     * @param item genlist item to remove a previously set tooltip from.
1455     *
1456     * This call removes any tooltip set on @p item. The callback
1457     * provided as @c del_cb to
1458     * elm_genlist_item_tooltip_content_cb_set() will be called to
1459     * notify it is not used anymore (and have resources cleaned, if
1460     * need be).
1461     *
1462     * @see elm_genlist_item_tooltip_content_cb_set()
1463     *
1464     * @ingroup Genlist
1465     */
1466    EAPI void               elm_genlist_item_tooltip_unset(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1467    /**
1468     * Set a different @b style for a given genlist item's tooltip.
1469     *
1470     * @param item genlist item with tooltip set
1471     * @param style the <b>theme style</b> to use on tooltips (e.g. @c
1472     * "default", @c "transparent", etc)
1473     *
1474     * Tooltips can have <b>alternate styles</b> to be displayed on,
1475     * which are defined by the theme set on Elementary. This function
1476     * works analogously as elm_object_tooltip_style_set(), but here
1477     * applied only to genlist item objects. The default style for
1478     * tooltips is @c "default".
1479     *
1480     * @note before you set a style you should define a tooltip with
1481     *       elm_genlist_item_tooltip_content_cb_set() or
1482     *       elm_genlist_item_tooltip_text_set()
1483     *
1484     * @see elm_genlist_item_tooltip_style_get()
1485     *
1486     * @ingroup Genlist
1487     */
1488    EAPI void               elm_genlist_item_tooltip_style_set(Elm_Object_Item *item, const char *style) EINA_ARG_NONNULL(1);
1489    /**
1490     * Get the style set a given genlist item's tooltip.
1491     *
1492     * @param item genlist item with tooltip already set on.
1493     * @return style the theme style in use, which defaults to
1494     *         "default". If the object does not have a tooltip set,
1495     *         then @c NULL is returned.
1496     *
1497     * @see elm_genlist_item_tooltip_style_set() for more details
1498     *
1499     * @ingroup Genlist
1500     */
1501    EAPI const char        *elm_genlist_item_tooltip_style_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1502    /**
1503     * @brief Disable size restrictions on an object's tooltip
1504     * @param item The tooltip's anchor object
1505     * @param disable If EINA_TRUE, size restrictions are disabled
1506     * @return EINA_FALSE on failure, EINA_TRUE on success
1507     *
1508     * This function allows a tooltip to expand beyond its parant window's canvas.
1509     * It will instead be limited only by the size of the display.
1510     */
1511    EAPI Eina_Bool          elm_genlist_item_tooltip_size_restrict_disable(Elm_Object_Item *item, Eina_Bool disable);
1512    /**
1513     * @brief Retrieve size restriction state of an object's tooltip
1514     * @param item The tooltip's anchor object
1515     * @return If EINA_TRUE, size restrictions are disabled
1516     *
1517     * This function returns whether a tooltip is allowed to expand beyond
1518     * its parant window's canvas.
1519     * It will instead be limited only by the size of the display.
1520     */
1521    EAPI Eina_Bool          elm_genlist_item_tooltip_size_restrict_disabled_get(const Elm_Object_Item *item);
1522    /**
1523     * Set the type of mouse pointer/cursor decoration to be shown,
1524     * when the mouse pointer is over the given genlist widget item
1525     *
1526     * @param item genlist item to customize cursor on
1527     * @param cursor the cursor type's name
1528     *
1529     * This function works analogously as elm_object_cursor_set(), but
1530     * here the cursor's changing area is restricted to the item's
1531     * area, and not the whole widget's. Note that that item cursors
1532     * have precedence over widget cursors, so that a mouse over @p
1533     * item will always show cursor @p type.
1534     *
1535     * If this function is called twice for an object, a previously set
1536     * cursor will be unset on the second call.
1537     *
1538     * @see elm_object_cursor_set()
1539     * @see elm_genlist_item_cursor_get()
1540     * @see elm_genlist_item_cursor_unset()
1541     *
1542     * @ingroup Genlist
1543     */
1544    EAPI void               elm_genlist_item_cursor_set(Elm_Object_Item *item, const char *cursor) EINA_ARG_NONNULL(1);
1545    /**
1546     * Get the type of mouse pointer/cursor decoration set to be shown,
1547     * when the mouse pointer is over the given genlist widget item
1548     *
1549     * @param item genlist item with custom cursor set
1550     * @return the cursor type's name or @c NULL, if no custom cursors
1551     * were set to @p item (and on errors)
1552     *
1553     * @see elm_object_cursor_get()
1554     * @see elm_genlist_item_cursor_set() for more details
1555     * @see elm_genlist_item_cursor_unset()
1556     *
1557     * @ingroup Genlist
1558     */
1559    EAPI const char        *elm_genlist_item_cursor_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1560    /**
1561     * Unset any custom mouse pointer/cursor decoration set to be
1562     * shown, when the mouse pointer is over the given genlist widget
1563     * item, thus making it show the @b default cursor again.
1564     *
1565     * @param item a genlist item
1566     *
1567     * Use this call to undo any custom settings on this item's cursor
1568     * decoration, bringing it back to defaults (no custom style set).
1569     *
1570     * @see elm_object_cursor_unset()
1571     * @see elm_genlist_item_cursor_set() for more details
1572     *
1573     * @ingroup Genlist
1574     */
1575    EAPI void               elm_genlist_item_cursor_unset(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1576    /**
1577     * Set a different @b style for a given custom cursor set for a
1578     * genlist item.
1579     *
1580     * @param item genlist item with custom cursor set
1581     * @param style the <b>theme style</b> to use (e.g. @c "default",
1582     * @c "transparent", etc)
1583     *
1584     * This function only makes sense when one is using custom mouse
1585     * cursor decorations <b>defined in a theme file</b> , which can
1586     * have, given a cursor name/type, <b>alternate styles</b> on
1587     * it. It works analogously as elm_object_cursor_style_set(), but
1588     * here applied only to genlist item objects.
1589     *
1590     * @warning Before you set a cursor style you should have defined a
1591     *       custom cursor previously on the item, with
1592     *       elm_genlist_item_cursor_set()
1593     *
1594     * @see elm_genlist_item_cursor_engine_only_set()
1595     * @see elm_genlist_item_cursor_style_get()
1596     *
1597     * @ingroup Genlist
1598     */
1599    EAPI void               elm_genlist_item_cursor_style_set(Elm_Object_Item *item, const char *style) EINA_ARG_NONNULL(1);
1600    /**
1601     * Get the current @b style set for a given genlist item's custom
1602     * cursor
1603     *
1604     * @param item genlist item with custom cursor set.
1605     * @return style the cursor style in use. If the object does not
1606     *         have a cursor set, then @c NULL is returned.
1607     *
1608     * @see elm_genlist_item_cursor_style_set() for more details
1609     *
1610     * @ingroup Genlist
1611     */
1612    EAPI const char        *elm_genlist_item_cursor_style_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1613    /**
1614     * Set if the (custom) cursor for a given genlist item should be
1615     * searched in its theme, also, or should only rely on the
1616     * rendering engine.
1617     *
1618     * @param item item with custom (custom) cursor already set on
1619     * @param engine_only Use @c EINA_TRUE to have cursors looked for
1620     * only on those provided by the rendering engine, @c EINA_FALSE to
1621     * have them searched on the widget's theme, as well.
1622     *
1623     * @note This call is of use only if you've set a custom cursor
1624     * for genlist items, with elm_genlist_item_cursor_set().
1625     *
1626     * @note By default, cursors will only be looked for between those
1627     * provided by the rendering engine.
1628     *
1629     * @ingroup Genlist
1630     */
1631    EAPI void               elm_genlist_item_cursor_engine_only_set(Elm_Object_Item *item, Eina_Bool engine_only) EINA_ARG_NONNULL(1);
1632    /**
1633     * Get if the (custom) cursor for a given genlist item is being
1634     * searched in its theme, also, or is only relying on the rendering
1635     * engine.
1636     *
1637     * @param item a genlist item
1638     * @return @c EINA_TRUE, if cursors are being looked for only on
1639     * those provided by the rendering engine, @c EINA_FALSE if they
1640     * are being searched on the widget's theme, as well.
1641     *
1642     * @see elm_genlist_item_cursor_engine_only_set(), for more details
1643     *
1644     * @ingroup Genlist
1645     */
1646    EAPI Eina_Bool          elm_genlist_item_cursor_engine_only_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1647    /**
1648     * Update the contents of all realized items.
1649     *
1650     * @param obj The genlist object.
1651     *
1652     * This updates all realized items by calling all the item class functions again
1653     * to get the contents, texts and states. Use this when the original
1654     * item data has changed and the changes are desired to be reflected.
1655     *
1656     * To update just one item, use elm_genlist_item_update().
1657     *
1658     * @see elm_genlist_realized_items_get()
1659     * @see elm_genlist_item_update()
1660     *
1661     * @ingroup Genlist
1662     */
1663    EAPI void               elm_genlist_realized_items_update(Evas_Object *obj) EINA_ARG_NONNULL(1);
1664    /**
1665     * Activate a genlist mode on an item
1666     *
1667     * @param item The genlist item
1668     * @param mode Mode name
1669     * @param mode_set Boolean to define set or unset mode.
1670     *
1671     * A genlist mode is a different way of selecting an item. Once a mode is
1672     * activated on an item, any other selected item is immediately unselected.
1673     * This feature provides an easy way of implementing a new kind of animation
1674     * for selecting an item, without having to entirely rewrite the item style
1675     * theme. However, the elm_genlist_selected_* API can't be used to get what
1676     * item is activate for a mode.
1677     *
1678     * The current item style will still be used, but applying a genlist mode to
1679     * an item will select it using a different kind of animation.
1680     *
1681     * The current active item for a mode can be found by
1682     * elm_genlist_mode_item_get().
1683     *
1684     * The characteristics of genlist mode are:
1685     * - Only one mode can be active at any time, and for only one item.
1686     * - Genlist handles deactivating other items when one item is activated.
1687     * - A mode is defined in the genlist theme (edc), and more modes can easily
1688     *   be added.
1689     * - A mode style and the genlist item style are different things. They
1690     *   can be combined to provide a default style to the item, with some kind
1691     *   of animation for that item when the mode is activated.
1692     *
1693     * When a mode is activated on an item, a new view for that item is created.
1694     * The theme of this mode defines the animation that will be used to transit
1695     * the item from the old view to the new view. This second (new) view will be
1696     * active for that item while the mode is active on the item, and will be
1697     * destroyed after the mode is totally deactivated from that item.
1698     *
1699     * @see elm_genlist_mode_get()
1700     * @see elm_genlist_mode_item_get()
1701     *
1702     * @ingroup Genlist
1703     */
1704    EAPI void               elm_genlist_item_mode_set(Elm_Object_Item *it, const char *mode_type, Eina_Bool mode_set) EINA_ARG_NONNULL(1, 2);
1705    /**
1706     * Get the last (or current) genlist mode used.
1707     *
1708     * @param obj The genlist object
1709     *
1710     * This function just returns the name of the last used genlist mode. It will
1711     * be the current mode if it's still active.
1712     *
1713     * @see elm_genlist_item_mode_set()
1714     * @see elm_genlist_mode_item_get()
1715     *
1716     * @ingroup Genlist
1717     */
1718    EAPI const char        *elm_genlist_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1719    /**
1720     * Get active genlist mode item
1721     *
1722     * @param obj The genlist object
1723     * @return The active item for that current mode. Or @c NULL if no item is
1724     * activated with any mode.
1725     *
1726     * This function returns the item that was activated with a mode, by the
1727     * function elm_genlist_item_mode_set().
1728     *
1729     * @see elm_genlist_item_mode_set()
1730     * @see elm_genlist_mode_get()
1731     *
1732     * @ingroup Genlist
1733     */
1734    EAPI const Elm_Object_Item *elm_genlist_mode_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1735
1736    /**
1737     * Set reorder mode
1738     *
1739     * @param obj The genlist object
1740     * @param reorder_mode The reorder mode
1741     * (EINA_TRUE = on, EINA_FALSE = off)
1742     *
1743     * @ingroup Genlist
1744     */
1745    EAPI void               elm_genlist_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode) EINA_ARG_NONNULL(1);
1746
1747    /**
1748     * Get the reorder mode
1749     *
1750     * @param obj The genlist object
1751     * @return The reorder mode
1752     * (EINA_TRUE = on, EINA_FALSE = off)
1753     *
1754     * @ingroup Genlist
1755     */
1756    EAPI Eina_Bool          elm_genlist_reorder_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1757
1758    EAPI void               elm_genlist_edit_mode_set(Evas_Object *obj, Eina_Bool edit_mode) EINA_ARG_NONNULL(1);
1759    EAPI Eina_Bool          elm_genlist_edit_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1760    EAPI void               elm_genlist_item_rename_mode_set(Elm_Object_Item *it, Eina_Bool renamed) EINA_ARG_NONNULL(1);
1761    EAPI Eina_Bool          elm_genlist_item_rename_mode_get(Elm_Object_Item *item) EINA_ARG_NONNULL(1);
1762    EAPI void               elm_genlist_item_move_after(Elm_Object_Item *it, Elm_Object_Item *after ) EINA_ARG_NONNULL(1, 2);
1763    EAPI void               elm_genlist_item_move_before(Elm_Object_Item *it, Elm_Object_Item *before) EINA_ARG_NONNULL(1, 2);
1764    EAPI void               elm_genlist_effect_set(const Evas_Object *obj, Eina_Bool emode) EINA_ARG_NONNULL(1);
1765    EAPI void               elm_genlist_pinch_zoom_set(Evas_Object *obj, Eina_Bool emode) EINA_ARG_NONNULL(1);
1766    EAPI void               elm_genlist_pinch_zoom_mode_set(Evas_Object *obj, Eina_Bool emode) EINA_ARG_NONNULL(1);
1767    EAPI Eina_Bool          elm_genlist_pinch_zoom_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1768
1769    EAPI void               elm_genlist_item_no_select_mode_set(Elm_Object_Item *it, Eina_Bool no_select) EINA_ARG_NONNULL(1);
1770    EAPI Eina_Bool          elm_genlist_item_no_select_mode_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
1771
1772    /**
1773     * @}
1774     */