List

../_images/list-preview.png

Widget description

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 items selection. 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.

Emitted signals

  • activated - The user has double-clicked or pressed (enter|return|spacebar) on an item.

  • clicked,double - The user has double-clicked an item.

  • clicked,right - The user has right-clicked an item. (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.

  • 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.

  • 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

  • default

Layout content parts

  • start - A start position object in the list item

  • end - A end position object in the list item

Layout text parts

  • default - label in the list item

Scrollable Interface

This widget supports the scrollable interface.

If you wish to control the scolling behaviour using these functions, inherit both the widget class and the Scrollable class using multiple inheritance, for example:

class ScrollableGenlist(Genlist, Scrollable):
    def __init__(self, canvas, *args, **kwargs):
        Genlist.__init__(self, canvas)

Enumerations

List sizing modes

efl.elementary.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.

efl.elementary.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.

efl.elementary.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.

efl.elementary.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.

Inheritance diagram

Inheritance diagram of List, ListItem
class efl.elementary.List(Object parent, *args, **kwargs)

Bases: efl.elementary.__init__.Object

This is the class that actually implement the widget.

Parameters
  • parent (efl.evas.Object) – The parent object

  • **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

at_xy_item_get(x, y)

Get the item that is at the x, y canvas coords.

Parameters
  • x – The input x coordinate

  • y – The input y coordinate

Returns

(ListItem, int posret)

This returns the item at the given coordinates (which are canvas relative, not object-relative). If an item is at that coordinate, that item handle is returned, and if @p posret is not NULL, the integer pointed to is set to a value of -1, 0 or 1, depending if the coordinate is on the upper portion of that item (-1), on the middle section (0) or on the lower part (1). If NULL is returned as an item (no item found there), then posret may indicate -1 or 1 based if the coordinate is above or below all items respectively in the list.

New in version 1.8.

bounce

Deprecated since version 1.8: You should combine with Scrollable class instead.

bounce_get()

Deprecated since version 1.8: You should combine with Scrollable class instead.

bounce_set(h, v)

Deprecated since version 1.8: You should combine with Scrollable class instead.

callback_activated_add(func, *args, **kwargs)

The user has double-clicked or pressed (enter|return|spacebar) on an item.

func signature: cb(list, item, *args, **kwargs)

callback_activated_del(func)
callback_clicked_double_add(func, *args, **kwargs)

The user has double-clicked an item.

func signature: cb(list, item, *args, **kwargs)

callback_clicked_double_del(func)
callback_clicked_right_add(func, *args, **kwargs)

The user has right-clicked an item.

func signature: cb(list, item, *args, **kwargs)

New in version 1.13.

callback_clicked_right_del(func)
callback_edge_bottom_add(func, *args, **kwargs)

The list is scrolled until the bottom edge.

callback_edge_bottom_del(func)
callback_edge_left_add(func, *args, **kwargs)

The list is scrolled until the left edge.

callback_edge_left_del(func)
callback_edge_right_add(func, *args, **kwargs)

The list is scrolled until the right edge.

callback_edge_right_del(func)
callback_edge_top_add(func, *args, **kwargs)

The list is scrolled until the top edge.

callback_edge_top_del(func)
callback_highlighted_add(func, *args, **kwargs)

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.

func signature: cb(list, item, *args, **kwargs)

Changed in version 1.14: Added item param to func

callback_highlighted_del(func)
callback_item_focused_add(func, *args, **kwargs)

When the list item has received focus.

func signature: cb(list, item, *args, **kwargs)

New in version 1.10.

callback_item_focused_del(func)
callback_item_unfocused_add(func, *args, **kwargs)

When the list item has lost focus.

func signature: cb(list, item, *args, **kwargs)

New in version 1.10.

callback_item_unfocused_del(func)
callback_longpressed_add(func, *args, **kwargs)

An item in the list is long-pressed.

func signature: cb(list, item, *args, **kwargs)

callback_longpressed_del(func)
callback_selected_add(func, *args, **kwargs)

When the user selected an item.

func signature: cb(list, item, *args, **kwargs)

callback_selected_del(func)
callback_unhighlighted_add(func, *args, **kwargs)

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.

func signature: cb(list, item, *args, **kwargs)

Changed in version 1.14: Added item param to func

callback_unhighlighted_del(func)
callback_unselected_add(func, *args, **kwargs)

When the user unselected an item.

func signature: cb(list, item, *args, **kwargs)

callback_unselected_del(func)
clear()

Remove all list’s items.

See also

delete() ListItem.append_to()

first_item

The first item in the list

Type

ListItem

first_item_get()
focus_on_selection

Focus upon items selection mode

Type

bool

When enabled, every selection of an item inside the genlist will automatically set focus to its first focusable widget from the left. This is true of course if the selection was made by clicking an unfocusable area in an item or selecting it with a key movement. Clicking on a focusable widget inside an item will couse this particular item to get focus as usual.

New in version 1.8.

go()

Starts the list.

Example:

li = List(win)
ListItem("First").append_to(li)
ListItem("Second").append_to(li)
li.go()
li.show()

Note

Call before running show() on the list object.

Warning

If not called, it won’t display the list properly.

horizontal

Enable or disable horizontal mode on the list object.

Note

Vertical mode is set by default.

On horizontal mode items are displayed on list from left to right, instead of from top to bottom. Also, the list will scroll horizontally. Each item will presents left icon on top and right icon, or end, at the bottom.

Type

bool

item_append(label=None, icon=None, end=None, callback=None, *args, **kargs)
item_insert_after(after, label=None, icon=None, end=None, callback=None, *args, **kargs)
item_insert_before(before, label=None, icon=None, end=None, callback=None, *args, **kargs)
item_prepend(label=None, icon=None, end=None, callback=None, *args, **kargs)
items

Get a list of all the list items.

See also

ListItem.append_to() delete() clear()

Type

tuple of List items

items_get()
last_item

The last item in the list

Type

ListItem

last_item_get()
mode

Which mode to use for the list object.

The list’s resize behavior, transverse axis scroll and items cropping. See each mode’s description for more details.

Only one can be set, if a previous one was set, it will be changed by the new mode set. Bitmask won’t work as well.

Note

Default value is ELM_LIST_SCROLL.

Type

List sizing modes

mode_get()
mode_set(mode)
multi_select

Enable or disable multiple items selection on the list object.

Disabled by default. If disabled, the user can select a single item of the list each time. Selected items are highlighted on list. If enabled, many items can be selected.

If a selected item is selected again, it will be unselected.

Type

bool

multi_select_get()
multi_select_mode

Control the list multi select mode.

  • #ELM_OBJECT_MULTI_SELECT_MODE_DEFAULT : select/unselect items whenever each item is clicked.

  • #ELM_OBJECT_MULTI_SELECT_MODE_WITH_CONTROL : Only one item will be selected although multi-selection is enabled, if clicked without pressing control key. This mode is only available with multi-selection.

See also

multi_select

Type

Object multi select policy values

New in version 1.18.

multi_select_mode_get()
multi_select_mode_set(mode)
multi_select_set(multi)
scroller_policy

Deprecated since version 1.8: You should combine with Scrollable class instead.

scroller_policy_get()

Deprecated since version 1.8: You should combine with Scrollable class instead.

scroller_policy_set(policy_h, policy_v)

Deprecated since version 1.8: You should combine with Scrollable class instead.

select_mode

The list select mode.

Type

Selection modes

select_mode_get()
select_mode_set(mode)
selected_item

Get the selected item.

The selected item can be unselected with ListItem.selected.

The selected item always will be highlighted on list.

See also

selected_items

Type

ListItem

selected_item_get()
selected_items

Return a list of the currently selected list items.

Multiple items can be selected if multi_select is enabled.

Type

tuple of ListItem

selected_items_get()
class efl.elementary.ListItem(label=None, Object icon=None, Object end=None, callback=None, cb_data=None, *args, **kargs)

Bases: efl.elementary.__init__.ObjectItem

An item for the list widget.

Parameters
  • label (string) – The label of the list item.

  • icon (Object) – The icon object to use for the left side of the item. An icon can be any Evas object, but usually it is an Icon.

  • end (Object) – The icon object to use for the right side of the item. An icon can be any Evas object.

  • callback (callable) – The function to call when the item is selected.

  • cb_data – User data for the callback function

  • **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

append_to(list)

Append a new item to the list object.

A new item will be created and appended to the list, i.e., will be set as last item.

Items created with this method can be deleted with delete().

If a function is passed as argument, it will be called every time this item is selected, i.e., the user clicks over an unselected item. If always select is enabled it will call this function every time user clicks over an item (already selected or not).

Simple example (with no function callback or data associated):

li = List(win)
ic = Icon(win)
ic.file = "path/to/image"
ic.resizable = (True, True)
ListItem("label", ic).append_to(li)
li.go()
li.show()

See also

List.select_mode delete() List.clear() Icon

Returns

The created item or None upon failure.

Return type

ListItem

bring_in()

Bring in the given item to list view.

This causes list to jump to the given item and show it (by scrolling), if it is not fully visible.

This may use animation to do so and take a period of time.

If animation isn’t wanted, show() can be used.

insert_after(after)

Insert a new item into the list object after item after.

See also

append_to() List.select_mode efl.elementary.object_item.ObjectItem.delete() List.clear() Icon

Parameters

after (ListItem) – The list item to insert after.

Returns

The created item or None upon failure.

Return type

ListItem

insert_before(before)

Insert a new item into the list object before item before.

See also

append_to() List.select_mode efl.elementary.object_item.ObjectItem.delete() List.clear() Icon

Parameters

before (ListItem) – The list item to insert before.

Returns

The created item or None upon failure.

Return type

ListItem

next

The item after this item in the list.

Note

If the item is the last item, None will be returned.

Type

ListItem

next_get()
object

Returns the base object set for this list item.

Base object is the one that visually represents the list item row. It must not be changed in a way that breaks the list behavior (like deleting the base!), but it might be used to feed Edje signals to add more features to row representation.

Type

efl.edje.Edje

object_get()
prepend_to(list)

Prepend a new item to the list object.

See also

append_to() List.select_mode efl.elementary.object_item.ObjectItem.delete() List.clear() Icon

Parameters

list (List) – The list

Returns

The created item or None upon failure.

Return type

ListItem

prev

The item before this item in the list.

Note

If the item is the first item, None will be returned.

Type

ListItem

prev_get()
selected

The selected state of an item.

This property is the selected state of the given item. True for selected, False for not selected.

If a new item is selected the previously selected will be unselected, unless multiple selection is enabled with List.multi_select. Previously selected item can be get with List.selected_item().

Selected items will be highlighted.

Type

bool

selected_get()
selected_set(selected)
separator

Set or unset item as a separator.

Items aren’t set as separator by default.

If set as separator it will display separator theme, so won’t display icons or label.

Type

bool

separator_get()
separator_set(separator)
show()

Show the item in the list view.

It won’t animate list until item is visible. If such behavior is wanted, use bring_in() instead.