Genlist is a container that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint (only the visible items are allocated in the memory).
An item can have 0 or more texts, 0 or more contents, and 0 or more boolean states. This is defined in the Edje item theme style. Genlist looks for data items named respectively âlabelsâ, âcontentsâ, and âstatesâ in the Edje file. The âdefaultâ item style provides one text part (âelm.textâ), two content parts (âelm.swalllow.iconâ and âelm.swallow.endâ) and no state parts.
The following item styles are available:
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.
Genlist widget is added with the elm_genlist_add()
function.
Evas_Object *genlist; genlist = elm_genlist_add(parent);
To save up memory, genlist allocates and deletes items on the go, while the
user is scrolling the list. To enable that, the user creates and fills a
Elm_Genlist_Item_Class
structure that informs the genlist widget which
callbacks to call when an item is created or deleted.
Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new(); itc->item_style = "default"; itc->decorate_item_style = NULL; itc->decorate_all_item_style = NULL; itc->func.text_get = _item_label_get; itc->func.content_get = _item_content_get; itc->func.state_get = _item_state_get; itc->func.del = _item_del;
The item_style
, decorate_item_style
, and decorate_all_item_style
attributes define the names of the item style, the decorate mode item style
and the decorate all item style.
The func
structure contains pointers to functions that are called when an
item is going to be created or deleted. All of them receive a data parameter
that points to the same data passed to the elm_genlist_item_append()
and
related item creation functions, and an obj parameter that points to the
genlist object itself.
text_get | This function receives a PART parameter that is the name string of one of the existing text parts in the Edje group implementing the item's theme. It has to return a string (duplicated with the strdup() function) corresponding to the PART parameter. The caller is in charge of freeing the string when done. |
content_get | The PART parameter is the name string of one of the existing swallow parts in the Edje group. When no content is desired it must return NULL, or otherwise, a valid object handle. The object is deleted by the genlist on its deletion or when the item is âunrealizedâ. |
state_get | The PART parameter is the name string of one of the state parts in the Edje group implementing the item's theme. It returns EINA_FALSE for false/off or EINA_TRUE for true/on. The default is false. Genlists emit a signal to the PART parameter's theming Edje object with âelm,state,xxx,activeâ as âemissionâ and âelmâ as âsourceâ argument, when the state is true. xxx is the name of the (state) part. |
del | This function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation. |
To add an item, several functions can be used. elm_genlist_item_append()
adds an item to the end of the list, or if there is a parent list, to the end
of all the child items of the parent list. elm_genlist_item_prepend()
is
otherwise the same but adds to the beginning of the list or children lists.
elm_genlist_item_insert_before()
inserts an item before the indicated item
and elm_genlist_item_insert_after()
inserts an item after the indicated
item.
The previous functions take a âtypeâ parameter that can be one of the following.
ELM_GENLIST_ITEM_NONE
ELM_GENLIST_ITEM_TREE
ELM_GENLIST_ITEM_GROUP
If ELM_GENLIST_ITEM_TREE
is set, this item is displayed as being able to
expand and have child items. If ELM_GENLIST_ITEM_GROUP
is set, this item is a
group index item that is displayed at the top until the next group appears.
The application clears the list with elm_genlist_clear()
, which deletes
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, move to the item at the top of the list with
elm_genlist_first_item_get()
, which returns the item pointer.
elm_genlist_last_item_get()
moves to the item at the end of the list.
elm_genlist_item_next_get()
and elm_genlist_item_prev_get()
move to
the next and previous items relative to the indicated item. Using these calls
you can go through the entire item list or tree.
elm_genlist_item_parent_get()
gives you the name of the parent item (even to
skip them if needed).
elm_genlist_item_show()
scrolls the scroller to show the desired item as visible.
elm_object_item_data_get()
returns the data pointer set by the item creation functions.
If an item changes (state, boolean, text or content change), use
elm_genlist_item_update()
for the genlist to update the item. Genlist will
re-realize the item and call the functions in the Elm_Genlist_Item_Class
for
it.
Items are manually selected or unselected with
elm_genlist_item_selected_set()
or disabled with
elm_object_item_disabled_set()
. In case there is a tree or a group item,
the elm_genlist_item_expanded_set()
function is used to expand or contract
the item.
By default, the genlist is in single-selection mode: only one item can be
selected at a time. You can use elm_genlist_multi_select_set()
to select
multiple items. In single-selection mode, the
elm_genlist_selected_item_get()
function can be called to retrieve the
selected item. If several items are selected, the
elm_genlist_selected_items_get()
returns a list of the current selected
items.
In the picture below, there is a genlist in multi-selection mode with two items selected (#4 and #5) and one item disabled (#2).
The genlist widget emits the following signals:
âactivatedâ
: The user has double-clicked or pressed (enter | return | spacebar) on an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âclicked,doubleâ
: The user has double-clicked an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âselectedâ
: The user selects an item. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âunselectedâ
: The user unselects an item. event_info in the callback function points at an object of type Elm_Object_Item that contains the activated item.âexpandedâ
: The item is to be expanded with elm_genlist_item_expanded_set()
. This callback fills in the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âcontractedâ
: The item is to be contracted with elm_genlist_item_expanded_set()
. This callback deletes the child items. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âexpand,requestâ
: The user wants to expand a tree branch item. The callback decides if the item can expand (if it has any children) and calls elm_genlist_item_expanded_set()
to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âcontract,requestâ
: The user wants to contract a tree branch item. The callback decides if the item can contract (if it has any children) and calls elm_genlist_item_expanded_set()
to set the state. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.ârealizedâ
: The item is created as a real evas object. event_info in the callback function points at an object of the type Elm_Object_Item, that contains the activated item.âunrealizedâ
: An item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdrag,start,upâ
: The item in the list is dragged (not scrolled) up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdrag,start,downâ
: The item in the list is dragged (not scrolled) down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdrag,start,leftâ
: The item in the list is dragged (not scrolled) left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdrag,start,rightâ
: The item in the list is dragged (not scrolled) right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdrag,stopâ
: The item in the list has stopped being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âdragâ
: The item in the list is being dragged. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âlongpressedâ
: The item is pressed for a certain amount of time. The default specified time is one second. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âscroll,anim,startâ
: The scrolling animation is started. event_info is NULL.âscroll,anim,stopâ
: The scrolling animation is stopped. event_info is NULL.âscroll,drag,startâ
: Dragging the content is started. event_info is NULL.âscroll,drag,stopâ
: Dragging the content is stopped. event_info is NULL.âedge,topâ
: The genlist is scrolled to the top edge. event_info is NULL.âedge,bottomâ
: The genlist is scrolled to the bottom edge. event_info is NULL.âedge,leftâ
: The genlist is scrolled to the left edge. event_info is NULL.âedge,rightâ
: The genlist is scrolled to the right edge. event_info is NULL.âmulti,swipe,leftâ
: The genlist is multi-touch swiped left. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmulti,swipe,rightâ
: The genlist is multi-touch swiped right. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmulti,swipe,upâ
: The genlist is multi-touch swiped up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmulti,swipe,downâ
: The genlist is multi-touch swiped down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmulti,pinch,outâ
: The genlist is multi-touch pinched out. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmulti,pinch,inâ
: The genlist is multi-touch pinched in. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âswipeâ
: The genlist is swiped. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmovedâ
: A genlist item is moved in the reorder mode. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmoved,afterâ
: A genlist item is moved after another item in the reorder mode. To access the relative previous item, use elm_genlist_item_prev_get()
. This signal is called along with the âmovedâ signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âmoved,beforeâ
: A genlist item is moved before another item in the reorder mode. To access the relative previous item, use elm_genlist_item_next_get()
. This signal is called along with the âmovedâ signal. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.âlanguage,changedâ
: The program's language is changed. event_info is NULL.âtree,effect,finishedâ
: A genlist tree effect is finished. event_info is NULL.