This widget is a very simple type of a list widget. It is not to be used to manage a lot of items. For that, genlists are a better option.

The list items can contain a text and two contents (“start”, and “end”). These are set with the elm_object_item_*() functions.

• Adding a List
• Using the List
• Adding Item to the List
• Changing Text Or Icon of an Item
• Retrieving Selected Items
• List Item Operations
• Using List Callbacks

• List Widget API
• Basic List Tutorial

To create a list:

Evas_Object *list = elm_list_add(parent);

This widget implements the scrollable interface, so the scroller widget functions can be used on it. For example, if you want to change the bounce property of the scroller or the scrolling policy:

Evas_Object *list;
 
// Change the scroller policy to fix the scroll only vertically
elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_ON,
ELM_SCROLLER_POLICY_OFF);
// Enable bounce effect when the list reaches the upper and lower limits
elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);

The elm_list_multi_select_set() function can be called to enable multi-selection of items. Each time an item is clicked, the state changes to “selected”.

Evas_Object *list;
 
// Activate multi selection
elm_list_multi_select_set(list, EINA_TRUE);

Items are added with elm_list_item_append() or elm_list_item_prepend(). Here an example of adding ten items with text and one icon on the front: The last two arguments are the callback function when the created item is clicked and the data passed to the callback function.

Evas_Object *list;
int i;
 
// This function is called when the list item is selected
static void
_selected_item_cb(void *data, Evas_Object *obj, void *event_info)
{
   Elm_Object_Item *list_it = elm_list_selected_item_get(obj);
   Eina_Bool selected = elm_list_item_selected_get(list_it);
   printf("item is %s\n", selected? "selected": "unselected");
}
 
for (i = 0; i < 10; i++)
  {
     Evas_Object *ic;
     char tmp[8];
     snprintf(tmp, sizeof(tmp), "Item %02d", i);
     // Create an icon
     ic = elm_icon_add(win);
     // Set the file to the icon file
     elm_image_file_set(ic, "path/to/file", NULL);
     // Add item to the list
     elm_list_item_append(list, tmp, ic, NULL, _selected_item_cb, NULL);
  }

If you want to change the state of an item, you can do it by using all the functions relative to Elm_Object_Item. Each item of the list contains two evas_object. Give those as the third and the fourth arguments when you append or prepend the item in the list. Those evas objects are changed with elm_object_item_part_content_set. The first object is referenced as the “start” object in the theme, whereas the second one is referenced as the “end” object. Give these names when you use the elm_object_item_part_content_set. The label of the item is changed by using elm_object_item_text_set.

Evas_Object *list;
Eina_List *l;
Elm_Object_Item *it;
 
// Retrieve the current selected item
it = elm_list_selected_item_get(list);
if (!it)
   return;
 
ic = elm_icon_add(win);
// Set the file to the icon file
elm_image_file_set(ic, "path/to/file", NULL);
// Change the first icon
elm_object_item_part_content_set(it, "start", ic);
// Change the second icon
elm_object_item_part_content_set(it, "end", ic);
// Change the label
elm_object_item_text_set(it, "I've been selected !");

The list of the currently selected items is retrieved with elm_list_selected_items_get(). If the multiselect mode is false, you can retrieve the only selected item with elm_list_selected_item_get(). For example, this is how to unselect all previously selected items.

Evas_Object *list; Eina_List *l;
Eina_List *selected_items;
// List of Elm_Object_Item
Elm_Object_Item *it;
 
selected_items = elm_list_selected_items_get(list);
EINA_LIST_FOREACH(selected_items, l, it)
   elm_list_item_selected_set(it, EINA_FALSE);

To find out if an item is selected, call elm_list_item_selected_get. This function returns EINA_TRUE if the item is selected, otherwise EINA_FALSE.

Elementary list provides two functions for sliding a list to a specific item. elm_list_item_show shows the item passed as an argument, whereas elm_list_item_bring_in shows the item, but only after animating the slide.

You can go to the item immediately preceding a specific item with the function elm_list_item_prev, or to the one immediately following a specific item with the function elm_list_item_next.

The following example shows selecting the item immediately following the currently selected one, unselecting it, selecting the next one and bringing it to the screen.

Evas_Object *list;
Elm_Object_Item *current, *next;
current = elm_list_selected_item_get(list);
elm_list_item_selected_set(current, EINA_FALSE);
next = elm_list_item_next(current);
elm_list_item_selected_set(next, EINA_TRUE);
elm_list_item_bring_in(next);

This widget emits the following signals, besides the ones sent from Layout:

• “activated” - The user has double-clicked or pressed (enter|return|spacebar) on an item. The event_info parameter is the item that was activated.
• “clicked,double” - The user has double-clicked an item. The event_info parameter is the item that was double-clicked.
• “clicked,right” - The user has right-clicked an item. The event_info parameter is the item that was right-clicked. (since 1.13)
• “selected” - when the user selected an item
• “unselected” - when the user unselected an item
• “longpressed” - an item in the list is long-pressed
• “edge,top” - the list is scrolled until the top edge
• “edge,bottom” - the list is scrolled until the bottom edge
• “edge,left” - the list is scrolled until the left edge
• “edge,right” - the list is scrolled until the right edge
• “highlighted” - an item in the list is highlighted. This is called when the user presses an item or keyboard selection is done so the item is physically highlighted. The event_info parameter is the item that was highlighted.
• “unhighlighted” - an item in the list is unhighlighted. This is called when the user releases an item or keyboard selection is moved so the item is physically unhighlighted. The event_info parameter is the item that was unhighlighted.
• “language,changed” - the program's language changed
• “focused” - When the list has received focus. (since 1.8)
• “unfocused” - When the list has lost focus. (since 1.8)
• “item,focused” - When the list item has received focus. (since 1.10)
• “item,unfocused” - When the list item has lost focus. (since 1.10)

You can register to the “clicked,double” signal with the following code. Note that the currently double-clicked item can be retrieved via the event_info pointer. This code registers to the “double,clicked” signal and unselects the item that has been double-clicked.

Evas_Object *list;
evas_object_smart_callback_add(list, "clicked,double", _double_clicked_cb, data);

// Callback function for the "clicked" signal
// This callback is called when the button is clicked by the user
static void
_double_clicked_cb(void *data, Evas_Object *obj, void  *event_info)
{
   elm_Object_Item *it = event_info;
   elm_list_selected_item_set(it,  EINA_FALSE);
}