An index widget gives you an index for fast access to whichever group of other UI items one might have.

It's a list of text items (usually letters, for alphabetically ordered access).

Index widgets are by default hidden and just appear when the user clicks over it's reserved area in the canvas. In its default theme, it's an area of one finger wide on the right side of the index widget's container.

When items on the index are selected, smart callbacks get called, so that its user can make other container objects to show a given area or child object depending on the index item selected. You would probably be using an index together with lists or generic lists.

This widget inherits from the Layout one, so that all the functions acting on it also work for index objects.

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

"changed" - When the selected index item changes. event_info is the selected item's data pointer.
"delay,changed" - When the selected index item changes, but after a small idling period. event_info is the selected item's data pointer.
"selected" - When the user releases a mouse button and selects an item. event_info is the selected item's data pointer.
"level,up" - When the user moves a finger from the first level to the second level.
"level,down" - When the user moves a finger from the second level to the first level.
"language,changed" - The program's language is changed.

The "delay,changed" event is so that it waits for a small period of time before actually reporting those events and, moreover, just the last event happening on those time frames is actually reported.

Functions
Evas_Object *	elm_index_add (Evas_Object *parent)
	Adds a new index widget to the given parent Elementary (container) object.
void	elm_index_autohide_disabled_set (Evas_Object *obj, Eina_Bool disabled)
	Enables or disables the auto hiding feature for a given index widget.
Eina_Bool	elm_index_autohide_disabled_get (const Evas_Object *obj)
	Gets whether the auto hiding feature is enabled for a given index widget.
void	elm_index_item_level_set (Evas_Object *obj, int level)
	Sets the items level for a given index widget.
int	elm_index_item_level_get (const Evas_Object *obj)
	Gets the items level set for a given index widget.
void	elm_index_item_selected_set (Elm_Object_Item *it, Eina_Bool selected)
	Sets the selected state of an item.
Elm_Object_Item *	elm_index_selected_item_get (const Evas_Object *obj, int level)
	Gets the last selected item, for a given index widget.
Elm_Object_Item *	elm_index_item_append (Evas_Object obj, const char letter, Evas_Smart_Cb func, const void *data)
	Appends a new item on a given index widget.
Elm_Object_Item *	elm_index_item_prepend (Evas_Object obj, const char letter, Evas_Smart_Cb func, const void *data)
	Prepends a new item on a given index widget.
Elm_Object_Item *	elm_index_item_insert_after (Evas_Object obj, Elm_Object_Item after, const char letter, Evas_Smart_Cb func, const void data)
	Inserts a new item into the index object after the item after.
Elm_Object_Item *	elm_index_item_insert_before (Evas_Object obj, Elm_Object_Item before, const char letter, Evas_Smart_Cb func, const void data)
	Inserts a new item into the index object before the item before.
Elm_Object_Item *	elm_index_item_sorted_insert (Evas_Object obj, const char letter, Evas_Smart_Cb func, const void *data, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func)
	Inserts a new item into the given index widget, using cmp_func function to sort items (by item handles).
Elm_Object_Item *	elm_index_item_find (Evas_Object obj, const void data)
	Finds a given index widget's item, using item data.
void	elm_index_item_clear (Evas_Object *obj)
	Removes all items from a given index widget.
void	elm_index_level_go (Evas_Object *obj, int level)
	Flushes the changes made to the index items so they work correctly.
const char *	elm_index_item_letter_get (const Elm_Object_Item *item)
	Gets the letter (string) set on a given index widget item.
void	elm_index_indicator_disabled_set (Evas_Object *obj, Eina_Bool disabled)
	Sets the indicator to be disabled.
Eina_Bool	elm_index_indicator_disabled_get (const Evas_Object *obj)
	Gets the value of the indicator's disabled status.
void	elm_index_horizontal_set (Evas_Object *obj, Eina_Bool horizontal)
	Enables or disables the horizontal mode on the index object.
