Index widget example 1

This code places an Elementary index widget on a window, which also has a very long list of arbitrary strings on it.

The list is sorted alphabetically and the index will be used to index the first items of each set of strings beginning with an alphabet letter.

Below the list are some buttons, which are there just to exercise some index widget's API.

Here's how we instantiate it:

where we're showing also the list being created. Note that we issue elm_win_resize_object_add() on the index, so that it's set to have the whole window as its container. Then, we have to populate both list and index widgets:

for (i = 0; i < (sizeof(dict) / sizeof(dict[0])); i++)
{
lit = elm_list_item_append(list, dict[i], NULL, NULL, NULL, NULL);
if (curr != dict[i][0])
{
Elm_Object_Item *index_it;
char buf[32];
curr = dict[i][0];
/* indexing by first letters */
snprintf(buf, sizeof(buf), "%c", curr);
index_it = elm_index_item_append(id, buf, NULL, lit);
/* this is here just to demostrate the API call */
(void)elm_index_item_find(id, lit);
assert(elm_index_item_find(id, lit) == index_it);
elm_object_item_del_cb_set(index_it, _index_item_del);
}
elm_object_item_del_cb_set
void elm_object_item_del_cb_set(Elm_Widget_Item *obj, Evas_Smart_Cb del_cb)
Set the function to be called when an item from the widget is freed.
Definition elm_widget_item_eo.legacy.c:231
Elm_Object_Item
Eo Elm_Object_Item
An Elementary Object item handle.
Definition elm_object_item.h:6
elm_index_item_find
Elm_Widget_Item * elm_index_item_find(Elm_Index *obj, const void *data)
Find a given index widget's item, using item data.
Definition elm_index_eo.legacy.c:99
elm_index_item_append
Elm_Widget_Item * elm_index_item_append(Elm_Index *obj, const char *letter, Evas_Smart_Cb func, const void *data)
Append a new item on a given index widget.
Definition elm_index_eo.legacy.c:111
elm_list_item_append
Elm_Widget_Item * elm_list_item_append(Elm_List *obj, const char *label, Efl_Canvas_Object *icon, Efl_Canvas_Object *end, Evas_Smart_Cb func, const void *data)
Append a new item to the list object.
Definition elm_list_eo.legacy.c:129
}

The strings populating the list come from a file

static const char *dict[] = \
{
#include "dict.txt"
};

We use the `curr` char variable to hold the last initial letter seen on that ordered list of strings, so that we're able to have an index item pointing to each list item starting a new letter "section". Note that our index item data pointers will be the list item handles. We are also setting a callback function to index items deletion events:

static void
_index_item_del(void *data, Evas_Object *obj EINA_UNUSED, void *event_info)
{
printf("Deleting index node (%s). Comparing index "
"item data reported via callback with the one returned by "
"index's API on items: %s.\n",
elm_index_item_letter_get(event_info),
data == elm_object_item_data_get(event_info) ? "OK" :
"FAIL, something went wrong");
}
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition eina_types.h:339
elm_object_item_data_get
void * elm_object_item_data_get(const Elm_Object_Item *it)
Get the data associated with an object item.
Definition efl_ui_widget.c:3796
elm_index_item_letter_get
const char * elm_index_item_letter_get(const Elm_Index_Item *obj)
Get the letter (string) set on a given index widget item.
Definition elm_index_item_eo.legacy.c:15
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition Evas_Common.h:185

There, we show you that the `event_info` pointer will contain the item in question's data, i.e., a given list item's pointer. Because item data is also returned in the `data` argument on `Evas_Smart_Cb` functions, those two pointers must have the same values. On this deletion callback, we're deleting the referred list item too, just to exemplify that anything could be done there.

Next, we hook to two smart events of the index object:

/* "delay,changed" hook */
static void
_index_changed(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED, void *event_info)
{
elm_list_item_bring_in(elm_object_item_data_get(event_info));
}
static void
_index_selected(void *data EINA_UNUSED, Evas_Object *obj, void *event_info)
{
Elm_Object_Item *lit = event_info;
printf("New index item selected. Comparing item reported"
" via callback with the selection returned by the API: "
"%s.\n", lit == elm_index_selected_item_get(obj, 0) ? "OK" :
"FAIL, something went wrong");
}
elm_index_selected_item_get
Elm_Widget_Item * elm_index_selected_item_get(const Elm_Index *obj, int level)
Returns the last selected item, for a given index widget.
Definition elm_index_eo.legacy.c:117

Check that, whenever one holds the mouse pressed over a given index letter for some time, the list beneath it will roll down to the item pointed to by that index item. When one releases the mouse button, the second callback takes place. There, we check that the reported item data, on `event_info`, is the same reported by elm_index_selected_item_get(), which gives the last selection's data on the index widget.

The first of the three buttons that follow will call elm_index_autohide_disabled_set(), thus showing the index automatically for you, if it's not already visible, what is checked with elm_index_autohide_disabled_get(). The second button will exercise deletion of index item objects, by the following code:

/* delete an index item */
static void
_item_del(void *data, Evas_Object *obj EINA_UNUSED, void *event_info EINA_UNUSED)
{
Elm_Object_Item *it = elm_index_selected_item_get(data, 0);
if (!it) return;
printf("Deleting last selected index item, which had letter"
" %s (pointing to %p)\n", elm_index_item_letter_get(it),
elm_object_item_data_get(it));
elm_object_item_del(it);
elm_index_level_go(data, 0);
}
elm_object_item_del
void elm_object_item_del(Eo *obj)
Delete the given item.
Definition elm_main.c:2017
elm_index_level_go
void elm_index_level_go(Elm_Index *obj, int level)
Flush the changes made to the index items so they work correctly.
Definition elm_index_eo.legacy.c:75

It will get the last index item selected's data and find the respective index item handle(Elm_Object_Item) with elm_index_item_find(). We need the latter to query the indexing letter string from, with elm_index_item_letter_get(). Next, comes the deletion itself, which will also trigger the `_index_item_del` callback function, as said above.

The third button, finally, will exercise elm_index_item_clear(), which will delete all of the index's items.

This is how the example program's window looks like with the index widget hidden:

When it's shown, it's like the following figure:

See the full source code for this example.