A list widget is a container whose children are displayed vertically or horizontally, in order, and can be selected. The list can accept only one or multiple item selections. Also has many modes of items displaying.

A list is a very simple type of list widget. For more robust lists, Genlist should probably be used.

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

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)

Available styles for it are:

"default"

Default content parts of the list items that you can use are:

"start" - A start position object in the list item
"end" - An end position object in the list item Another parts for customized styles are not accepted.

Default text parts of the list items that you can use are:

"default" - A label in the list item Another parts for customized styles are not accepted.

Supported elm_object_item common APIs.

This widget implements the elm-scrollable-interface interface, so that all (non-deprecated) functions for the base Scroller widget also work for lists.

Some calls on the list's API are marked as deprecated, as they just wrap the scrollable widgets counterpart functions. Use the ones we point you to, for each case of deprecation here, instead -- eventually the deprecated ones will be discarded (next major release).

List of examples:

Functions
EINA_DEPRECATED void	elm_list_bounce_set (Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce)
EINA_DEPRECATED void	elm_list_bounce_get (const Evas_Object obj, Eina_Bool h_bounce, Eina_Bool *v_bounce)
EINA_DEPRECATED void	elm_list_scroller_policy_set (Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v)
EINA_DEPRECATED void	elm_list_scroller_policy_get (const Evas_Object obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy *policy_v)
Evas_Object *	elm_list_add (Evas_Object *parent)

Enumeration Type Documentation

enum Elm_List_Mode

Set list's resizing behavior, transverse axis scrolling and items cropping. See each mode's description for more details.

Note:: Default value is ELM_LIST_SCROLL.

Values here don't work as bitmasks -- only one can be chosen at a time.

Enumerator:

ELM_LIST_COMPRESS	The list won't set any of its size hints to inform how a possible container should resize it. Then, if it's not created as a "resize object", it might end with zeroed dimensions. The list will respect the container's geometry and, if any of its items won't fit into its transverse axis, one won't be able to scroll it in that direction.
ELM_LIST_SCROLL	Default value. This is the same as ELM_LIST_COMPRESS, with the exception that if any of its items won't fit into its transverse axis, one will be able to scroll it in that direction.
ELM_LIST_LIMIT	Sets a minimum size hint on the list object, so that containers may respect it (and resize itself to fit the child properly). More specifically, a minimum size hint will be set for its transverse axis, so that the largest item in that direction fits well. This is naturally bound by the list object's maximum size hints, set externally.
ELM_LIST_EXPAND	Besides setting a minimum size on the transverse axis, just like on ELM_LIST_LIMIT, the list will set a minimum size on the longitudinal axis, trying to reserve space to all its children to be visible at a time. . This is naturally bound by the list object's maximum size hints, set externally.
ELM_LIST_LAST	Indicates error if returned by elm_list_mode_get().

Function Documentation

Evas_Object* elm_list_add ( Evas_Object * parent )

Add a new list widget to the given parent Elementary (container) object.

Parameters:

parent The parent object.

Returns:: a new list widget handle or NULL, on errors.

This function inserts a new list widget on the canvas.

Since :: 2.3

Examples:: ctxpopup_example_01.c, index_example_01.c, list_example_01.c, list_example_02.c, list_example_03.c, and track_example_01.c.

EINA_DEPRECATED void elm_list_bounce_get	(	const Evas_Object *	obj,
		Eina_Bool *	h_bounce,
		Eina_Bool *	v_bounce
	)

Get the bouncing behaviour of the internal scroller.

Get whether the internal scroller should bounce when the edge of each axis is reached scrolling.

Parameters:

obj	The list object.
h_bounce	Pointer to store the bounce state of the horizontal axis.
v_bounce	Pointer to store the bounce state of the vertical axis.

Deprecated:: Use elm_scroller_bounce_get() instead.

See also:: elm_scroller_bounce_get(); elm_list_bounce_set()

EINA_DEPRECATED void elm_list_bounce_set	(	Evas_Object *	obj,
		Eina_Bool	h_bounce,
		Eina_Bool	v_bounce
	)

Set bouncing behaviour when the scrolled content reaches an edge.

Tell the internal scroller object whether it should bounce or not when it reaches the respective edges for each axis.

Parameters:

obj	The list object
h_bounce	Whether to bounce or not in the horizontal axis.
v_bounce	Whether to bounce or not in the vertical axis.

Deprecated:: Use elm_scroller_bounce_set() instead.

See also:: elm_scroller_bounce_set()

EINA_DEPRECATED void elm_list_scroller_policy_get	(	const Evas_Object *	obj,
		Elm_Scroller_Policy *	policy_h,
		Elm_Scroller_Policy *	policy_v
	)

Get the scrollbar policy.

See also:: elm_list_scroller_policy_get() for details.

Parameters:

obj	The list object.
policy_h	Pointer to store horizontal scrollbar policy.
policy_v	Pointer to store vertical scrollbar policy.

Deprecated:: Use elm_scroller_policy_get() instead.

EINA_DEPRECATED void elm_list_scroller_policy_set	(	Evas_Object *	obj,
		Elm_Scroller_Policy	policy_h,
		Elm_Scroller_Policy	policy_v
	)

Set the scrollbar policy.

Parameters:

obj	The list object
policy_h	Horizontal scrollbar policy.
policy_v	Vertical scrollbar policy.

This sets the scrollbar visibility policy for the given scroller. ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies respectively for the horizontal and vertical scrollbars.

The both are disabled by default, i.e., are set to ELM_SCROLLER_POLICY_OFF.

Deprecated:: Use elm_scroller_policy_set() instead.

Functions

Enumeration Type Documentation

Function Documentation