Genlist

This feature is supported in mobile applications only.

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

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

Figure: Genlist component

Figure: Genlist hierarchy

Adding a Genlist Component

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

Evas_Object *genlist, *parent;
genlist = elm_genlist_add(parent);

Defining the Genlist and Item Style

The genlist can have 2 styles, for itself or for its items.

The genlist style determines the figure or characteristics of the entire scrollable area. The following genlist styles are available:

• default

  Same as effect.

• effect

  When the genlist reaches its edge during scrolling, it shows an effect.

• no_effect

  The genlist has no effect when it reaches an edge.

• handler

  Enables a scrollbar that eases scrolling through the whole list.

• solid/default
• solid/effect
• solid/no_effect
• solid/handler

In Tizen 2.4, the genlist items have a gradient opacity from the top to the bottom rather than an explicit divider. Each item is identified by its color made by blending its opacity and background color (or image).

The solid prefix in a genlist style name means that genlist items have a divider and background color. The following example sets a genlist with a solid background color.

elm_object_style_set(genlist, "solid/default");

The genlist item style determines the number of parts for text and content, and their arrangement within the item. For example, a default style item has 1 text part (elm.text), and 2 content parts (elm.swallow.icon and elm.swallow.end).

The following item styles are available:

• default
• full
• one_icon
• end_icon
• group_index
• double_label

The following item styles are supported since Tizen 2.4:

• type1
• type2
• multiline
• group_index/expandable

The following figures show examples of the item styles.

Figure: Default item style

Figure: end_icon item style

Figure: double_label item style

Figure: type1 item style

Figure: type2 item style

Figure: multiline item style

Figure: group_index item style

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

Creating and Deleting Items

To save up memory and speed up processing when many items exist, the genlist has the concept of realization when managing items. It means that a genlist item creates its text and content when the item shows up on the display (realize), and frees them when the item is scrolled out of the screen (unrealize). Text and content are retrieved by calling the text_get and content_get functions defined in the genlist item class.

You can use the Elm_Genlist_Item_Class for the following purposes:

• Setting the item style
• Registering callback functions for item realization
• Registering a callback function for item deletion

Elm_Genlist_Item_Class *itc = elm_genlist_item_class_new();
int i;

itc->item_style = "default"; 
itc->func.text_get = _item_label_get;
itc->func.content_get = _item_content_get;
itc->func.del = _item_del;

for (i = 0; i < 10; i++)
{
   elm_genlist_item_append(genlist, // Genlist object
                           itc, // Genlist item class
                           (void *)i, // Item data
                           NULL, // Parent item
                           ELM_GENLIST_ITEM_NONE, // Item type
                           _item_select, // Select callback
                           (void *)i); // Callback data
}
Elm_genlist_item_class_free(itc);

The func structure in the genlist item class contains pointers to functions that are called when an item is going to be realized or deleted. All of them receive item data (third parameter of the elm_genlist_item_append() function) as their first parameter and the genlist object itself as the second parameter.

The genlist item class must be freed manually with the elm_genlist_item_class_free() function after appending items is finished. To delete a genlist item, use the elm_object_item_del() function. You can also use the elm_genlist_clear() function to clear all items. If a genlist object is deleted by the evas_object_del() function, all items are deleted automatically. On item deletion, the del function in the item class is called.

• text_get

  When a genlist item becomes realized, the text_get function is called repeatedly for all text parts in that item. This function can return text with the strdup() function when the desired part is found. After the text is set to the part, it is freed automatically (do not free it manually).

  static char *
  _item_label_get(void *data, Evas_Object *obj, const char *part)
  {
     if (!strcmp(part, "elm.text"))
        return strdup("text");
     else return NULL;
  }
  

• content_get

  As the text_get function, the content_get function is also called repeatedly for all swallow parts in the item. When no content is desired, it must return NULL, or a valid object handle to be set. The object is deleted by the genlist on its deletion or when the item is unrealized.

  static Evas_Object *
  _item_content_get(void *data, Evas_Object *obj, const char *part)
  {
     if (!strcmp(part, "elm.swallow.icon"))
     {
        Evas_Object *img = elm_image_add(obj);
        elm_image_file_Set(img, "sample.png", NULL);
  
        return img;
     }
     else return NULL;
  } 
  

• del

  This function is called when the genlist item is deleted. It deletes any data that has been allocated at the item creation.

  static void
  _item_del(void *data, Evas_Object *obj)
  {
     printf("item(%d) is now deleted", (int) data);
  }
  

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 parent list. 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.

    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 genlist to the desired item.

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

• Update items:

  If an item changes (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.

  You can also use the elm_genlist_item_fields_update() function to update only specific parts:

  • ELM_GENLIST_ITEM_FIELD_TEXT
  • ELM_GENLIST_ITEM_FIELD_CONTENT
• Change the genlist and item size:

  The genlist and item size can be changed by the elm_genlist_mode_set() function:

  • ELM_LIST_COMPRESS

    The genlist respects its container's geometry. Even though there are any items exceeding the genlist in transverse axis, the genlist is not scrollable in that direction.

  • ELM_LIST_SCROLL

    Same as ELM_LIST_COMPRESS, but if there are any items exceeding the genlist in transverse axis, genlist is scrollable in that direction.

  • ELM_LIST_LIMIT

    Sets a minimum size hint on the list object, so that containers can respect it. A minimum size hint is set for its transverse axis, so that the largest item in that direction fits well.

  • ELM_LIST_EXPAND

    Besides setting a minimum size on the transverse axis, like ELM_LIST_LIMIT, the list sets a minimum size on the longitudinal axis, trying to reverse space to all its children to be visible at a time.

  The elm_genlist_homogeneous_set() function makes all items the same height, and increases the performance by reducing size calculation during genlist item creation.

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 item, the elm_genlist_item_expanded_set() function is used to expand or contract the item.

static void
select_cb(void *data, Evas_Object *obj, void *event_info)
{
   Elm_Object_Item *it = (Elm_Object_Item *)event_info;
   // Cancel select and highlight when item is selected
   elm_genlist_item_selected_set(it, EINA_FALSE);
}

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 currently selected items.

In the following figure, the 3rd item is disabled and 5th and 6th item are selected in the multi-selection mode. (The check component works independently of the genlist item; unless it receives an event directly, you must change its state manually in the selected callback of the genlist item.)

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.
• scroll: The scrolling is ongoing.
• 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.
• pressed: The genlist item is pressed by mouse down. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• released: The genlist item is released by mouse up. event_info in the callback function points at an object of the type Elm_Object_Item that contains the activated item.