Eina_Bool	elm_index_horizontal_get (const Evas_Object *obj)
	Gets a value that indicates whether the horizontal mode is enabled.
void	elm_index_delay_change_time_set (Evas_Object *obj, double delay_change_time)
	Sets a delay change time for the index object.
double	elm_index_delay_change_time_get (const Evas_Object *obj)
	Gets a delay change time for the index object.
void	elm_index_omit_enabled_set (Evas_Object *obj, Eina_Bool enabled)
	Enables or disables the omit feature for a given index widget.
Eina_Bool	elm_index_omit_enabled_get (const Evas_Object *obj)
	Gets whether the omit feature is enabled for a given index widget.

Function Documentation

Evas_Object* elm_index_add ( Evas_Object * parent )

Adds a new index widget to the given parent Elementary (container) object.

This function inserts a new index widget on the canvas.

Since :: 2.3.1

Parameters:

[in] parent The parent object

Returns:: A new index widget handle, otherwise NULL in case of an error

Eina_Bool elm_index_autohide_disabled_get ( const Evas_Object * obj )

Gets whether the auto hiding feature is enabled for a given index widget.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: EINA_TRUE if auto hiding is disabled, otherwise EINA_FALSE

See also:: elm_index_autohide_disabled_set()

void elm_index_autohide_disabled_set	(	Evas_Object *	obj,
		Eina_Bool	disabled
	)

Enables or disables the auto hiding feature for a given index widget.

Since :: 2.3.1

Parameters:

[in]	obj	The index object
[in]	disabled	If `EINA_TRUE` auto hiding is disabled, otherwise `EINA_FALSE` to enable it

See also:: elm_index_autohide_disabled_get()

double elm_index_delay_change_time_get ( const Evas_Object * obj )

Gets a delay change time for the index object.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: The delay change time in seconds

See also:: elm_index_delay_change_time_set

void elm_index_delay_change_time_set	(	Evas_Object *	obj,
		double	delay_change_time
	)

Sets a delay change time for the index object.

Since :: 2.3.1

Remarks:: The delay time is 0.2 sec by default.

Parameters:

[in]	obj	The index object
[in]	delay_change_time	The delay change time to set.

See also:: elm_index_delay_change_time_get

Eina_Bool elm_index_horizontal_get ( const Evas_Object * obj )

Gets a value that indicates whether the horizontal mode is enabled.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: EINA_TRUE means the horizontal mode selection is enabled, otherwise EINA_FALSE indicates that it's disabled
If obj is NULL, EINA_FALSE is returned.

See also:: elm_index_horizontal_set()

void elm_index_horizontal_set	(	Evas_Object *	obj,
		Eina_Bool	horizontal
	)

Enables or disables the horizontal mode on the index object.

Since :: 2.3.1

Remarks:: The vertical mode is set by default.; On the horizontal mode items are displayed on the index from left to right, instead of from top to bottom. Also, the index scrolls horizontally.

Parameters:

[in]	obj	The index object
[in]	horizontal	If `EINA_TRUE` the horizontal is enabled, otherwise `EINA_FALSE` to disable it, i.e., to enable the vertical mode It's an area of one finger wide at the bottom side of the index widget's container.

See also:: elm_index_horizontal_get()

Eina_Bool elm_index_indicator_disabled_get ( const Evas_Object * obj )

Gets the value of the indicator's disabled status.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: EINA_TRUE if the indicator is disabled, otherwise EINA_FALSE

See also:: elm_index_indicator_disabled_set()

void elm_index_indicator_disabled_set	(	Evas_Object *	obj,
		Eina_Bool	disabled
	)

Sets the indicator to be disabled.

Since :: 2.3.1

Remarks:: In the Index widget, Indicator notes the popup text, which shows that a letter has been selected.

Parameters:

[in]	obj	The index object
[in]	disabled	If `EINA_TRUE` the indicator is disabled, otherwise `EINA_FALSE` to enable it

