Widget's input value

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

<tree>

    <header>
        <column>Label</column>
        <column>Label</column>
        ...
    </header>


    <row>
        <column>Value</column>
        <column>Value</column>
        ...
    </row>

    <row>
        <column>Value</column>
        <column>Value</column>
        ...
        <row>
            <column>Value</column>
            <column>Value</column>
            ...
        </row>
        <row>
            <column>Value</column>
            <column>Value</column>
            ...
        </row>
        ...
    </row>

    ...


</tree>

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

The row tag can contain other rows which will be the row's children.

The following attributes can be specified in the different tags, see Table 4.3, “Tree widget XML attributes” to know where you can put each attribute.

This table defines in which tag attributes can be specified :

Widget's attributes

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 Tree 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 Tree 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 rows id, it is usefull to access rows directly without a loop. list returns a list in the same order as the screen.

header

If this attribute is set to False, headers are not shown. The default is True.

cascading_resize

This attribute holds whether interactive resizing will be cascaded to the following columns once the column being resized by the user has reached its minimum size. The default is False.

movable

This attribute holds if columns can be moved by the user. The default is False.

resize

This attribute sets the constraint on how the columns can be resized. Possible values are :

none

The user cannot resize the columns.

free

The user can resize the columns.

fit

Columns are automatically resized to an optimal size based on the contents. The size cannot be changed by the user.

stretch

Columns are automatically resized to fill the available space. The size cannot be changed by the user.

stretch_last

The last column is automatically resized to fill the available space. This is the default.

stretch_N

The column N is automatically resized to fill the available space.

selection

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

none

Items cannot be selected.

row

Only one row at a time can be selected.

rows

Multiple rows can be selected. This is the default.

item

Only one item at a time can be selected.

items

Multiple items can be selected.

elide

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

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.

validators

Validator type of input text. Possible values are : int, date, time. Validators are specified by column index, ex : 0:int,1:int,2:date.

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

getRowValue(row, parent=None)

This function returns a row's value. row can be the id, the value or the index of the row. parent can be the id, the value, the index of the parent row or None for root rows.

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

setSingleSelection()

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

addRows(data=None, parent=None, position=-1)

Add rows represented by data in the given position (-1 means at the bottom) within parent. parent can be the id, the value, the index of the parent row or None for root rows. data can be :

• An XML string containing any number of row tags.
• A tuple that represent one row in the form : (column0, column1, ..., columnN) where column can be a string or a dict. If column is a dict, column's attributes can be passed as the dict's keys, the value of the column is passed in the value key.
• A list that contains any of the previous formats. You can use different formats in the same list.
• If data is left to None, an empty row is added.

addRequest()

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

editRow(row, data, parent=None)

Edit row. row can be the id, the text or the index of the row. parent can be the id, the value, the index of the parent row or None for root rows. data can be :

• A list or tuple that contains columns values.
• A value that will be assigned to all columns in the edited row.

In both cases, a column value can be a string representing the item's value. It can be a boolean representing the item's checked state (for checkable items). It can also be a dict that contains item's attributes that will be modified, item's value can be modified with the value key.

editRequest(row=None, parent=None)

This function triggers a row edit action, the row is selected and put into edit mode. if row is left to None, the current row is edited. parent can be the id, the value, the index of the parent row or None for root rows.

editCurrentRow(data)

Edit the current row. data holds the row's data and follow the same rules as the editRow function.

editItem(row, col, data, parent=None)

This function edits the item referenced by row, col and parent. row and col can be an id, a value or an index. parent can be the id, the value, the index of the parent row or None for root rows. data is the item's value and can be a string or a dict like in the editRow function.

editCurrentItem(data)

This function sets the value of the current item to data.

delRows(rows, parent=None)

This function deletes rows. rows can be a list of rows (id, value or index) or a single row. parent can be the id, the value, the index of the parent row or None for root rows.

delCurrentRows()

This function deletes the current selected rows.

clear(clear_header=True)

This function deletes all rows. if clear_header is set to False, the headers are not deleted.

select(rows, parent=None, flag='clearandselect')

This function selects rows. rows can be a list of rows (id, value or index) or a single row. parent can be the id, the value, the index of the parent row or None for root rows. flag can be one of the following :

none

No selection will be made.

clear

The complete selection will be cleared.

select

All specified rows will be selected.

deselect

All specified rows will be deselected.

toggle

All specified rows 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.

scrollToRow(row, parent=None)

This function scrolls the view to ensure that row is visible. parent can be the id, the value, the index of the parent row or None for root rows.

expandRow(row, parent=None)

This function expands row and show the row's children. parent can be the id, the value, the index of the parent row or None for root rows.

moveRow(row, position, parent=None)

This function moves row to position. position can be an absolute index position or an offset in the form +n or -n. parent can be the id, the value, the index of the parent row or None for root rows. Moving rows is disabled when sorting is enabled.

moveRowUp(row, parent=None)

This function moves row up. parent can be the id, the value, the index of the parent row or None for root rows. Moving rows is disabled when sorting is enabled.

moveRowDown(row, parent=None)

This function moves row down. parent can be the id, the value, the index of the parent row or None for root rows. Moving rows is disabled when sorting is enabled.

moveCurrentRow(position)

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

moveCurrentRowUp()

This function moves the current row up. Moving rows is disabled when sorting is enabled.

moveCurrentRowDown()

This function moves the current row down. Moving rows is disabled when sorting is enabled.

changeRowsParent(rows, parent=None, position=-1, current_parent=None)

This function changes the parent of rows to parent. The rows are put in position, -1 means at the bottom. rows can be a list of rows (id, value or index) or a single row. parent can be the id, the value, the index of the new parent row or None to make rows parent less. current_parent can be the id, the value, the index of the current parent row or None for root rows.

changeCurrentRowsParent(parent=None, position=-1)

This function changes the parent of the current row to parent. The row is put in position, -1 means at the bottom. parent can be the id, the value, the index of the new parent or None to make the current row parent less.

Widget's signals

clicked(row)

This signal is emitted when the user clicks on a row. row is the value of the clicked row as returned with the getRowValue function.

doubleClicked(row)

This signal is emitted when the user double clicks on a row. row is the value of the double clicked row as returned with the getRowValue function.

rowAdded(row)

This signal is emitted when a row is added after calling the addRequest function.

itemChanged(row, col, item)

This signal is emitted when the content of the item referenced by row and col change. item is the new value of the item.

rowsDeleted(rows)

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

Widget's output value

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

If return is dict, the output value is a bi-dimensional dict where each item's value can be accessed like this : output_value[row_id][column_id]. item's value is a dict in the form : {'column':INDEX, 'selected':BOOL, 'value':VALUE, 'checked':BOOL}. the checked key is available only for checkable items. The row's index is available at output_value[row_id]['__row__'] and the row's embedded data is available at output_value[row_id]['__data__']. Child rows are available via output_value[row_id]['__childs__'].

If return is list, the output value is a list of rows values. Each row's value is a dict in the form : {'id':ID, 'row':INDEX, 'columns':COLUMNS, 'data':DATA, 'childs':CHILDS} where COLUMNS is a list of items values and CHILDS a list of child rows. All those elements follows the screen order.

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