diff options
Diffstat (limited to 'src/lib/elm_genlist.h')
| -rw-r--r-- | src/lib/elm_genlist.h | 2042 |
1 files changed, 1835 insertions, 207 deletions
diff --git a/src/lib/elm_genlist.h b/src/lib/elm_genlist.h index c95d472f2..ece8752e7 100644 --- a/src/lib/elm_genlist.h +++ b/src/lib/elm_genlist.h @@ -1,37 +1,37 @@ /** - * @defgroup Genlist Genlist (Generic list) - * @ingroup Elementary + * @defgroup Genlist Genlist + * @ingroup elm_widget_group * * @image html genlist_inheritance_tree.png * @image latex genlist_inheritance_tree.eps * - * @image html img/widget/genlist/preview-00.png - * @image latex img/widget/genlist/preview-00.eps * @image html img/genlist.png * @image latex img/genlist.eps * - * This widget aims to have more expansive list than the simple list in - * Elementary that could have more flexible items and allow many more entries - * while still being fast and low on memory usage. At the same time it was - * also made to be able to do tree structures. But the price to pay is more - * complexity when it comes to usage. If all you want is a simple list with - * icons and a single text, use the normal @ref List object. + * @brief This widget aims to have a more expansive list than the simple list + * in Elementary that could have more flexible items and allow many more + * entries while still being fast and low on memory usage. + * + * At the same time it was also made to be able to do tree structures. But the + * price to pay is based on complexity when it comes to usage. If all you want + * is a simple list with icons and a single text, use the normal @ref List + * object. * * Genlist has a fairly large API, mostly because it's relatively complex, - * trying to be both expansive, powerful and efficient. First we will begin + * trying to be expansive, powerful, and efficient. First we begin with * an overview on the theory behind genlist. * * This widget inherits from the @ref Layout one, so that all the * functions acting on it also work for genlist objects. * - * This widget implements the @b @ref elm-scrollable-interface + * This widget implements the elm-scrollable-interface * interface, so that all (non-deprecated) functions for the base @ref * Scroller widget also work for genlists. * * Some calls on the genlist's API are marked as @b deprecated, as * they just wrap the scrollable widgets counterpart functions. Use - * the ones we point you to, for each case of deprecation here, - * instead -- eventually the deprecated ones will be discarded (next + * the ones mentioned for each case of deprecation here. + * Eventually the deprecated ones are discarded (next * major release). * * @section Genlist_Item_Class Genlist item classes - creating items @@ -39,103 +39,79 @@ * In order to have the ability to add and delete items on the fly, genlist * implements a class (callback) system where the application provides a * structure with information about that type of item (genlist may contain - * multiple different items with different classes, states and styles). - * Genlist will call the functions in this struct (methods) when an item is + * multiple items of different types with different classes, states, and styles). + * Genlist calls the functions in this struct (methods) when an item is * "realized" (i.e., created dynamically, while the user is scrolling the - * list). All objects will simply be deleted when no longer needed with + * list). All objects are simply deleted when they are no longer needed by * evas_object_del(). The #Elm_Genlist_Item_Class structure contains the * following members: * - @c item_style - This is a constant string and simply defines the name * of the item style. It @b must be specified and the default should be @c * "default". * - @c decorate_item_style - This is a constant string and simply defines the name - * of the decorate mode item style. It is used to specify decorate mode item style. It can be - * used when you call elm_genlist_item_decorate_mode_set(). + * of the decorate mode item style. It is used to specify the decorate mode item style. It can be + * used when elm_genlist_item_decorate_mode_set() is called. * - @c decorate_all_item_style - This is a constant string and simply defines the name - * of the decorate all item style. It is used to specify decorate all item style. It can be - * used to set selection, checking and deletion mode. This is used when you - * call elm_genlist_decorate_mode_set(). - * - @c func - A struct with pointers to functions that will be called when - * an item is going to be actually created. All of them receive a @c data - * parameter that will point to the same data passed to - * elm_genlist_item_append() and related item creation functions, and an @c + * of the decorate all item style. It is used to specify the decorate all item style. It can be + * used to set the selection, checking, and deletion mode. This is used when + * elm_genlist_decorate_mode_set() is called. + * - @c func - This is a struct with pointers to functions that are called when + * an item is going to actually be created. All of them receive a @c data + * parameter that points to the same data that is passed to + * elm_genlist_item_append() and other related item creation functions, and an @c * obj parameter that points to the genlist object itself. * * The function pointers inside @c func are @c text_get, @c content_get, @c - * state_get and @c del. The 3 first functions also receive a @c part - * parameter described below. A brief description of these functions follows: + * state_get, and @c del. The first three functions also receive a @c part + * parameter described below. A brief description of these functions is as follows: * * - @c text_get - The @c part parameter is the name string of one of the * existing text parts in the Edje group implementing the item's theme. - * This function @b must return a strdup'()ed string, as the caller will + * This function @b must return a strdup'()ed string, as the caller is going to * free() it when done. See #Elm_Genlist_Item_Text_Get_Cb. * - @c content_get - The @c part parameter is the name string of one of the * existing (content) swallow parts in the Edje group implementing the item's * theme. It must return @c NULL, when no content is desired, or a valid - * object handle, otherwise. The object will be deleted by the genlist on + * object handle, otherwise. The object is deleted by the genlist on * its deletion or when the item is "unrealized". * See #Elm_Genlist_Item_Content_Get_Cb. * - @c func.state_get - The @c part parameter is the name string of one of - * the state parts in the Edje group implementing the item's theme. Return - * @c EINA_FALSE for false/off or @c EINA_TRUE for true/on. Genlists will + * the state parts in the Edje group implementing the item's theme. It must return + * @c EINA_FALSE for false/off or @c EINA_TRUE for true/on. Genlists * emit a signal to its theming Edje object with @c "elm,state,xxx,active" * and @c "elm" as "emission" and "source" arguments, respectively, when - * the state is true (the default is false), where @c xxx is the name of + * the state is @c true (the default is false), where @c xxx is the name of * the (state) part. See #Elm_Genlist_Item_State_Get_Cb. * - @c func.del - This is intended for use when genlist items are deleted, * so any data attached to the item (e.g. its data parameter on creation) * can be deleted. See #Elm_Genlist_Item_Del_Cb. * - * available item styles: + * The available item styles are as follows: * - default * - default_style - The text part is a textblock - * - * @image html img/widget/genlist/preview-04.png - * @image latex img/widget/genlist/preview-04.eps - * * - double_label - * - * @image html img/widget/genlist/preview-01.png - * @image latex img/widget/genlist/preview-01.eps - * * - icon_top_text_bottom - * - * @image html img/widget/genlist/preview-02.png - * @image latex img/widget/genlist/preview-02.eps - * * - group_index - * - * @image html img/widget/genlist/preview-03.png - * @image latex img/widget/genlist/preview-03.eps - * - * - one_icon - Only 1 icon (left) (since 1.7) - * - end_icon - Only 1 icon (at end/right) (since 1.7) - * - no_icon - No icon (at end/right) (since 1.7) - * - full - Only 1 icon, elm.swallow.content, which consumes whole area of - * genlist itemj (since 1.7) - * - * If one wants to use more icons and texts than are offered in theme, there - * are two solutions. One is to use 'full' style that has one big swallow part. - * You can swallow anything there. The other solution is to customize genlist - * item style in application side by using elm_theme_extension_add() and its - * own edc. Please refer @ref theme_example_01 for that. + * - one_icon - Only 1 icon (left) @since 1.7 + * - end_icon - Only 1 icon (at end/right) @since 1.7 + * - no_icon - No icon (at end/right) @since 1.7 * * @section Genlist_Items Structure of items * - * An item in a genlist can have 0 or more texts (they can be regular - * text or textblock Evas objects - that's up to the style to determine), 0 - * or more contents (which are simply objects swallowed into the genlist item's - * theming Edje object) and 0 or more <b>boolean states</b>, which have the + * An item in a genlist can have @c 0 or more texts (they can be regular + * text or textblock Evas objects - that's up to the style to determine), @c 0 + * or more blocks of content (which are simply objects swallowed into the genlist item's + * theming Edje object) and @c 0 or more <b>boolean states</b>, which have the * behavior left to the user to define. The Edje part names for each of - * these properties will be looked up, in the theme file for the genlist, - * under the Edje (string) data items named @c "labels", @c "contents" and @c - * "states", respectively. For each of those properties, if more than one - * part is provided, they must have names listed separated by spaces in the + * these properties are looked up, in the theme file for the genlist, + * under the Edje (string) data items named @c "labels", @c "contents", and @c + * "states", respectively. For each of these properties, if more than one + * part is provided, they must have names listed and separated by spaces in the * data fields. For the default genlist item theme, we have @b one text * part (@c "elm.text"), @b two content parts (@c "elm.swalllow.icon" and @c * "elm.swallow.end") and @b no state parts. * - * A genlist item may be at one of several styles. Elementary provides one + * A genlist item may be having one of the several styles. Elementary provides one * by default - "default", but this can be extended by system or application * custom themes/overlays/extensions (see @ref Theme "themes" for more * details). @@ -144,123 +120,123 @@ * * Items can be added by several calls. All of them return a @ref * Elm_Object_Item handle that is an internal member inside the genlist. - * They all take a data parameter that is meant to be used for a handle to - * the applications internal data (eg. the struct with the original item + * They all take a data parameter that is meant to be used as a handle for + * the application's internal data (eg. the struct with the original item * data). The parent parameter is the parent genlist item this belongs to if - * it is a tree or an indexed group, and NULL if there is no parent. The - * flags can be a bitmask of #ELM_GENLIST_ITEM_NONE, #ELM_GENLIST_ITEM_TREE + * it is a tree or an indexed group, and this value is @c NULL if there is no parent. The + * flags can be a bitmask of #ELM_GENLIST_ITEM_NONE, #ELM_GENLIST_ITEM_TREE, * and #ELM_GENLIST_ITEM_GROUP. If #ELM_GENLIST_ITEM_TREE is set then this * item is displayed as an item that is able to expand and have child items. - * If #ELM_GENLIST_ITEM_GROUP is set then this item is group index item that - * is displayed at the top until the next group comes. The func parameter is + * If #ELM_GENLIST_ITEM_GROUP is set then this item is a group index item that + * is displayed at the top until the next group comes. The @a func parameter is * a convenience callback that is called when the item is selected and the - * data parameter will be the func_data parameter, @c obj be the genlist - * object and event_info will be the genlist item. + * @a data parameter is the @a func_data parameter, @a obj is the genlist + * object, and @a event_info is the genlist item. * * elm_genlist_item_append() adds an item to the end of the list, or if - * there is a parent, to the end of all the child items of the parent. - * elm_genlist_item_prepend() is the same but adds to the beginning of + * there is a parent, it adds the item to the end of all the child items of the parent. + * elm_genlist_item_prepend() is the same but adds an item to the beginning of * the list or children list. elm_genlist_item_insert_before() inserts at - * item before another item and elm_genlist_item_insert_after() inserts after + * item before another item and elm_genlist_item_insert_after() inserts an item after * the indicated item. * * The application can clear the list with elm_genlist_clear() which deletes - * all the items in the list and elm_object_item_del() will delete a specific - * item. elm_genlist_item_subitems_clear() will clear all items that are + * all the items in the list. elm_object_item_del() deletes a specific + * item. elm_genlist_item_subitems_clear() clears all items that are * children of the indicated parent item. * * To help inspect list items you can jump to the item at the top of the list - * with elm_genlist_first_item_get() which will return the item pointer, and - * similarly elm_genlist_last_item_get() gets the item at the end of the list. + * with elm_genlist_first_item_get() which returns the item pointer. Similarly, + * elm_genlist_last_item_get() gets the item at the end of the list. * elm_genlist_item_next_get() and elm_genlist_item_prev_get() get the next * and previous items respectively relative to the indicated item. Using - * these calls you can walk the entire item list/tree. Note that as a tree - * the items are flattened in the list, so elm_genlist_item_parent_get() will - * let you know which item is the parent (and thus know how to skip them if - * wanted). + * these calls you can walk through the entire item list/tree. Note that as a tree + * the items are flattened in the list, so elm_genlist_item_parent_get() + * lets you know which item is the parent (and thus helps you skip them if + * needed). * * @section Genlist_Multi_Selection Multi-selection * - * If the application wants multiple items to be able to be selected, + * If the application wants to allow multiple items to be selected, * elm_genlist_multi_select_set() can enable this. If the list is * single-selection only (the default), then elm_genlist_selected_item_get() - * will return the selected item, if any, or NULL if none is selected. If the - * list is multi-select then elm_genlist_selected_items_get() will return a + * returns the selected item, if any, or @c NULL if none is selected. If the + * list is multi-select then elm_genlist_selected_items_get() returns a * list (that is only valid as long as no items are modified (added, deleted, - * selected or unselected)). + * selected, or unselected)). * * @section Genlist_Usage_Hints Usage hints * - * There are also convenience functions. elm_object_item_widget_get() will - * return the genlist object the item belongs to. elm_genlist_item_show() - * will make the scroller scroll to show that specific item so its visible. + * There are also convenience functions. elm_object_item_widget_get() + * returns the genlist object the item belongs to. elm_genlist_item_show() + * makes the scroller scroll to show that specific item so that it is visible. * elm_object_item_data_get() returns the data pointer set by the item * creation functions. * - * If an item changes (state of boolean changes, text or contents change), + * If an item changes (state of boolean changes, text or content changes), * then use elm_genlist_item_update() to have genlist update the item with - * the new state. Genlist will re-realize the item and thus call the functions + * the new state. Genlist re-realizes the item and thus calls the functions * in the _Elm_Genlist_Item_Class for that item. * * To programmatically (un)select an item use elm_genlist_item_selected_set(). - * To get its selected state use elm_genlist_item_selected_get(). Similarly + * To get its selected state use elm_genlist_item_selected_get(). Similarly, * to expand/contract an item and get its expanded state, use * elm_genlist_item_expanded_set() and elm_genlist_item_expanded_get(). And - * again to make an item disabled (unable to be selected and appear + * again to disable an item (unable to be selected and appear * differently) use elm_object_item_disabled_set() to set this and * elm_object_item_disabled_get() to get the disabled state. * - * In general to indicate how the genlist should expand items horizontally to + * In general, to indicate how the genlist should expand items horizontally to * fill the list area, use elm_genlist_mode_set(). Valid modes are - * ELM_LIST_LIMIT, ELM_LIST_COMPRESS and ELM_LIST_SCROLL. The default is + * ELM_LIST_LIMIT, ELM_LIST_COMPRESS, and ELM_LIST_SCROLL. The default is * ELM_LIST_SCROLL. This mode means that if items are too wide to fit, the - * scroller will scroll horizontally. Otherwise items are expanded to + * scroller scrolls horizontally. Otherwise items are expanded to * fill the width of the viewport of the scroller. If it is - * ELM_LIST_LIMIT, items will be expanded to the viewport width - * if larger than the item, but genlist widget witdh is - * limited to the largest item. Do not use ELM_LIST_LIMIT mode with homogenous + * ELM_LIST_LIMIT, items are expanded to the viewport width + * if the viewport width is larger than the item, but the genlist widget width is + * limited to the largest item. Do not use the ELM_LIST_LIMIT mode with the homogenous * mode turned on. ELM_LIST_COMPRESS can be combined with a different style - * that uses edjes' ellipsis feature (cutting text off like this: "tex..."). + * that uses the edjes' ellipsis feature (cutting text off like this: "tex..."). * - * Items will call their selection func and callback only once when first becoming - * selected. Any further clicks will do nothing, unless you enable always + * Items call their selection func and callback only once when selected for the + * first time. Any further clicks do nothing, unless you enable always * select with elm_genlist_select_mode_set() as ELM_OBJECT_SELECT_MODE_ALWAYS. - * This means even if selected, every click will make the selected callbacks - * be called. elm_genlist_select_mode_set() as ELM_OBJECT_SELECT_MODE_NONE will - * turn off the ability to select items entirely and they will neither + * This means even if selected, every click make the selected callbacks + * to be called. elm_genlist_select_mode_set() as ELM_OBJECT_SELECT_MODE_NONE + * turns off the ability to select items entirely and they neither * appear selected nor call selected callback functions. * * Remember that you can create new styles and add your own theme augmentation - * per application with elm_theme_extension_add(). If you absolutely must - * have a specific style that overrides any theme the user or system sets up + * for each application with elm_theme_extension_add(). If you absolutely must + * have a specific style that overrides any theme that the user or system sets up, * you can use elm_theme_overlay_add() to add such a file. * * @section Genlist_Implementation Implementation * * Evas tracks every object you create. Every time it processes an event * (mouse move, down, up etc.) it needs to walk through objects and find out - * what event that affects. Even worse every time it renders display updates, - * in order to just calculate what to re-draw, it needs to walk through many - * many many objects. Thus, the more objects you keep active, the more + * what event they affect. Further, every time it renders display updates, + * in order to just calculate what to re-draw, it needs to walk through a large + * number of objects. Thus, the more objects you keep active, the more * overhead Evas has in just doing its work. It is advisable to keep your * active objects to the minimum working set you need. Also remember that * object creation and deletion carries an overhead, so there is a * middle-ground, which is not easily determined. But don't keep massive lists * of objects you can't see or use. Genlist does this with list objects. It * creates and destroys them dynamically as you scroll around. It groups them - * into blocks so it can determine the visibility etc. of a whole block at - * once as opposed to having to walk the whole list. This 2-level list allows - * for very large numbers of items to be in the list (tests have used up to + * into blocks so that it can determine the visibility of a whole block at + * once as opposed to having to walk through the whole list. This 2-level list allows + * for very large numbers of items to be in the list (tests have used upto * 2,000,000 items). Also genlist employs a queue for adding items. As items - * may be different sizes, every item added needs to be calculated as to its + * maybe of different sizes, every added item needs to be calculated as per its * size and thus this presents a lot of overhead on populating the list, this - * genlist employs a queue. Any item added is queued and spooled off over - * time, actually appearing some time later, so if your list has many members - * you may find it takes a while for them to all appear, with your process - * consuming a lot of CPU while it is busy spooling. + * genlist employs a queue. Every added item is queued and spooled off over + * time, though it appears some time later. So if your list has many members, + * you may find that it takes a while for them to appear and this process + * consumes a lot of CPU time while it is busy spooling. * * Genlist also implements a tree structure for items, but it does so with - * callbacks to the application, with the application filling in tree + * callbacks to the application, with the application filling in tree * structures when requested (allowing for efficient building of a very * deep tree that could even be used for file-management). * See the above smart signal callbacks for details. @@ -268,45 +244,45 @@ * @section Genlist_Smart_Events Genlist smart events * * This widget emits the following signals, besides the ones sent from - * @ref Layout: + * @ref Layout : * - @c "activated" - The user has double-clicked or pressed - * (enter|return|spacebar) on an item. The @p event_info parameter is the - * item that was activated. - * - @c "pressed" - The user pressed the an item. The @p event_info - * parameter is the item that was pressed. - * - @c "released" - The user released the an item. The @p event_info - * parameter is the item that was released. - * - @c "clicked,double" - The user has double-clicked an item. The @c - * event_info parameter is the item that was double-clicked. - * - @c "selected" - This is called when a user has made an item selected. - * The event_info parameter is the genlist item that was selected. - * - @c "unselected" - This is called when a user has made an item - * unselected. The event_info parameter is the genlist item that was + * (enter|return|spacebar) on an item. The @a event_info parameter is the + * item that is activated. + * - @c "pressed" - The user pressed an item. The @a event_info + * parameter is the item that is pressed. + * - @c "released" - The user released an item. The @a event_info + * parameter is the item that is released. + * - @c "clicked,double" - The user has double-clicked an item. The @a + * event_info parameter is the item that is double-clicked. + * - @c "selected" - This is called when a user has selected an item. + * The @a event_info parameter is the genlist item that is selected. + * - @c "unselected" - This is called when a user has unselected an item. + * The @a event_info parameter is the genlist item that is * unselected. * - @c "expanded" - This is called when elm_genlist_item_expanded_set() is - * called and the item is now meant to be expanded. The event_info - * parameter is the genlist item that was indicated to expand. It is the + * called and the item is now meant to be expanded. The @a event_info + * parameter is the genlist item that is indicated to expand. It is the * job of this callback to then fill in the child items. * - @c "contracted" - This is called when elm_genlist_item_expanded_set() is - * called and the item is now meant to be contracted. The event_info - * parameter is the genlist item that was indicated to contract. It is the + * called and the item is now meant to contract. The @a event_info + * parameter is the genlist item that is indicated to contract. It is the * job of this callback to then delete the child items. - * - @c "expand,request" - This is called when a user has indicated they want + * - @c "expand,request" - This is called when a user has indicated that they want * to expand a tree branch item. The callback should decide if the item can * expand (has any children) and then call elm_genlist_item_expanded_set() - * appropriately to set the state. The event_info parameter is the genlist - * item that was indicated to expand. - * - @c "contract,request" - This is called when a user has indicated they + * appropriately to set the state. The @a event_info parameter is the genlist + * item that is indicated to expand. + * - @c "contract,request" - This is called when a user has indicated that they * want to contract a tree branch item. The callback should decide if the * item can contract (has any children) and then call * elm_genlist_item_expanded_set() appropriately to set the state. The - * event_info parameter is the genlist item that was indicated to contract. + * event_info parameter is the genlist item that is indicated to contract. * - @c "realized" - This is called when the item in the list is created as a - * real evas object. event_info parameter is the genlist item that was + * real evas object. @a event_info parameter is the genlist item that is * created. * - @c "unrealized" - This is called just before an item is unrealized. - * After this call content objects provided will be deleted and the item - * object itself delete or be put into a floating cache. + * After this call, the provided content objects are deleted and the item + * object itself is deleted or is put into a floating cache. * - @c "drag,start,up" - This is called when the item in the list has been * dragged (not scrolled) up. * - @c "drag,start,down" - This is called when the item in the list has been @@ -315,11 +291,11 @@ * dragged (not scrolled) left. * - @c "drag,start,right" - This is called when the item in the list has * been dragged (not scrolled) right. - * - @c "drag,stop" - This is called when the item in the list has stopped + * - @c "drag,stop" - This is called when the item in the list is stopped * being dragged. * - @c "drag" - This is called when the item in the list is being dragged. * - @c "longpressed" - This is called when the item is pressed for a certain - * amount of time. By default it's 1 second. The event_info parameter is the + * amount of time. By default it's @c 1 second. The @a event_info parameter is the * longpressed genlist item. * - @c "scroll,anim,start" - This is called when scrolling animation has * started. @@ -350,76 +326,1728 @@ * - @c "multi,pinch,in" - This is called when the genlist is multi-touch * pinched in. * - @c "swipe" - This is called when the genlist is swiped. - * - @c "moved" - This is called when a genlist item is moved by a user - * interaction in a reorder mode. The @p event_info parameter is the item that - * was moved. + * - @c "moved" - This is called when a genlist item is moved in the reorder mode. * - @c "moved,after" - This is called when a genlist item is moved after - * another item in reorder mode. The event_info parameter is the reordered + * another item in the reorder mode. The @a event_info parameter is the reordered * item. To get the relative previous item, use elm_genlist_item_prev_get(). - * This signal is called along with "moved" signal. + * This signal is called along with the "moved" signal. * - @c "moved,before" - This is called when a genlist item is moved before - * another item in reorder mode. The event_info parameter is the reordered + * another item in the reorder mode. The @a event_info parameter is the reordered * item. To get the relative previous item, use elm_genlist_item_next_get(). - * This signal is called along with "moved" signal. - * - @c "index,update" - This is called when a genlist item index is changed. - * Note that this callback is called while each item is being realized. + * This signal is called along with the "moved" signal. * - @c "language,changed" - This is called when the program's language is - * changed. Call the elm_genlist_realized_items_update() if items text should + * changed. Call elm_genlist_realized_items_update() if the item's text should * be translated. - * - @c "tree,effect,finished" - This is called when a genlist tree effect is finished. - * - @c "highlighted" - an item in the list is highlighted. This is called when - * the user presses an item or keyboard selection is done so the item is - * physically highlighted. The @p event_info parameter is the item that was - * highlighted. - * - @c "unhighlighted" - an item in the list is unhighlighted. This is called - * when the user releases an item or keyboard selection is moved so the item - * is physically unhighlighted. The @p event_info parameter is the item that - * was unhighlighted. - * - @c "focused" - When the genlist has received focus. (since 1.8) - * - @c "unfocused" - When the genlist has lost focus. (since 1.8) - * - @c "item,focused" - When the genlist item has recieved focus. (since 1.10) - * - @c "item,unfocused" - When the genlist item has lost focus. (since 1.10) - * - * - * Supported elm_object_item common APIs - * @li @ref elm_object_item_part_content_get - * @li @ref elm_object_item_part_text_get - * @li @ref elm_object_item_disabled_set - * @li @ref elm_object_item_disabled_get - * @li @ref elm_object_item_signal_emit - * - * Unsupported elm_object_item common APIs due to the genlist concept. + * - @c "tree,effect,finished" - This is called when the genlist tree effect is finished. + * - @c "highlighted" - This is called when an item in the list is pressed and highlighted. + * The @a event_info parameter is the item that is highlighted. + * - @c "unhighlighted" - This is called when an item in the list is unpressed and unhighlighted. + * The @a event_info parameter is the item that is unhighlighted. + * + * + * Supported common elm_object_item APIs. + * @li @ref elm_object_item_part_content_get() + * @li @ref elm_object_item_part_text_get() + * @li @ref elm_object_item_disabled_set() + * @li @ref elm_object_item_disabled_get() + * @li @ref elm_object_item_signal_emit() + * + * Unsupported common elm_object_item APIs as per the genlist concept. * Genlist fills content/text according to the appropriate callback functions. - * Please use elm_genlist_item_update() or elm_genlist_item_fields_update() + * Use elm_genlist_item_update() or elm_genlist_item_fields_update() * instead. - * @li @ref elm_object_item_part_content_set - * @li @ref elm_object_item_part_content_unset - * @li @ref elm_object_item_part_text_set + * @li @ref elm_object_item_part_content_set() + * @li @ref elm_object_item_part_content_unset() + * @li @ref elm_object_item_part_text_set() * - * @section Genlist_Examples Examples + * @{ + */ + +#define ELM_GENLIST_ITEM_CLASS_VERSION ELM_GEN_ITEM_CLASS_VERSION +#define ELM_GENLIST_ITEM_CLASS_HEADER ELM_GEN_ITEM_CLASS_HEADER + +/** + * @brief Enumeration that defines whether the item is of a special type (has subitems or it's the + * index of a group), or it is just a simple item. + */ +typedef enum +{ + ELM_GENLIST_ITEM_NONE = 0, /**< Simple item */ + ELM_GENLIST_ITEM_TREE = (1 << 0), /**< This may be expanded and may have child items */ + ELM_GENLIST_ITEM_GROUP = (1 << 1), /**< The index item of a group of items. This item can have child items */ + + ELM_GENLIST_ITEM_MAX = (1 << 2) +} Elm_Genlist_Item_Type; + +/** + * @brief Enumeration that defines the type of the item field. + * @remarks It is used while updating the item field. + * @remarks It can be used for updating multi fields. + */ +typedef enum +{ + ELM_GENLIST_ITEM_FIELD_ALL = 0, /**< The item contains all fields */ + ELM_GENLIST_ITEM_FIELD_TEXT = (1 << 0), /**< The item contains a text field */ + ELM_GENLIST_ITEM_FIELD_CONTENT = (1 << 1), /**< The item contains a content field */ + ELM_GENLIST_ITEM_FIELD_STATE = (1 << 2) /**< The item contains a state field */ +} Elm_Genlist_Item_Field_Type; + +/** + * @brief Enumeration that defines where to position the item in the genlist. + */ +typedef enum +{ + ELM_GENLIST_ITEM_SCROLLTO_NONE = 0, /**< Scrolls to nowhere */ + ELM_GENLIST_ITEM_SCROLLTO_IN = (1 << 0), /**< Scrolls to the nearest viewport */ + ELM_GENLIST_ITEM_SCROLLTO_TOP = (1 << 1), /**< Scrolls to the top of the viewport */ + ELM_GENLIST_ITEM_SCROLLTO_MIDDLE = (1 << 2) /**< Scrolls to the middle of the viewport */ +} Elm_Genlist_Item_Scrollto_Type; + +/** + * @see Elm_Gen_Item_Class + */ +typedef Elm_Gen_Item_Class Elm_Genlist_Item_Class; + +/** + * @see Elm_Gen_Item_Text_Get_Cb + */ +typedef Elm_Gen_Item_Text_Get_Cb Elm_Genlist_Item_Text_Get_Cb; + +/** + * @see Elm_Gen_Item_Content_Get_Cb + */ +typedef Elm_Gen_Item_Content_Get_Cb Elm_Genlist_Item_Content_Get_Cb; + +/** + * @see Elm_Gen_Item_State_Get_Cb + */ +typedef Elm_Gen_Item_State_Get_Cb Elm_Genlist_Item_State_Get_Cb; + +/** + * @see Elm_Gen_Item_Del_Cb + */ +typedef Elm_Gen_Item_Del_Cb Elm_Genlist_Item_Del_Cb; + +/** + * @brief Adds a new genlist widget to the given parent Elementary + * (container) object. + * + * @details This function inserts a new genlist widget on the canvas. + * + * @since_tizen 2.3 * - * Here is a list of examples that use the genlist, trying to show some of - * its capabilities: - * - @ref genlist_example_01 - * - @ref genlist_example_02 - * - @ref genlist_example_03 - * - @ref genlist_example_04 - * - @ref genlist_example_05 + * @param[in] parent The parent object + * @return A new genlist widget handle, otherwise @c NULL in case of an error + * + * @see elm_genlist_item_append() + * @see elm_object_item_del() + * @see elm_genlist_clear() */ +EAPI Evas_Object *elm_genlist_add(Evas_Object *parent); /** - * @addtogroup Genlist - * @{ + * @brief Removes all items from a given genlist widget. + * + * @details This removes (and deletes) all items in @a obj, making it empty. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * + * @see elm_object_item_del() to remove just one item. + */ +EAPI void elm_genlist_clear(Evas_Object *obj); + +/** + * @brief Enables or disables multi-selection in the genlist. + * + * @details This enables (@c EINA_TRUE) or disables (@c EINA_FALSE) multi-selection in + * the list. This allows more than @c 1 item to be selected. To retrieve the list + * of selected items, use elm_genlist_selected_items_get(). + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] multi The boolean value that enables or disables multi-selection \n + * Default is disabled. + * + * @see elm_genlist_selected_items_get() + * @see elm_genlist_multi_select_get() + */ +EAPI void elm_genlist_multi_select_set(Evas_Object *obj, Eina_Bool multi); + +/** + * @brief Gets whether multi-selection in genlist is enabled or disabled. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The boolean value that indicates whether multi-selection is enabled or disabled + * (@c EINA_TRUE = enabled/@c EINA_FALSE = disabled). Default is @c EINA_FALSE. + * + * @see elm_genlist_multi_select_set() + */ +EAPI Eina_Bool elm_genlist_multi_select_get(const Evas_Object *obj); + +/** + * @brief Sets the horizontal stretching mode. + * + * @details This sets the mode used for sizing items horizontally. Valid modes + * are #ELM_LIST_LIMIT, #ELM_LIST_SCROLL, and #ELM_LIST_COMPRESS. The default is + * ELM_LIST_SCROLL. This mode means that if items are too wide to fit, + * the scroller scrolls horizontally. Otherwise items are expanded + * to fill the width of the viewport of the scroller. If it is + * ELM_LIST_LIMIT, items are expanded to the viewport width and + * limited to that size. If it is ELM_LIST_COMPRESS, the item width is + * fixed (restricted to a minimum of) to the list width when calculating its + * size in order to allow the height to be calculated based on it. This allows, + * for instance, a text block to wrap lines if the Edje part is configured with + * "text.min: 0 1". + * + * @since_tizen 2.3 + * + * @remarks ELM_LIST_COMPRESS makes list resize slower as it + * recalculates every item height again whenever the list width + * changes + * @remarks The homogeneous mode is so that all items in the genlist are of the same + * width/height. With ELM_LIST_COMPRESS, genlist items are initialized fast. + * However, there are no sub-objects in the genlist which can be + * on the flying resizable (such as TEXTBLOCK). If so, then some dynamic + * resizable objects in the genlist would not be diplayed properly. + * + * @param[in] obj The genlist object + * @param[in] mode The mode to use (either #ELM_LIST_SCROLL or #ELM_LIST_LIMIT) + * + * @see elm_genlist_mode_get() + */ +EAPI void elm_genlist_mode_set(Evas_Object *obj, Elm_List_Mode mode); + +/** + * @brief Gets the horizontal stretching mode. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The mode to use + * (#ELM_LIST_LIMIT, #ELM_LIST_SCROLL) + * + * @see elm_genlist_mode_set() + */ +EAPI Elm_List_Mode elm_genlist_mode_get(const Evas_Object *obj); + +/** + * @internal + * + * @brief Enables or disables horizontal and vertical bouncing effect. + * + * @details This enables or disables the scroller bouncing effect for the + * genlist. See elm_scroller_bounce_set() for details. + * + * @param obj The genlist object + * @param h_bounce The boolean value that allows horizontal bouncing (@c EINA_TRUE = on, @c + * EINA_FALSE = off) \n + * Default is @c EINA_FALSE. + * @param v_bounce The boolean value that allows vertical bouncing (@c EINA_TRUE = on, @c + * EINA_FALSE = off) \n + * Default is @c EINA_TRUE. + * + * @deprecated Use elm_scroller_bounce_set() instead. + * + * @see elm_scroller_bounce_set() + * @see elm_genlist_bounce_get() + */ +EINA_DEPRECATED EAPI void elm_genlist_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce); + +/** + * @internal + * + * @brief Gets whether the horizontal and vertical bouncing effect is enabled. + * + * @param obj The genlist object + * @param h_bounce The pointer to a bool that indicates if horizontal bouncing is set + * @param v_bounce The pointer to a bool that indicates if vertical bouncing is set + * + * @deprecated Use elm_scroller_bounce_get() instead. + * + * @see elm_scroller_bounce_get() + * @see elm_genlist_bounce_set() + */ +EINA_DEPRECATED EAPI void elm_genlist_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce); + +/** + * @brief Appends a new item to a given genlist widget. + * + * @details This adds the given item to the end of the list or the end of + * the children list if the @a parent is given. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] itc The item class for the item + * @param[in] data The item data + * @param[in] parent The parent item, otherwise @c NULL if there is no parent item + * @param[in] type The item type + * @param[in] func The convenience function that is called when the item is selected + * @param[in] func_data The data passed to @a func mentioned above + * @return A handle to the added item, otherwise @c NULL if it is not possible + * + * @see elm_genlist_item_prepend() + * @see elm_genlist_item_insert_before() + * @see elm_genlist_item_insert_after() + * @see elm_object_item_del() + */ +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); + +/** + * @brief Prepends a new item to a given genlist widget. + * + * @details This adds an item to the beginning of the list or beginning of the + * children of the parent if given. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] itc The item class for the item + * @param[in] data The item data + * @param[in] parent The parent item, otherwise @c NULL if there is no parent item + * @param[in] type The item type + * @param[in] func The convenience function that is called when the item is selected + * @param[in] func_data The data passed to @a func mentioned above + * @return A handle to the added item, otherwise @c NULL if it is not possible + * + * @see elm_genlist_item_append() + * @see elm_genlist_item_insert_before() + * @see elm_genlist_item_insert_after() + * @see elm_object_item_del() + */ +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); + +/** + * @brief Inserts an item before another in a genlist widget. + * + * @details This inserts an item before another in the list. It is the + * same tree level or group as the item before which it is inserted. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] itc The item class for the item + * @param[in] data The item data + * @param[in] parent The parent item, otherwise @c NULL if there is no parent item + * @param[in] before The item before which to place this new one + * @param[in] type The item type + * @param[in] func The convenience function that is called when the item is selected + * @param[in] func_data The data passed to @a func mentioned above + * @return A handle to the item added, otherwise @c NULL if it is not possible + * + * @see elm_genlist_item_append() + * @see elm_genlist_item_prepend() + * @see elm_genlist_item_insert_after() + * @see elm_object_item_del() + */ +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); + +/** + * @brief Inserts an item after another in a genlist widget. + * + * @details This inserts an item after another in the list. It is in the + * same tree level or group as the item after which it is inserted. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] itc The item class for the item + * @param[in] data The item data + * @param[in] parent The parent item, otherwise @c NULL if there is no parent item + * @param[in] after The item after which to place this new one + * @param[in] type The item type + * @param[in] func The convenience function that is called when the item is selected + * @param[in] func_data The data passed to @a func mentioned above + * @return A handle to the item added, otherwise @c NULL if it is not possible + * + * @see elm_genlist_item_append() + * @see elm_genlist_item_prepend() + * @see elm_genlist_item_insert_before() + * @see elm_object_item_del() + */ +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); + +/** + * @brief Inserts a new item into the sorted genlist object. + * + * @details This inserts an item in the genlist based on a user defined comparison + * function. The two arguments passed to the function @a func are genlist item + * handles to compare. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] itc The item class for the item + * @param[in] data The item data + * @param[in] parent The parent item, otherwise @c NULL if there is no parent item + * @param[in] type The item type + * @param[in] comp The function called for sorting + * @param[in] func The convenience function that is called when the item is selected + * @param[in] func_data The data passed to @a func mentioned above + * @return A handle to the item added, otherwise @c NULL if it is not possible + * + * @see elm_genlist_item_append() + * @see elm_genlist_item_prepend() + * @see elm_genlist_item_insert_after() + * @see elm_object_item_del() + */ +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); + +/* Operations to retrieve existing items */ +/** + * @brief Gets the selected item in the genlist. + * + * @details This gets the selected item in the list (if multi-selection is enabled, only + * the item that is first selected in the list is returned, which is not very + * useful, so see elm_genlist_selected_items_get() to know when multi-selection is + * used). + * + * @since_tizen 2.3 + * + * @remarks If no item is selected, @c NULL is returned. + * + * @param[in] obj The genlist object + * @return The selected item, otherwise @c NULL if none are selected + * + * @see elm_genlist_selected_items_get() + */ +EAPI Elm_Object_Item *elm_genlist_selected_item_get(const Evas_Object *obj); + +/** + * @brief Gets a list of selected items in the genlist. + * + * @details It returns a list of selected items. This list pointer is only valid as + * long as the selection doesn't change (no items are selected or unselected, or + * unselected implicitly by deletion). The list contains genlist item + * pointers. The order of the items in this list is the order in which they were + * selected, i.e. the first item in this list is the first item that is + * selected, and so on. + * + * @since_tizen 2.3 + * + * @remarks If not in the multi-select mode, use + * elm_genlist_selected_item_get() instead. + * + * @param[in] obj The genlist object + * @return The list of selected items, otherwise @c NULL if none are selected + * + * @see elm_genlist_multi_select_set() + * @see elm_genlist_selected_item_get() + */ +EAPI Eina_List *elm_genlist_selected_items_get(const Evas_Object *obj); + +/** + * @brief Gets a list of realized items in the genlist. + * + * @details This returns a list of realized items in the genlist. The list + * contains genlist item pointers. The list must be freed by the + * caller when done with eina_list_free(). The item pointers in the + * list are only valid as long as those items are not deleted or the + * genlist is not deleted. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The list of realized items, otherwise @c NULL if none are realized + * + * @see elm_genlist_realized_items_update() + */ +EAPI Eina_List *elm_genlist_realized_items_get(const Evas_Object *obj); + +/** + * @brief Gets the first item in the genlist. + * + * @details This returns the first item in the list. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The first item, otherwise @c NULL if there are no items + */ +EAPI Elm_Object_Item *elm_genlist_first_item_get(const Evas_Object *obj); + +/** + * @brief Gets the last item in the genlist. + * + * @details This returns the last item in the list. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The last item, otherwise @c NULL if there are no items + */ +EAPI Elm_Object_Item *elm_genlist_last_item_get(const Evas_Object *obj); + +/** + * @internal + * + * @brief Sets the scrollbar policy. + * + * @details This sets the scrollbar visibility policy for the given genlist + * scroller. #ELM_SCROLLER_POLICY_AUTO means the scrollbar is + * made visible if it is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON + * turns it on at all times, and #ELM_SCROLLER_POLICY_OFF always keeps it off. + * This applies for the horizontal and vertical scrollbars respectively. + * The default is #ELM_SCROLLER_POLICY_AUTO. + * + * @param obj The genlist object + * @param policy_h The horizontal scrollbar policy + * @param policy_v The vertical scrollbar policy + * + * @deprecated Use elm_scroller_policy_set() instead. + * + * @see elm_scroller_policy_set() + */ +EINA_DEPRECATED EAPI void elm_genlist_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v); + +/** + * @internal + * + * @brief Gets the scrollbar policy. + * + * @param obj The genlist object + * @param policy_h The pointer to store the horizontal scrollbar policy + * @param policy_v The pointer to store the vertical scrollbar policy + * + * @deprecated Use elm_scroller_policy_get() instead. + * + * @see elm_scroller_policy_get() + */ +EINA_DEPRECATED EAPI void elm_genlist_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v); + +/** + * @brief Gets the @b next item in a genlist widget's internal list of items, + * given that a handle to one of those items is present. + * + * @details This returns the item placed after @a it on the container + * genlist. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item to fetch next from + * @return The item after @a it, otherwise @c NULL if there are none (and + * on errors) + * + * @see elm_genlist_item_prev_get() + */ +EAPI Elm_Object_Item *elm_genlist_item_next_get(const Elm_Object_Item *it); + +/** + * @brief Get the @b previous item in a genlist widget's internal list of items, + * given that a handle to one of those items is present. + * + * @details This returns the item placed before @a it on the container + * genlist. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item to fetch previous from + * @return The item before @a it, otherwise @c NULL if there are none (and + * on errors) + * + * @see elm_genlist_item_next_get() + */ +EAPI Elm_Object_Item *elm_genlist_item_prev_get(const Elm_Object_Item *it); + +/** + * @brief Sets whether a given genlist item is selected. + * + * @details This sets the selected state of an item. If multi-selection is + * not enabled on the containing genlist and @a selected is @c + * EINA_TRUE, any previously selected item gets + * unselected in favor of this new one. + * + * @since_tizen 2.3 + * + * @param[in] it The item + * @param[in] selected If @c EINA_TRUE it is selected, + * otherwise @c EINA_FALSE to unselect it + * + * @see elm_genlist_item_selected_get() + */ +EAPI void elm_genlist_item_selected_set(Elm_Object_Item *it, Eina_Bool selected); + +/** + * @brief Gets whether a given genlist item is selected. + * + * @since_tizen 2.3 + * + * @param[in] it The item + * @return @c EINA_TRUE if it's selected, otherwise @c EINA_FALSE + * + * @see elm_genlist_item_selected_set() + */ +EAPI Eina_Bool elm_genlist_item_selected_get(const Elm_Object_Item *it); + +/** + * @brief Shows the portion of a genlist's internal list containing a given + * item, immediately. + * + * @details This causes genlist to jump to the given item @a it and display it (by + * jumping to that position), if it is not fully visible. + * + * @since_tizen 2.3 + * + * @param[in] it The item to display + * @param[in] type The position to bring the given item to + * @ref Elm_Genlist_Item_Scrollto_Type + * + * @see elm_genlist_item_bring_in() + */ +EAPI void elm_genlist_item_show(Elm_Object_Item *it, Elm_Genlist_Item_Scrollto_Type type); + +/** + * @brief Animatedly brings a given item to the visible area of a genlist. + * + * @details This causes genlist to jump to the given item @a it and display it (by + * animatedly scrolling), if it is not fully visible. + * This may use animation and may take some time. + * + * @since_tizen 2.3 + * + * @param[in] it The item to display + * @param[in] type The position to bring the given item to + * @ref Elm_Genlist_Item_Scrollto_Type + * + * @see elm_genlist_item_show() + */ +EAPI void elm_genlist_item_bring_in(Elm_Object_Item *it, Elm_Genlist_Item_Scrollto_Type type); + +/** + * @brief Updates the content of an item. + * + * @details This updates an item by calling all the item class functions again + * to get the content, text, and states. Use this when the original + * item data has changed and the changes are desired to reflect. + * + * Use elm_genlist_realized_items_update() to update already realized + * items. + * + * @since_tizen 2.3 + * + * @remarks This also updates the internal genlist item object(edje_object as of now). + * So when this is called, between mouse down and mouse up, mouse up event is + * ignored because edje_object is deleted and created again by this API. If + * you want to avoid this, use @ref elm_genlist_item_fields_update. + * + * @param[in] it The item + * + * @see elm_genlist_realized_items_update() + */ +EAPI void elm_genlist_item_update(Elm_Object_Item *it); + +/** + * @brief Updates the item class of an item. + * + * @details This sets another class of the item, changing the way it is + * displayed. After changing the item class, elm_genlist_item_update() is + * called on the item @a it. + * + * @since_tizen 2.3 + * + * @param[in] it The item + * @param[in] itc The item class for the item + */ +EAPI void elm_genlist_item_item_class_update(Elm_Object_Item *it, const Elm_Genlist_Item_Class *itc); + +/** + * @brief Gets the genlist item class for the given genlist item. + * + * @details This returns the Genlist_Item_Class for the given item. It can be used to + * examine the function pointers and item style. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return The item class + */ +EAPI const Elm_Genlist_Item_Class *elm_genlist_item_item_class_get(const Elm_Object_Item *it); + +/** + * @brief Gets the index of the item. It is only valid once it is displayed. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return The position inside the list of items + */ +EAPI int elm_genlist_item_index_get(const Elm_Object_Item *it); + +/** + * @brief Updates the content of all the realized items. + * + * @details This updates all the realized items by calling all the item class functions again + * to get the content, text and states. Use this when the original + * item data has changed and the changes are desired to reflect. + * + * To update just one item, use elm_genlist_item_update(). + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * + * @see elm_genlist_realized_items_get() + * @see elm_genlist_item_update() + */ +EAPI void elm_genlist_realized_items_update(Evas_Object *obj); + +/** + * @brief Returns the number of items that are currently in a list. + * + * @since_tizen 2.3 + * + * @remarks This behavior is O(1) and includes items which may or may not be realized. + * + * @param[in] obj The list + * @return The total number of items in the list + */ +EAPI unsigned int elm_genlist_items_count(const Evas_Object *obj); + +/** + * @brief Creates a new genlist item class in a given genlist widget. + * + * @details This adds a genlist item class for the genlist widget. When adding an item, + * the genlist_item_{append, prepend, insert} function needs the item class of the item. + * Given callback parameters are used for retrieving {text, content} of + * an added item. Set as @c NULL if it's not used. + * If there's no available memory, it returns @c NULL. + * + * @since_tizen 2.3 + * + * @return Newly allocated genlist item class + * + * @see elm_genlist_item_class_free() + * @see elm_genlist_item_append() + */ +EAPI Elm_Genlist_Item_Class *elm_genlist_item_class_new(void); + +/** + * @brief Removes an item class from a given genlist widget. + * + * @details This removes an item class from the genlist widget. + * Whenever it has no more references to it, the item class is going to be freed. + * Otherwise it just decreases its reference count. + * + * @since_tizen 2.3 + * + * @param[in] itc The item class to be removed + * + * @see elm_genlist_item_class_new() + * @see elm_genlist_item_class_ref() + * @see elm_genlist_item_class_unref() */ +EAPI void elm_genlist_item_class_free(Elm_Genlist_Item_Class *itc); -#include <elm_genlist_common.h> -#ifdef EFL_EO_API_SUPPORT -#include <elm_genlist_eo.h> -#endif -#ifndef EFL_NOLEGACY_API_SUPPORT -#include <elm_genlist_legacy.h> -#endif +/** + * @brief Increments the object reference count for the item class. + * + * @details This API just increases its reference count for item class management. + * + * @since_tizen 2.3 + * + * @param[in] itc The given item class object to reference + * + * @see elm_genlist_item_class_unref() + */ +EAPI void elm_genlist_item_class_ref(Elm_Genlist_Item_Class *itc); /** + * @brief Decrements the object reference count for the item class. + * + * @details This API just decreases its reference count for item class management. + * Reference count can't be less than @c 0. + * + * @since_tizen 2.3 + * + * @param[in] itc The given item class object to reference + * + * @see elm_genlist_item_class_ref() + * @see elm_genlist_item_class_free() + */ +EAPI void elm_genlist_item_class_unref(Elm_Genlist_Item_Class *itc); + +/** + * @brief Sets the text to be shown in a given genlist item's tooltips. + * + * @details This call is used to setup the text to be used as a tooltip for that item + * (analogous to elm_object_tooltip_text_set(), but are item + * tooltips with higher precedence than object tooltips). It can + * have only one tooltip at a time, so any previous tooltip data + * gets removed. + * + * @since_tizen 2.3 + * + * @remarks In order to set content or something else as a tooltip, see + * elm_genlist_item_tooltip_content_cb_set(). + * + * @param[in] it The genlist item + * @param[in] text The text to set in the content + */ +EAPI void elm_genlist_item_tooltip_text_set(Elm_Object_Item *it, const char *text); + +/** + * @brief Sets the content to be shown in a given genlist item's tooltips. + * + * @details This call is used to setup the tooltip's content to @a it + * (analogous to elm_object_tooltip_content_cb_set(), but are + * item tooltips with higher precedence than object tooltips). It + * can have only one tooltip at a time, so any previous tooltip + * content gets removed. @a func (with @a data) is called + * every time Elementary needs to display the tooltip. Moreover, it should + * return a valid Evas object, which is fully managed by the + * tooltip system and gets deleted when the tooltip is gone. + * + * @since_tizen 2.3 + * + * @remarks In order to set just text as a tooltip, see + * elm_genlist_item_tooltip_text_set(). + * + * @param[in] it The genlist item + * @param[in] func The function returning the tooltip contents + * @param[in] data The data to provide to @a func as callback data/context + * @param[in] del_cb Called when data is not needed anymore, either when + * another callback replaces @a func, the tooltip is unset with + * elm_genlist_item_tooltip_unset() or the owner @a it dies \n + * This callback receives the given @a data as its first parameter + * with @a event_info as the item handle. + */ +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); + +/** + * @brief Unsets a tooltip from a given genlist item. + * + * @details This call removes any tooltip set on @a it. The callback + * provided as @a del_cb to + * elm_genlist_item_tooltip_content_cb_set() is called to + * notify that it is not used anymore (and have resources cleaned, if + * needed). + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item from which to remove a previously set tooltip + * + * @see elm_genlist_item_tooltip_content_cb_set() + */ +EAPI void elm_genlist_item_tooltip_unset(Elm_Object_Item *it); + +/** + * @brief Sets a different @b style for a given genlist item's tooltip. + * + * @since_tizen 2.3 + * + * @remarks Tooltips can have <b>alternate styles</b> to be displayed on, + * which are defined by the theme set on Elementary. This function + * works analogous to elm_object_tooltip_style_set(), but is + * applied only to genlist item objects. The default style for + * tooltips is @c "default". + * + * @remarks Before you set a style, you should define a tooltip with + * elm_genlist_item_tooltip_content_cb_set() or + * elm_genlist_item_tooltip_text_set() + * + * @param[in] it The genlist item with a tooltip set + * @param[in] style The <b>theme style</b> to use on tooltips (e.g. @c + * "default", @c "transparent", etc) + * + * @see elm_genlist_item_tooltip_style_get() + */ +EAPI void elm_genlist_item_tooltip_style_set(Elm_Object_Item *it, const char *style); + +/** + * @brief Gets the style set for a given genlist item's tooltip. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item on which the tooltip is already set + * @return style The theme style in use, whose default value is @c "default" \n + * If the object does not have a tooltip set, + * then @c NULL is returned. + * + * @see elm_genlist_item_tooltip_style_set() + */ +EAPI const char *elm_genlist_item_tooltip_style_get(const Elm_Object_Item *it); + +/** + * @brief Disables the size restrictions on an object's tooltip. + * + * @details This function allows a tooltip to expand beyond its parent window's canvas. + * It is instead limited only to the size of the display. + * + * @since_tizen 2.3 + * + * @param[in] it The tooltip's anchor object + * @param[in] disable If @c EINA_TRUE size restrictions are disabled, otherwise @c EINA_FALSE + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + */ +EAPI Eina_Bool elm_genlist_item_tooltip_window_mode_set(Elm_Object_Item *it, Eina_Bool disable); + +/** + * @brief Retrieves the size restriction state of an object's tooltip. + * + * @details This function returns a value that indicates whether a tooltip is allowed to expand beyond + * its parent window's canvas. + * + * @since_tizen 2.3 + * + * @remarks It is instead limited only by the size of the display. + * + * @param[in] it The tooltip's anchor object + * @return If @c EINA_TRUE size restrictions are disabled, + * otherwise @c EINA_FALSE + */ +EAPI Eina_Bool elm_genlist_item_tooltip_window_mode_get(const Elm_Object_Item *it); + +/** + * @brief Sets the type of mouse pointer/cursor decoration to be displayed + * when the mouse pointer is over the given genlist widget item. + * + * @details This function is analogous to elm_object_cursor_set(), but + * the cursor's changing area is restricted to the item's + * area, and not the whole widget. Note that item cursors + * have precedence over widget cursors, so a mouse over @a + * it always shows the @a cursor type. + * + * @since_tizen 2.3 + * + * @remarks If this function is called twice for an object, a previously set + * cursor is unset on the second call. + * + * @param[in] it The genlist item on which to customize the cursor + * @param[in] cursor the cursor type + * + * @see elm_object_cursor_set() + * @see elm_genlist_item_cursor_get() + * @see elm_genlist_item_cursor_unset() + */ +EAPI void elm_genlist_item_cursor_set(Elm_Object_Item *it, const char *cursor); + +/** + * @brief Gets the type of mouse pointer/cursor decoration set to be displayed + * when the mouse pointer is over the given genlist widget item. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item with a custom cursor set + * @return The cursor type, otherwise @c NULL if no custom cursors + * are set to @a it (and on errors) + * + * @see elm_object_cursor_get() + * @see elm_genlist_item_cursor_set() for more details + * @see elm_genlist_item_cursor_unset() + */ +EAPI const char *elm_genlist_item_cursor_get(const Elm_Object_Item *it); + +/** + * @brief Unsets the custom mouse pointer/cursor decoration set to be + * displayed when the mouse pointer is over the given genlist widget + * item, thus making it show the @b default cursor again. + * + * @since_tizen 2.3 + * + * @remarks Use this call to undo any custom settings on this item's cursor + * decoration, bringing it back to the default value (no custom style set). + * + * @param[in] it The genlist item + * + * @see elm_object_cursor_unset() + * @see elm_genlist_item_cursor_set() + */ +EAPI void elm_genlist_item_cursor_unset(Elm_Object_Item *it); + +/** + * @brief Sets a different @b style for a given custom cursor set for a + * genlist item. + * + * @details This function only makes sense when one is using customized mouse + * cursor decorations <b>defined in a theme file</b> , which can + * have, given a cursor name/type, <b>alternate styles</b> on + * it. It is analogous to elm_object_cursor_style_set(), but + * is applied only to genlist item objects. + * + * @since_tizen 2.3 + * + * @remarks Before you set a cursor style, you should define a + * custom cursor on the item using + * elm_genlist_item_cursor_set() + * + * @param[in] it The genlist item with a custom cursor set + * @param[in] style The <b>theme style</b> to use (e.g. @c "default", + * @c "transparent", etc) + * + * @see elm_genlist_item_cursor_engine_only_set() + * @see elm_genlist_item_cursor_style_get() + */ +EAPI void elm_genlist_item_cursor_style_set(Elm_Object_Item *it, const char *style); + +/** + * @brief Gets the current @b style set for a given genlist item's custom + * cursor. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item with custom cursor set + * @return style The cursor style in use /n + * If the object does not have a cursor set, then @c NULL is returned. + * + * @see elm_genlist_item_cursor_style_set() + */ +EAPI const char *elm_genlist_item_cursor_style_get(const Elm_Object_Item *it); + +/** + * @brief Sets whether the (custom) cursor for a given genlist item should be + * searched in its theme or should only rely on the + * rendering engine. + * + * @details This call is used only if you have set a custom cursor + * for genlist items using elm_genlist_item_cursor_set(). + * + * @since_tizen 2.3 + * + * @remarks By default, cursors are looked for only from those + * provided by the rendering engine. + * + * @param[in] it The item with custom (custom) cursor already set on it + * @param[in] engine_only If @c EINA_TRUE look for cursors + * only from those provided by the rendering engine, + * otherwise @c EINA_FALSE to have them searched on the widget's theme as well + */ +EAPI void elm_genlist_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only); + +/** + * @brief Gets whether the (custom) cursor for a given genlist item is being + * searched in its theme or is only relying on the rendering + * engine. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return @c EINA_TRUE if cursors are being looked for only from + * those provided by the rendering engine, + * otherwise @c EINA_FALSE if they are being searched on the widget's theme as well. + * + * @see elm_genlist_item_cursor_engine_only_set() for more details + */ +EAPI Eina_Bool elm_genlist_item_cursor_engine_only_get(const Elm_Object_Item *it); + +/** + * @brief Enables or disables the homogeneous mode. + * + * @details This enables the homogeneous mode where items are of the same + * height and width so that genlist may perform lazy-loading at its + * maximum (which increases the performance for scrolling the list). + * In the normal mode, genlist pre-calculates all the items' sizes even + * though they are not in use. So items' callbacks are called for more times than + * expected. But the homogeneous mode skips the item size pre-calculation + * process so items' callbacks are called only when the item is needed. + * + * @since_tizen 2.3 + * + * @remarks This also works well with group index. + * + * @param[in] obj The genlist object + * @param[in] homogeneous The boolean value assuming that the items within the genlist are of the + * same height and width (@c EINA_TRUE = on, @c EINA_FALSE = off) \n + * Default is @c EINA_FALSE. + * + * @see elm_genlist_mode_set() + * @see elm_genlist_homogeneous_get() + */ +EAPI void elm_genlist_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous); + +/** + * @brief Gets whether the homogeneous mode is enabled. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The boolean value assuming that the items within the genlist are of the same height + * and width (@c EINA_TRUE = on, @c EINA_FALSE = off) + * + * @see elm_genlist_homogeneous_set() + */ +EAPI Eina_Bool elm_genlist_homogeneous_get(const Evas_Object *obj); + +/** + * @brief Sets the maximum number of items within an item block. + * + * @details This configures the block count to tune the target with, for a particular + * performance matrix. + * + * @since_tizen 2.3 + * + * @remarks A block of objects are used to reduce the number of operations occurring due to + * large number of objects on the screen. It can determine the visibility, or if the + * object has changed, its theme needs to be updated by doing this kind of + * calculation to the entire block, instead of every object. + * + * @remarks The default value for the block count is enough for most lists, so unless + * your sure that you have a lot of objects visible on the screen at the same + * time, don't try to change this. + * + * @param[in] obj The genlist object + * @param[in] count The maximum number of items within an item block \n + * Default is @c 32. + * + * @see elm_genlist_block_count_get() + * @see @ref Genlist_Implementation + */ +EAPI void elm_genlist_block_count_set(Evas_Object *obj, int count); + +/** + * @brief Gets the maximum number of items within an item block. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The maximum number of items within an item block + * + * @see elm_genlist_block_count_set() + */ +EAPI int elm_genlist_block_count_get(const Evas_Object *obj); + +/** + * @brief Sets the timeout in seconds for the longpress event. + * + * @since_tizen 2.3 + * + * @remarks This option changes the time it takes to send an event @c "longpressed" + * after the mouse down signal is sent to the list. If this event occurs, no + * @c "clicked" event is sent. + * + * @remarks If you set the longpress timeout value with this API, your genlist + * is not affected by the longpress value of the elementary config value + * later. + * + * @param[in] obj The genlist object + * @param[in] timeout The timeout in seconds \n + * The default value is elm config value(1.0). + * + * @see elm_genlist_longpress_timeout_set() + */ +EAPI void elm_genlist_longpress_timeout_set(Evas_Object *obj, double timeout); + +/** + * @brief Gets the timeout in seconds for the longpress event. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The timeout in seconds + * + * @see elm_genlist_longpress_timeout_get() + */ +EAPI double elm_genlist_longpress_timeout_get(const Evas_Object *obj); + +/** + * @brief Gets the item that is at the x, y canvas coordinates. + * + * @details This returns the item at the given coordinates (which are canvas + * relative, not object-relative). If an item is at that coordinate, + * that item handle is returned, and if @a posret is not @c NULL, the + * integer it is pointing to is set to either @c -1, @c 0, or @c 1, depending on whether + * the coordinate is on the upper portion of that item (-1), in the + * middle section (0), or on the lower part (1). If @c NULL is returned as + * an item (no item found there), then posret may indicate @c -1 or @c 1 + * depending on whether the coordinate is above or below the items in + * the genlist respectively. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] x The input x coordinate + * @param[in] y The input y coordinate + * @param[out] posret The position relative to the returned item + * @return The item at the coordinates, otherwise @c NULL if there are none + */ +EAPI Elm_Object_Item *elm_genlist_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret); + +/** + * @brief Gets the parent item of the given genlist item. + * + * @details This returns the item that is specified as the parent of the item @a it in + * elm_genlist_item_append() and insertion related functions. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return The parent of the item, otherwise @c NULL if it has no parent item + */ +EAPI Elm_Object_Item *elm_genlist_item_parent_get(const Elm_Object_Item *it); + +/** + * @brief Removes all sub-items (children) of the given item. + * + * @details This removes all items (and their descendants) that are children of the + * given item @a it. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * + * @see elm_genlist_clear() + * @see elm_object_item_del() + */ +EAPI void elm_genlist_item_subitems_clear(Elm_Object_Item *it); + +/** + * @brief Sets the expanded state of an item. + * + * @details This function flags the item of type #ELM_GENLIST_ITEM_TREE as + * either expanded or not expanded. + * + * @since_tizen 2.3 + * + * @remarks The theme responds to this change visually, and a signal @c "expanded" or + * @c "contracted" is sent from the genlist with a pointer to the item that + * has been expanded/contracted. + * + * @remarks Calling this function won't show or hide any child of this item (if it is + * a parent). You must manually delete and create them on the callbacks of + * the @c "expanded" or @c "contracted" signals. + * + * @param[in] it The genlist item + * @param[in] expanded The expanded state (@c EINA_TRUE if expanded, @c EINA_FALSE if not expanded) + * + * @see elm_genlist_item_expanded_get() + */ +EAPI void elm_genlist_item_expanded_set(Elm_Object_Item *it, Eina_Bool expanded); + +/** + * @brief Gets the expanded state of an item. + * + * @details This gets the expanded state of an item. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return The expanded state + * + * @see elm_genlist_item_expanded_set() + */ +EAPI Eina_Bool elm_genlist_item_expanded_get(const Elm_Object_Item *it); + +/** + * @brief Gets the depth of the expanded item + * + * @param[in] it The genlist item object + * @return The depth of the expanded item + */ +EAPI int elm_genlist_item_expanded_depth_get(const Elm_Object_Item *it); + +/** + * @brief Unsets all the content fetched by the item class. + * + * @details This instructs genlist to release references to content in the item, + * meaning that they are longer managed by genlist and are + * floating "orphans" that can be re-used elsewhere if the user wants + * to. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @param[in] l The content list to return + */ +EAPI void elm_genlist_item_all_contents_unset(Elm_Object_Item *it, Eina_List **l); + +/** + * @brief Promotes an item to the top of the list. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + */ +EAPI void elm_genlist_item_promote(Elm_Object_Item *it); + +/** + * @brief Demotes an item to the end of the list. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + */ +EAPI void elm_genlist_item_demote(Elm_Object_Item *it); + +/** + * @brief Updates a part of an item. + * + * @details This updates an item part by calling the item's fetching functions again + * to get the content, text, and states. Use this when the original + * item data has changed and the changes are desired to reflect. + * Second part's argument is used for globbing to match '*', '?', and '.' + * It can be used for updating multi fields. + * + * @since_tizen 2.3 + * + * @remarks Use elm_genlist_realized_items_update() to update an item's all + * property. + * + * @param[in] it The genlist item + * @param[in] parts The name of the item part + * @param[in] itf The item part type + * + * @see elm_genlist_item_update() + */ +EAPI void elm_genlist_item_fields_update(Elm_Object_Item *it, const char *parts, Elm_Genlist_Item_Field_Type itf); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Activates the genlist mode on an item. + * + * @remarks A genlist mode is a different way of selecting an item. Once a mode is + * activated on an item, any other selected item is immediately unselected. + * This feature provides an easy way of implementing a new kind of animation + * for selecting an item, without having to entirely rewrite the item style + * theme. However, the elm_genlist_selected_* API can't be used to get what + * item is activated for a mode. + * + * @remarks The current item style is still being used, but applying a genlist mode to + * an item selects it by using a different kind of animation. + * + * @remarks The current active item for a mode can be found by + * elm_genlist_decorated_item_get(). + * + * @remarks The characteristics of a genlist mode are: + * - Only one mode can be actived at a time, and for only one item. + * - Genlist handles deactivating other items when one item is activated. + * - A mode is defined in the genlist theme (edc), and more modes can easily + * be added. + * - A mode style and the genlist item style are different things. They + * can be combined to provide a default style to the item, with some kind + * of animation for that item when the mode is activated. + * + * @remarks When a mode is activated on an item, a new view for that item is created. + * The theme of this mode defines the animation that is be used to transit + * the item from the old view to the new view. This second (new) view remains + * active for that item while the mode is active on the item, and gets + * destroyed after the mode is totally deactivated from that item. + * + * @param[in] it The genlist item + * @param[in] decorate_it_type The mode name + * @param[in] decorate_it_set The boolean value to define the set or unset mode + * + * @see elm_genlist_mode_get() + * @see elm_genlist_decorated_item_get() + */ +EAPI void elm_genlist_item_decorate_mode_set(Elm_Object_Item *it, const char *decorate_it_type, Eina_Bool decorate_it_set); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Get the item's decorate mode. + * + * @details This function just returns the name of the item's decorate mode. + * + * @param[in] it The genlist item + * + * @see elm_genlist_item_decorate_mode_set() + * @see elm_genlist_decorated_item_get() + */ +EAPI const char *elm_genlist_item_decorate_mode_get(const Elm_Object_Item *it); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Gets the active genlist mode item. + * + * @details This function returns the item that is activated with a mode, by the + * function elm_genlist_item_decorate_mode_set(). + * + * @param[in] obj The genlist object + * @return The active item for that current mode, otherwise @c NULL if no item is + * activated with a mode + * + * @see elm_genlist_item_decorate_mode_set() + * @see elm_genlist_mode_get() + */ +EAPI Elm_Object_Item *elm_genlist_decorated_item_get(const Evas_Object *obj); + +/** + * @brief Sets the reorder mode. + * + * @since_tizen 2.3 + * + * @remarks After turning on the reorder mode, longpress on a normal item triggers + * reordering of the item. You can move the item up and down. However, reordering + * does not work with group items. + * + * @param[in] obj The genlist object + * @param[in] reorder_mode The reorder mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + */ +EAPI void elm_genlist_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode); + +/** + * @brief Gets the reorder mode. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The reorder mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + */ +EAPI Eina_Bool elm_genlist_reorder_mode_get(const Evas_Object *obj); + +/** + * @brief Gets the item type. + * + * @details This function returns the item type. + * If it fails, the return value is @c ELM_GENLIST_ITEM_MAX + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item + * @return The item type + */ +EAPI Elm_Genlist_Item_Type elm_genlist_item_type_get(const Elm_Object_Item *it); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Sets the genlist decorate mode. + * + * @details This sets the genlist decorate mode for all items. + * + * @param obj The genlist object + * @param decorated The decorate mode status + * (@c EINA_TRUE = decorate mode, @c EINA_FALSE = normal mode + */ +EAPI void elm_genlist_decorate_mode_set(Evas_Object *obj, Eina_Bool decorated); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Gets the genlist decorate mode. + * + * @param obj The genlist object + * @return The decorate mode status + * (@c EINA_TRUE = decorate mode, @c EINA_FALSE = normal mode + */ +EAPI Eina_Bool elm_genlist_decorate_mode_get(const Evas_Object *obj); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Sets the flip state of a given genlist item. + * + * @details This function sets the flip state of a given genlist item. + * The flip mode overrides the current item object. + * It can be used for on-the-fly item replace. + * The flip mode can be used with/without the decorate mode. + * + * @param it The genlist item object + * @param flip The flip mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + * + * @see elm_genlist_item_flip_get() + */ + +EAPI void elm_genlist_item_flip_set(Elm_Object_Item *it, Eina_Bool flip); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Gets the flip state of a given genlist item. + * + * @details This function returns the flip state of a given genlist item. + * If the parameter is invalid, it returns @c EINA_FALSE. + * + * @param it The genlist item object + * + * @see elm_genlist_item_flip_set() + */ + +EAPI Eina_Bool elm_genlist_item_flip_get(const Elm_Object_Item *it); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Sets the genlist tree effect. + * + * @param obj The genlist object + * @param enabled The tree effect status + * (@c EINA_TRUE = enabled, @c EINA_FALSE = disabled + */ +EAPI void elm_genlist_tree_effect_enabled_set(Evas_Object *obj, Eina_Bool enabled); + +/** + * @internal + * @remarks Tizen no feature + * + * @brief Gets the genlist tree effect. + * + * @param obj The genlist object + * @return The tree effect status + * (@c EINA_TRUE = enabled, @c EINA_FALSE = disabled + */ +EAPI Eina_Bool elm_genlist_tree_effect_enabled_get(const Evas_Object *obj); + +/** + * @brief Sets the genlist select mode. + * + * @since_tizen 2.3 + * + * @remarks elm_genlist_select_mode_set() changes the item select mode in the genlist widget. + * - ELM_OBJECT_SELECT_MODE_DEFAULT : Items call their selection @a func and + * callback on first getting selected. Any further clicks + * do nothing, unless you set the always select mode. + * - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, + * every click calls the selected callbacks. + * - ELM_OBJECT_SELECT_MODE_NONE : This turns off the ability to select items + * entirely and they neither appear selected nor call selected + * callback functions. + * + * @param[in] obj The genlist object + * @param[in] mode The select mode + * + * @see elm_genlist_select_mode_get() + */ +EAPI void elm_genlist_select_mode_set(Evas_Object *obj, Elm_Object_Select_Mode mode); + +/** + * @brief Gets the genlist select mode. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return The select mode + * (If getting the mode fails, it returns @c ELM_OBJECT_SELECT_MODE_MAX) + * + * @see elm_genlist_select_mode_set() + */ +EAPI Elm_Object_Select_Mode elm_genlist_select_mode_get(const Evas_Object *obj); + +/** + * @brief Sets whether the genlist items should be highlighted when an item is selected. + * + * @details This turns on/off the highlight effect when an item is selected and + * it gets or does not get highlighted. The selected and clicked + * callback functions are still called. + * + * @since_tizen 2.3 + * + * @remarks Highlight is enabled by default. + * + * @param[in] obj The genlist object + * @param[in] highlight If @c EINA_TRUE highlighting is enabled, + * otherwise @c EINA_FALSE to disable it + * + * @see elm_genlist_highlight_mode_get(). + */ +EAPI void elm_genlist_highlight_mode_set(Evas_Object *obj, Eina_Bool highlight); + +/** + * @brief Gets whether the genlist items should be highlighted when an item is selected. + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @return @c EINA_TRUE indicates that items can be highlighted, + * otherwise @c EINA_FALSE indicates that they can't \n + * If @a obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_genlist_highlight_mode_set() + */ +EAPI Eina_Bool elm_genlist_highlight_mode_get(const Evas_Object *obj); + +/** + * @brief Sets the genlist item select mode. + * + * @since_tizen 2.3 + * + * @remarks elm_genlist_select_mode_set() changes the item select mode. + * - ELM_OBJECT_SELECT_MODE_DEFAULT : The item calls their selection @a func and + * callback on first getting selected. Any further clicks + * do nothing, unless you set the always select mode. + * - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, + * every click calls the selected callbacks. + * - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select the item + * entirely and they neither appear selected nor call selected + * callback functions. + * - ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY : This applies the no-finger-size rule + * with @c ELM_OBJECT_SELECT_MODE_NONE. The no-finger-size rule makes an item + * smaller than lower limit. Clickable objects should be bigger than + * a human touch point device (your finger) for some touch or + * small screen devices. Once it is enabled, the item can be shrunk to a value more than + * the predefined finger-size value. And the item is updated. + * + * @param[in] it The genlist item object + * @param[in] mode The select mode + * + * @see elm_genlist_item_select_mode_get() + */ +EAPI void +elm_genlist_item_select_mode_set(Elm_Object_Item *it, + Elm_Object_Select_Mode mode); + +/** + * @brief Gets the genlist item select mode. + * + * @since_tizen 2.3 + * + * @param[in] it The genlist item object + * @return The select mode + * (If getting the mode fails, it returns @c ELM_OBJECT_SELECT_MODE_MAX) + * + * @see elm_genlist_item_select_mode_set() + */ +EAPI Elm_Object_Select_Mode +elm_genlist_item_select_mode_get(const Elm_Object_Item *it); + + +/** + * @brief Gets the nth item in a given genlist widget, placed at position @a nth, in + * its internal items list. + * + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The genlist object + * @param[in] nth The number of the item to grab (@c 0 being the first) + * + * @return The item stored in @a obj at position @a nth, otherwise @c NULL if there is + * no item with that index (and on errors) + */ +EAPI Elm_Object_Item * +elm_genlist_nth_item_get(const Evas_Object *obj, unsigned int nth); + + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Sets the genlist fx mode. + * + * @remarks This API can be changed or deleted later. + * + * @remarks This sets the genlist special effects. + * Use this only when the genlist effects have to be disabled. + * + * @remarks In normal cases, don't use this API. + * The fx mode is enabled by default. + * + * @param obj The genlist object + * @param fx_mode The fx status + * (@c EINA_TRUE = fx mode, @c EINA_FALSE = normal mode) + */ +EAPI void +elm_genlist_fx_mode_set(Evas_Object *obj, Eina_Bool fx_mode); + + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Gets the genlist fx mode. + * + * @remarks This API can be changed or deleted later. + * + * @param obj The genlist object + * @return The fx mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + */ +EAPI Eina_Bool +elm_genlist_fx_mode_get(const Evas_Object *obj); + + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Sets whether a given genlist item is hidden. + * + * @details This sets the hidden state of an item. + * + * @param it The genlist item + * @param hide If @c EINA_TRUE it hides the item, + * otherwise @c EINA_FALSE to show it + */ +EAPI void +elm_genlist_item_hide_set(const Elm_Object_Item *it, Eina_Bool hide); + + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Gets the genlist item's hidden mode + * + * @param it The genlist item object + * @return The hidden mode + * (EINA_TRUE = on, EINA_FALSE = off) + */ +EAPI Eina_Bool +elm_genlist_item_hide_get(const Elm_Object_Item *it); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Sets the genlist realization mode. + * + * @remarks By default, genlist disables the realization mode and genlists realize and + * unrealize some items when needed. If the realization mode is on, + * all items are realized when genlist is created and no items are unrealized. + * If this mode is on and the content size is changed, the item size + * changes accordingly. By default, genlist does not change item sizes + * eventhough they can be changed for performance reasons. + * This consumes more memory and decrease performance. So if the application + * appends many items, do not use the realization mode. + * + * @param obj The genlist object + * @param mode The realization mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + */ +EAPI void +elm_genlist_realization_mode_set(Evas_Object *obj, Eina_Bool mode); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Gets the genlist realization mode. + * + * @param obj The genlist object + * @return The realization mode + * (@c EINA_TRUE = on, @c EINA_FALSE = off) + */ +EAPI Eina_Bool +elm_genlist_realization_mode_get(Evas_Object *obj); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Starts reordering for a specific item. it moves by move event. + * + * @param item The genlist item object + */ +EAPI void +elm_genlist_item_reorder_start(Elm_Object_Item *item); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Stop reordering and relocate the item at touch released position. + * @param item The genlist item object + */ +EAPI void +elm_genlist_item_reorder_stop(Elm_Object_Item *item); +/** * @} */ |