- Elementary
- Main
- Authors
- Examples
- Files
- Pages
- Types
- Modules

List - Items management

This code places a Elementary list widgets on a window, along with some buttons trigerring actions on it (though its API).

It covers most of elm_list_item functions.

On our `main` function, we are adding a default list with 3 items. We are only setting their labels (second parameter of function elm_list_item_append):

li = elm_list_add(win);
evas_object_size_hint_weight_set(li, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(li, EVAS_HINT_FILL, EVAS_HINT_FILL);
elm_box_pack_end(bx, li);
elm_list_item_append(li, "Item 0", NULL, NULL, NULL, NULL);
elm_list_item_append(li, "Item 1", NULL, NULL, NULL, NULL);
elm_list_item_append(li, "Item 2", NULL, NULL, NULL, NULL);

Next we are adding lots of buttons, each one for a callback function that will realize a task covering part of list items API. Lets check the first one:

bt = elm_button_add(win);
elm_object_text_set(bt, "Prepend item");
evas_object_smart_callback_add(bt, "clicked", _prepend_cb, li);
elm_box_pack_end(hbx, bt);
evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, 0);
evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, 0);
evas_object_show(bt);

We are labeling the button with a task description with elm_object_text_set() and setting a callback function evas_object_smart_callback_add(). Each callback function will have the signature: `static void _task_cb(void *data, Evas_Object *obj, void *event_info)` with the function name varying for each task.

Now let's cover all of them.

Prepending an item:

_prepend_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it;
Evas_Object *li = data;
char label[32];
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_prepend(li, label, NULL, NULL, NULL, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item\n");
}

The item will be placed on the beginning of the list, i.e. it will be the first one.

The first parameter of elm_list_item_prepend() is the list object, that we are receiving as data on our callback function. The second one is a label, the string that will be placed in the center of our item. As we don't wan't icons or callback functions, we can send NULL as third, fourth, fifth and sixth parameters.

Appending an item:

_add_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it;
Evas_Object *li = data;
char label[32];
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_append(li, label, NULL, NULL, NULL, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item\n");
}

Items included with append will be inserted inserted after the last one.

Appending an item with icon:

_add_ic_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it;
Evas_Object *ic, *li = data;
char label[32];
snprintf(label, sizeof(label), "Item %i", counter++);
ic = elm_icon_add(li);
elm_icon_standard_set(ic, "home");
elm_image_resizable_set(ic, EINA_FALSE, EINA_FALSE);
list_it = elm_list_item_append(li, label, ic, NULL, NULL, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item with icon\n");
}

If an icon is required, you can pass it as third parameter on our elm_list_item_append() function. It will be place on the left side of item's label. If an icon is wanted on the right side, it should be passed as fourth parameter.

For more details about how to create icons, look for elm_icon examples Icon example.

Appending an item with callback function for selected:

_sel_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it = event_info;
printf("Selected label: %s\n", elm_object_item_text_get(list_it));
}
static void
_add_func_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it;
Evas_Object *li = data;
char label[32];
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_append(li, label, NULL, NULL, _sel_cb, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item\n");
}

To set a callback function that will be called every time an item is selected, i.e., everytime the list stops with this item in center position, just pass the function as fifth parameter.

Appending an item with callback function for selected with data:

_sel_data_cb(void *data, Evas_Object *obj, void *event_info)
{
char *content = data;
Elm_Object_Item *list_it = event_info;
printf("Selected label: %s with data: %s\n",
elm_object_item_text_get(list_it), content);
}
static void
_free_data(void *data, Evas_Object *obj, void *event_info)
{
free(data);
}
static void
_add_data_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *list_it;
Evas_Object *li = data;
char label[32];
char *content = malloc(sizeof(char) * 32);
snprintf(content, 32, "Item content %i", counter);
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_append(li, label, NULL, NULL, _sel_data_cb, content);
elm_list_go(li);
if (!list_it)
{
printf("Error adding item\n");
return;
}
elm_object_item_del_cb_set(list_it, _free_data);
}

If the callback function request an extra data, it can be attached to our item passing a pointer for data as sixth parameter. Our function _sel_data_cb will receive it as `void *data` .

If you want to free this data, or handle that the way you need when the item is deleted, set a callback function for that, with elm_object_item_del_cb_set().

As you can see we check if `it` is not `NULL` after appending it. If an error happens, we won't try to set a function for it.

Deleting an item:

_del_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
elm_object_item_del(selected_item);
elm_list_go(li);
}

To delete an item we simple need to call elm_object_item_del() with a pointer for such item.

If you need, you can get selected item with elm_list_selected_item_get(), that will return a pointer for it.

Unselecting an item:

_unselect_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
elm_list_item_selected_set(selected_item, EINA_FALSE);
}

To select an item, you should call elm_list_item_selected_set() passing `EINA_TRUE`, and to unselect it, `EINA_FALSE`.

Printing all items:

_print_cb(void *data, Evas_Object *obj, void *event_info)
{
const Eina_List *l, *items;
Elm_Object_Item *list_it;
Evas_Object *li = data;
items = elm_list_items_get(li);
EINA_LIST_FOREACH(items, l, list_it)
printf("%s\n", elm_object_item_text_get(list_it));
}

Clearing the list:

_clear_cb(void *data, Evas_Object *obj, void *event_info)
{
Evas_Object *li = data;
elm_list_clear(li);
}

Selecting the next item:

_select_next_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item, *next_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
next_item = elm_list_item_next(selected_item);
if (next_item)
elm_list_item_selected_set(next_item, EINA_TRUE);
}

Inserting after an item:

_insert_after_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item, *list_it;
Evas_Object *li = data;
char label[32];
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_insert_after(li, selected_item, label, NULL, NULL,
NULL, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item\n");
}

Selecting the previous item:

_select_prev_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item, *prev_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
prev_item = elm_list_item_prev(selected_item);
if (prev_item)
elm_list_item_selected_set(prev_item, EINA_TRUE);
}

Inserting before an item:

_insert_before_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item, *list_it;
Evas_Object *li = data;
char label[32];
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
snprintf(label, sizeof(label), "Item %i", counter++);
list_it = elm_list_item_insert_before(li, selected_item, label, NULL, NULL,
NULL, NULL);
elm_list_go(li);
if (!list_it)
printf("Error adding item\n");
}

If a separator is required, just set an item as such:

_set_separator_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
elm_list_item_separator_set(selected_item, EINA_TRUE);
elm_list_go(li);
}

Also an item can be disabled, and the user won't be allowed to (un)select it:

_disable_cb(void *data, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *selected_item;
Evas_Object *li = data;
selected_item = elm_list_selected_item_get(li);
if (!selected_item) return;
elm_object_item_disabled_set(selected_item, EINA_TRUE);
}

See the full list_example_03.c code, whose window should look like this picture:

Copyright ©2000-2014 Enlightenment.org - Samsung Electronics supports the EFL Documentation Project - Generated Wed Jan 8 2014 20:51:07