See also:: elm_index_indicator_disabled_get()

Elm_Object_Item* elm_index_item_append	(	Evas_Object *	obj,
		const char *	letter,
		Evas_Smart_Cb	func,
		const void *	data
	)

Appends a new item on a given index widget.

Since :: 2.3.1

Remarks:: Despite the fact that the most common usage of the letter argument is for single char strings, one could use arbitrary strings as index entries.; it is the pointer returned back on the "changed", "delay,changed", and "selected" smart events.

Parameters:

[in]	obj	The index object
[in]	letter	The letter under which the item should be indexed
[in]	func	The function to call when the item is selected
[in]	data	The item data to set for the index's item

Returns:: A handle to the item added, otherwise NULL in case of an error

void elm_index_item_clear ( Evas_Object * obj )

Removes all items from a given index widget.

Since :: 2.3.1

Remarks:: If deletion callbacks are set, via elm_object_item_del_cb_set(), that callback function is called for each item in obj.

Parameters:

[in] obj The index object

Elm_Object_Item* elm_index_item_find	(	Evas_Object *	obj,
		const void *	data
	)

Finds a given index widget's item, using item data.

Since :: 2.3.1

Parameters:

[in]	obj	The index object
[in]	data	The item data pointed to by the desired index item

Returns:: The index item handle if found, otherwise NULL

Elm_Object_Item* elm_index_item_insert_after	(	Evas_Object *	obj,
		Elm_Object_Item *	after,
		const char *	letter,
		Evas_Smart_Cb	func,
		const void *	data
	)

Inserts a new item into the index object after the item after.

Since :: 2.3.1

Remarks:: Despite the fact that the most common usage of the letter argument is for single char strings, one could use arbitrary strings as index entries.; it is the pointer returned back on the "changed", "delay,changed", and "selected" smart events.; If relative is NULL this function behaves like elm_index_item_append().

Parameters:

[in]	obj	The index object
[in]	after	The index item to insert after
[in]	letter	The letter under which the item should be indexed
[in]	func	The function to call when the item is clicked
[in]	data	The item data to set for the index's item

Returns:: A handle to the item added, otherwise NULL in case of an error

Elm_Object_Item* elm_index_item_insert_before	(	Evas_Object *	obj,
		Elm_Object_Item *	before,
		const char *	letter,
		Evas_Smart_Cb	func,
		const void *	data
	)

Inserts a new item into the index object before the item before.

Since :: 2.3.1

Remarks:: Despite that fact that the most common usage of the letter argument is for single char strings, one could use arbitrary strings as index entries.; it is the pointer returned back on the "changed", "delay,changed", and "selected" smart events.; If relative is NULL this function behave like elm_index_item_prepend().

Parameters:

[in]	obj	The index object
[in]	before	The index item to insert after
[in]	letter	The letter under which the item should be indexed
[in]	func	The function to call when the item is clicked
[in]	data	The item data to set for the index's item

Returns:: A handle to the item added, otherwise NULL in case of an error

const char* elm_index_item_letter_get ( const Elm_Object_Item * item )

Gets the letter (string) set on a given index widget item.

Since :: 2.3.1

Parameters:

[in] item The index item handle

Returns:: The letter string set on it

int elm_index_item_level_get ( const Evas_Object * obj )

Gets the items level set for a given index widget.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: 0 or 1, which are the levels that obj might be at

See also:: elm_index_item_level_set()

void elm_index_item_level_set	(	Evas_Object *	obj,
		int	level
	)

Sets the items level for a given index widget.

Since :: 2.3.1

Parameters:

[in]	obj	The index object
[in]	level	`0` or `1`, the currently implemented levels

See also:: elm_index_item_level_get()

Elm_Object_Item* elm_index_item_prepend	(	Evas_Object *	obj,
		const char *	letter,
		Evas_Smart_Cb	func,
		const void *	data
	)

Prepends a new item on a given index widget.

Since :: 2.3.1

