Table of Contents

Container Menu

Genlist Container

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).

Table of Contents

Genlist Item Style

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.

Adding a Genlist

Genlist widget is added with the elm_genlist_add() function. 

Evas_Object *genlist;
genlist = elm_genlist_add(parent);

Creating And Deleting Items

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_getThis 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_getThe 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_getThe 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.
delThis function is called when the genlist item is deleted. It deletes any data that is allocated at the item creation.

Managing Items

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.

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.

As a tree, the items are flattened on the list, so 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.

Selection

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.

Calling this function does not show or hide any child of an item (if it is a parent). You must manually delete and create them on the callbacks of the “expanded” or “contracted” signals.

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).

Using Genlist Callbacks

The genlist widget emits the following signals:


A Genlist Example

Container Menu