List¶
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 itemunselected
- when the user unselected an itemlongpressed
- an item in the list is long-pressededge,top
- the list is scrolled until the top edgeedge,bottom
- the list is scrolled until the bottom edgeedge,left
- the list is scrolled until the left edgeedge,right
- the list is scrolled until the right edgehighlighted
- 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 itemend
- 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¶
- 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_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_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
- 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
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
- 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
- Type
- selected_item_get()¶
- selected_items¶
Return a list of the currently selected list items.
Multiple items can be selected if
multi_select
is enabled.See also
- 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 anIcon
.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
- 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
- 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
- next¶
The item after this item in the list.
Note
If the item is the last item,
None
will be returned.See also
- Type
- 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
- 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
- prev¶
The item before this item in the list.
Note
If the item is the first item,
None
will be returned.See also
- Type
- 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 withList.selected_item()
.Selected items will be highlighted.
See also
- 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.