Widget's input value

The input value of the List widget is an XML string in the form :

<list>
    <row>Item 1</row>
    <row>Item 2</row>
    ...
</list>

	Warning
	Unlike the example, the XML input value must not contain spaces between tags.

The following attributes can be specified globally in the list tag, or individually in the row tag :

The following attributes can be specified in the row tag :

Widget's attributes

flow

This attribute holds which direction the items layout should flow. If this attribute is horizontal, the items will be laid out left to right. If the wrap attribute is True, the layout will wrap when it reaches the right side of the visible area. If this attribute is vertical, the items will be laid out from the top of the visible area, wrapping when it reaches the bottom.

view

This attribute holds the view mode of the List. Possible values are : list or icon.

resize

If this attribute is set to True, the items will be laid out again when the view is resized.

wrap

This attribute holds whether the layout should wrap when there is no more space in the visible area. The point at which the layout wraps depends on the flow attribute.

move

This attribute determines how the user can move the items in the view. none means that the items can't be moved by the user. free means that the user can drag and drop the items to any position in the view. snap means that the user can drag and drop the items, but only to the positions in a notional grid.

batch

This attribute holds whether the layout of items should happen immediately or be delayed. If set to True the items are laid out in batches of 100 items.

selection

This attribute holds which selection mode the view operates in. Possible values are :

none

The items cannot be selected

single

When the user selects an item, any already-selected item becomes unselected, and the user cannot unselect the selected item.

multi

When the user selects an item in the usual way, the selection is cleared and the new item selected. However, if the user presses the Ctrl key when clicking on an item, the clicked item gets toggled and all other items are left untouched. If the user presses the Shift key while clicking on an item, all items between the current item and the clicked item are selected or unselected, depending on the state of the clicked item. Multiple items can be selected by dragging the mouse over them. This is the default.

elide

This attribute holds the the position of the "..." in elided text. Possible values are : none, left, right, middle. The default is right.

sort

This attribute holds the sorting mode. Possible values are : asc or desc. If the attribute is set to False, sorting is disabled. The default is asc.

numeric_sort

If this attribute is True (which is the default), numbers are sorted like numbers not strings.

dynamic_sort

This attribute holds whether the List is dynamically sorted whenever the contents change. The default is True.

case_sort

This attribute holds the case sensitivity setting used for comparing strings when sorting. If set to True sorting is case sensitive. The default is False.

buttons

This attribute holds a list of Button widgets which will be disabled when no items are selected. The buttons are enabled when selection contains items.

ro

If set to True, the List is set to read only mode.

verbose

If this attribute is set to True, the getValue function returns all items values. If set to False (which is the default), only selected items are returned.

return

This attribute holds the format of the return value of the getValue function. dict (which is the default) returns a dict with keys formed from items id, it is usefull to access items directly without a loop. list returns a list in the same order as the screen.

duplicates

If this attribute is set to False, duplicate items are not permitted. The default is True.

duplicates_msg

This attribute holds the message shown to the user when he tries to add a duplicate item. The default is "Item '@ITEM@' already exists" where @ITEM@ is replaced with the duplicate item.

validator

Validator type of input text. Possible values are : int, date, time.

invalid_msg

This attribute holds the message shown to the user when he tries to add an invalid item. The default is "Item '@ITEM@' is invalid" where @ITEM@ is replaced with the invalid item.

confirm_del

If this attribute is True (which is the default) a confirmation message is shown to the user before deleting items.

del_item_msg

This attribute holds the message shown to the user before deleting one item. The default is "Delete Item '@ITEM@' ?" where @ITEM@ is replaced with the item to delete.

del_items_msg

This attribute holds the message shown to the user before deleting multiple items. The default is "Delete these @COUNT@ Items ?" where @COUNT@ is replaced with the number of items to delete.

clear_msg

This attribute holds the message shown to the user before deleting all items. The default is "Delete all items ?".

Widget's functions

getItemValue(item)

This function returns an item's value. item can be the id, the text or the index of the item.

getCurrentValue(single_value=False)

This function returns the current selected items. if single_value is set to True, the return value is assumed to be a single item.

