src/lib/elm_genlist.h

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