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:

  • default
  • default_style - The text part is a textblock
  • double_label
  • icon_top_text_bottom
  • group_index
  • 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.

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.

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

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:

  • “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.


A Genlist Example