setSingleSelection()

This function ensures that only one item is selected. If multiple items are selected, only the last selected item remains selected.

addItems(data='', position=-1)

Add items represented by data in the given position, -1 means at the bottom. data can be :

• An XML string containing any number of row tags.
• A string representing an item text.
• A dict representing an item. The item's attribute used in the row tag can be used as the dict's keys. Item's text is passed in the value key.
• A tuple in the form (item_text,) or (item_id, item_text).
• A list that contains any of the previous formats. You can use different formats in the same list.

addRequest()

This function triggers an item add action. An empty item is added and set in edit mode immediately, the cursor is positioned so the user can begin editing the item.

editItem(item, data)

Edit item. item can be the id, the text or the index of the item. data can be :

• A string representing the item's text.
• A boolean representing the item's checked state.
• A dict that contains item's attributes that will be modified. Item's text can be modified with the value key.

editRequest(item=None)

This function triggers an item edit action, the item is selected and put into edit mode. if item is left to None, the current item is edited.

editCurrentItem(data)

Edit the current item. data holds the item's elements to edit and follow the same rules as the editItem function.

delItems(items)

This function deletes items. items can be a list of items (id, text or index) or a single item.

delCurrentItems()

This function deletes the current selected items.

clear()

This function deletes all items.

select(items, flag='clearandselect')

This function selects items. items can be a list of items (id, text or index) or a single item. flag can be one of the following :

none

No selection will be made.

clear

The complete selection will be cleared.

select

All specified items will be selected.

deselect

All specified items will be deselected.

toggle

All specified items will be selected or deselected depending on their current state.

current

The current selection will be updated.

selectcurrent

A combination of select and current, provided for convenience.

togglecurrent

A combination of toggle and current, provided for convenience.

clearandselect

A combination of clear and select, provided for convenience.

scrollToItem(item)

This function scrolls the view to ensure that item is visible.

moveItem(item, position)

This function moves item to position. position can be an absolute index position or an offset in the form +n or -n. Moving items is disabled when sorting is enabled.

moveItemUp(item)

This function moves item up. Moving items is disabled when sorting is enabled.

moveItemDown(item)

This function moves item down. Moving items is disabled when sorting is enabled.

moveCurrentItem(position)

This function moves the current item to position. position can be an absolute index position or an offset in the form +n or -n. Moving items is disabled when sorting is enabled.

moveCurrentItemUp()

This function moves the current item up. Moving items is disabled when sorting is enabled.

moveCurrentItemDown()

This function moves the current item down. Moving items is disabled when sorting is enabled.

Widget's signals

clicked(item)

This signal is emitted when the user clicks on an item. item is the value of the clicked item as returned with the getItemValue function.

doubleClicked(item)

This signal is emitted when the user double clicks on an item. item is the value of the double clicked item as returned with the getItemValue function.

itemAdded(item)

This signal is emitted when an item is added after calling the addRequest function.

itemValueChanged(item)

This signal is emitted when an item's value change. item is the new value of item as returned with the getItemValue function.

itemCheckChanged(item)

This signal is emitted when an item's checked state change. item is the new value of item as returned with the getItemValue function.

itemsDeleted(items)

This signal is emitted when one or more items are deleted. items is a dict or list (depending on return attribute) that contains the deleted items values.

Widget's output value

The output value of a List widget depends on two attributes : verbose and return.

If return is dict, the output value is a dict in the form {ITEM_1_ID:ITEM_1_VALUE, ITEM_2_ID:ITEM_2_VALUE, ..., ITEM_n_ID:ITEM_n_VALUE} where ITEM_ID is the id of the item and ITEM_VALUE is a dict in the form {'value':TEXT, 'row':INDEX, 'selected':BOOL, 'checked':BOOL, 'data':DATA}.

If return is list, the output value is a list of items values. Each item's value is a dict in the form : {'id':ID, 'value':TEXT, 'row':INDEX, 'selected':BOOL, 'checked':BOOL, 'data':DATA}

If verbose is True all items are returned otherwise only selected items are returned.