Remarks:: Despite the fact that the most common usage of the letter argument is for single char strings, one could use arbitrary strings as index entries.; it is the pointer returned back on the "changed", "delay,changed", and "selected" smart events.

Parameters:

[in]	obj	The index object
[in]	letter	The letter under which the item should be indexed
[in]	func	The function to call when the item is selected
[in]	data	The item data to set for the index's item

Returns:: A handle to the item added, otherwise NULL in case if an error

void elm_index_item_selected_set	(	Elm_Object_Item *	it,
		Eina_Bool	selected
	)

Sets the selected state of an item.

This sets the selected state of the given item it. EINA_TRUE for selected, EINA_FALSE for not selected.

Since :: 2.3.1

Remarks:: If a new item is selected the previously selected is unselected. Previously selected item can be obtained with function elm_index_selected_item_get().; Selected items are highlighted.

Parameters:

[in]	it	The index item
[in]	selected	The selected state

See also:: elm_index_selected_item_get()

Elm_Object_Item* elm_index_item_sorted_insert	(	Evas_Object *	obj,
		const char *	letter,
		Evas_Smart_Cb	func,
		const void *	data,
		Eina_Compare_Cb	cmp_func,
		Eina_Compare_Cb	cmp_data_func
	)

Inserts a new item into the given index widget, using cmp_func function to sort items (by item handles).

Since :: 2.3.1

Remarks:: Despite the fact that the most common usage of the letter argument is for single char strings, one could use arbitrary strings as index entries.; it is the pointer returned back on the "changed", "delay,changed", and "selected" smart events.

Parameters:

[in]	obj	The index object
[in]	letter	The letter under which the item should be indexed
[in]	func	The function to call when the item is clicked
[in]	data	The item data to set for the index's item
[in]	cmp_func	The comparing function to be used to sort index items by index item handles
[in]	cmp_data_func	A callback function to be called for the sorting of index items by item data) It is used when cmp_func returns `0` (equality), which means an index item with provided item data already exists To decide which data item should be pointed to by the index item in question, cmp_data_func is used If cmp_data_func returns a non-negative value, the previous index item data is replaced by the given it pointer If the previous data needs to be freed, it should be done by the cmp_data_func function, because all references to it are lost If this function is not provided (`NULL` is given), index items are duplicated, if cmp_func returns `0`.

Returns:: A handle to the item added, otherwise NULL in case of an error

void elm_index_level_go	(	Evas_Object *	obj,
		int	level
	)

Flushes the changes made to the index items so they work correctly.

This flushes any changes made to items indicating that the object is ready to go. You should call this before any expected changes work. This is similar to elm_list_go().

Since :: 2.3.1

Remarks:: If not called, it won't display the index properly.

Parameters:

[in]	obj	The index object
[in]	level	The index level (either `0` or `1`) where changes were made

Eina_Bool elm_index_omit_enabled_get ( const Evas_Object * obj )

Gets whether the omit feature is enabled for a given index widget.

Since :: 2.3.1

Parameters:

[in] obj The index object

Returns:: EINA_TRUE if the omit feature is enabled, otherwise EINA_FALSE

See also:: elm_index_omit_enabled_set()

void elm_index_omit_enabled_set	(	Evas_Object *	obj,
		Eina_Bool	enabled
	)

Enables or disables the omit feature for a given index widget.

Since :: 2.3.1

Parameters:

[in]	obj	The index object
[in]	enabled	If `EINA_TRUE` the omit feature is enabled, otherwise `EINA_FALSE` to disable it

See also:: elm_index_omit_enabled_get()

Elm_Object_Item* elm_index_selected_item_get	(	const Evas_Object *	obj,
		int	level
	)

Gets the last selected item, for a given index widget.

Since :: 2.3.1

Parameters:

[in]	obj	The index object
[in]	level	`0` or `1`, the currently implemented levels

Returns:: The last item selected on obj (or NULL on errors)

Functions

Function Documentation