Genlist

This feature is supported in wearable applications only.

Genlist is a UI component that displays a scrollable list of items. It allows a lot of entries while being fast and has a low memory footprint, as only the visible items are allocated in the memory.

For more information, see Creating Wearable Genlists and the Genlist API.

Figure: Genlist component

Figure: Genlist hierarchy

Defining the 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 1 text part (elm.text), 2 content parts (elm.swallow.icon and elm.swallow.end) and no state parts.

The following item styles are available:

• default
• groupindex
• 1text
• 1text.1icon
• 2text
• 2text.1
• 1text.1icon.divider
• 1text.1icon.1
• 2text.1icon.1
• multiline/1text
• multiline/2text

The following figures show examples of the item styles.

Figure: 1text item style

Figure: 1text.1icon.1 item style

Figure: 2text.1icon.1 item style

For more information on creating a new genlist item style, see Customizing Components.

Adding a Genlist Component

To add a genlist component, use the elm_genlist_add() function:

Evas_Object *genlist, *parent;
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, create and fill a Elm_Genlist_Item_Class structure that informs the genlist component 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() function 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 parameter, 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.

Managing Items

To manage items:

• Add items:

  To add an item, several functions can be used. The elm_genlist_item_append() function 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. The elm_genlist_item_prepend() function is otherwise the same but adds to the beginning of the list or children lists. The elm_genlist_item_insert_before() function inserts an item before the indicated item and the elm_genlist_item_insert_after() function inserts an item after the indicated item.

  The functions take one of the following type parameters:

  • ELM_GENLIST_ITEM_NONE
  • ELM_GENLIST_ITEM_TREE

    The item is displayed as being able to expand and have child items. In the wearable profile, the genlist tree item style is not supported yet, so the following example image is for the mobile profile.

    Figure: Genlist tree

    

  • ELM_GENLIST_ITEM_GROUP

    The item is a group index item that is displayed at the top until the next group appears.

• Clear the list:

  The application clears the list with the elm_genlist_clear() function, which deletes all the items in the list. The elm_object_item_del() function deletes a specific item. The elm_genlist_item_subitems_clear() function clears all items that are children of the indicated parent item.

• Inspect list elements:

  To help inspect the list items, move to the item at the top of the list with the elm_genlist_first_item_get() function, which returns the item pointer. The elm_genlist_last_item_get() function moves to the item at the end of the list. The elm_genlist_item_next_get() and elm_genlist_item_prev_get() functions 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.

  Note
  As a tree, the items are flattened on the list, so the elm_genlist_item_parent_get() function gives you the name of the parent item (even to skip them if needed).

  The elm_genlist_item_show() function scrolls the scroller to show the desired item as visible.

  The elm_object_item_data_get() function returns the data pointer set by the item creation functions.

• Update items:

  If an item changes (state, boolean, text or content change), use the elm_genlist_item_update() function for the genlist to update the item. Genlist re-realizes the item and calls the functions in the _Elm_Genlist_Item_Class class for it.

Selecting Items

Items are manually selected or deselected with the elm_genlist_item_selected_set() function or disabled with the elm_object_item_disabled_set() function. 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.

Note
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 the elm_genlist_multi_select_set() function to select multiple items. In the 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() function returns a list of the current selected items.

In the following figure, the first item is disabled and third and fourth item are selected in the multi-selection mode.

Figure: Genlist item selection highlight

Using Genlist Callbacks

The genlist component emits the following signals:

• activated: The item is double-clicked or pressed (enter | return | spacebar). event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• clicked,double: The item is double-clicked. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• selected: The item is selected. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• unselected: The item is unselected. 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 the elm_genlist_item_expanded_set() function. 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 the elm_genlist_item_expanded_set() function. 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 the elm_genlist_item_expanded_set() function 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 the elm_genlist_item_expanded_set() function 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 the elm_genlist_item_prev_get() function. 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 the elm_genlist_item_next_get() function. 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.

Note
Except as noted, this content is licensed under LGPLv2.1+.