wx.dataview.TreeListCtrl¶

A control combining wx.TreeCtrl and wx.ListCtrl features.

This is a multi-column tree control optionally supporting images and checkboxes for the items in the first column.

It is currently implemented using wx.dataview.DataViewCtrl internally but provides a much simpler interface for the common use case it addresses. Thus, one of the design principles for this control is simplicity and intentionally doesn’t provide all the features of wx.dataview.DataViewCtrl. Most importantly, this class stores all its data internally and doesn’t require you to define a custom model for it.

Instead, this controls works like wx.TreeCtrl or non-virtual wx.ListCtrl and allows you to simply add items to it using wx.dataview.TreeListCtrl.AppendItem and related methods. Typically, you start by setting up the columns (you must have at least one) by calling wx.dataview.TreeListCtrl.AppendColumn and then add the items. While only the text of the first column can be specified when adding them, you can use wx.dataview.TreeListCtrl.SetItemText to set the text of the other columns.

Unlike wx.TreeCtrl or wx.ListCtrl this control can sort its items on its own. To allow user to sort the control contents by clicking on some column you should use wx.COL_SORTABLE flag when adding that column to the control. When a column with this flag is clicked, the control resorts itself using the values in this column. By default the sort is done using alphabetical order comparison of the items text, which is not always correct (e.g. this doesn’t work for the numeric columns). To change this you may use SetItemComparator method to provide a custom comparator, i.e. simply an object that implements comparison between the two items. The treelist sample shows an example of doing this. And if you need to sort the control programmatically, you can call SetSortColumn method.

Here are the styles supported by this control. Notice that using wx.dataview.TL_USER_3STATE implies wx.dataview.TL_3STATE and wx.dataview.TL_3STATE in turn implies wx.dataview.TL_CHECKBOX.

^^

Window Styles¶

This class supports the following styles:

wx.dataview.TL_SINGLE: Single selection, this is the default.
wx.dataview.TL_MULTIPLE: Allow multiple selection, see GetSelections.
wx.dataview.TL_CHECKBOX: Show the usual, 2 state, checkboxes for the items in the first column.
wx.dataview.TL_3STATE: Show the checkboxes that can possibly be set by the program, but not the user, to a third, undetermined, state, for the items in the first column. Implies wx.dataview.TL_CHECKBOX.
wx.dataview.TL_USER_3STATE: Same as wx.dataview.TL_3STATE but the user can also set the checkboxes to the undetermined state. Implies wx.dataview.TL_3STATE.
wx.dataview.TL_NO_HEADER: Don’t show the column headers, that are shown by default. Notice that this style is only available since wxWidgets 2.9.5.
wx.dataview.TL_DEFAULT_STYLE: Style used by the control by default, just wx.dataview.TL_SINGLE currently. ^^

^^

Events Emitted by this Class¶

Handlers bound for the following event types will receive a wx.dataview.TreeListEvent parameter.

EVT_TREELIST_SELECTION_CHANGED: Process wxEVT_TREELIST_SELECTION_CHANGED event and notifies about the selection change in the control. In the single selection case the item indicated by the event has been selected and previously selected item, if any, was deselected. In multiple selection case, the selection of this item has just changed (it may have been either selected or deselected) but notice that the selection of other items could have changed as well, use wx.dataview.TreeListCtrl.GetSelections to retrieve the new selection if necessary.
EVT_TREELIST_ITEM_EXPANDING: Process wxEVT_TREELIST_ITEM_EXPANDING event notifying about the given branch being expanded. This event is sent before the expansion occurs and can be vetoed to prevent it from happening.
EVT_TREELIST_ITEM_EXPANDED: Process wxEVT_TREELIST_ITEM_EXPANDED event notifying about the expansion of the given branch. This event is sent after the expansion occurs and can’t be vetoed.
EVT_TREELIST_ITEM_CHECKED: Process wxEVT_TREELIST_ITEM_CHECKED event notifying about the user checking or unchecking the item. You can use wx.dataview.TreeListCtrl.GetCheckedState to retrieve the new item state and wx.dataview.TreeListEvent.GetOldCheckedState to get the previous one.
EVT_TREELIST_ITEM_ACTIVATED: Process wxEVT_TREELIST_ITEM_ACTIVATED event notifying about the user double clicking the item or activating it from keyboard.
EVT_TREELIST_ITEM_CONTEXT_MENU: Process wxEVT_TREELIST_ITEM_CONTEXT_MENU event indicating that the popup menu for the given item should be displayed.
EVT_TREELIST_COLUMN_SORTED: Process wxEVT_TREELIST_COLUMN_SORTED event indicating that the control contents has just been resorted using the specified column. The event doesn’t carry the sort direction, use GetSortColumn method if you need to know it. ^^

New in version 2.9.3.

See also

wx.TreeCtrl, wx.dataview.DataViewCtrl

Class Hierarchy¶

Inheritance diagram for class TreeListCtrl:

Methods Summary¶

`__init__`	Default constructor, call `Create` later.
`AppendColumn`	Add a column with the given title and attributes.
`AppendItem`	Same as `InsertItem` with `wx.dataview.TLI_LAST`.
`AreAllChildrenInState`	Return `True` if all children of the given item are in the specified state.
`AssignImageList`	Sets the image list and gives its ownership to the control.
`CheckItem`	Change the item checked state.
`CheckItemRecursively`	Change the checked state of the given item and all its children.
`ClearColumns`	Delete all columns.
`Collapse`	Collapse the given tree branch.
`Create`	Create the control window.
`DeleteAllItems`	Delete all tree items.
`DeleteColumn`	Delete the column with the given index.
`DeleteItem`	Delete the specified item.
`EnsureVisible`	Call this to ensure that the given item is visible.
`Expand`	Expand the given tree branch.
`GetCheckedState`	Return the checked state of the item.
`GetClassDefaultAttributes`
`GetColumnCount`	Return the total number of columns.
`GetColumnWidth`	Get the current width of the given column in pixels.
`GetDataView`	Return the view part of this control as wx.dataview.DataViewCtrl.
`GetFirstChild`	Return the first child of the given item.
`GetFirstItem`	Return the first item in the tree.
`GetItemData`	Get the data associated with the given item.
`GetItemParent`	Return the parent of the given item.
`GetItemText`	Return the text of the given item.
`GetNextItem`	Get item after the given one in the depth-first tree-traversal order.
`GetNextSibling`	Return the next sibling of the given item.
`GetRootItem`	Return the (never shown) root item.
`GetSelection`	Return the currently selected item.
`GetSelections`	Returns a list of all selected items. This method can be used in
`GetSortColumn`	Return the column currently used for sorting, if any.
`GetView`	Return the view part of this control as a wx.Window.
`InsertItem`	Insert a new item into the tree.
`IsExpanded`	Return whether the given item is expanded.
`IsSelected`	Return `True` if the item is selected.
`PrependItem`	Same as `InsertItem` with `wx.dataview.TLI_FIRST`.
`Select`	Select the given item.
`SelectAll`	Select all the control items.
`SetColumnWidth`	Change the width of the given column.
`SetImageList`	Sets the image list.
`SetItemComparator`	Set the object to use for comparing the items.
`SetItemData`	Set the data associated with the given item.
`SetItemImage`	Set the images for the given item.
`SetItemText`	Set the text of the specified column of the given item.
`SetSortColumn`	Set the column to use for sorting and the order in which to sort.
`UncheckItem`	Uncheck the given item.
`Unselect`	Deselect the given item.
`UnselectAll`	Deselect all the control items.
`UpdateItemParentStateRecursively`	Update the state of the parent item to reflect the checked state of its children.
`WidthFor`	Get the width appropriate for showing the given text.

Properties Summary¶

`ColumnCount`	See `GetColumnCount`
`DataView`	See `GetDataView`
`FirstItem`	See `GetFirstItem`
`RootItem`	See `GetRootItem`
`Selection`	See `GetSelection`
`Selections`	See `GetSelections`
`SortColumn`	See `GetSortColumn` and `SetSortColumn`
`View`	See `GetView`
`NO_IMAGE`	A public C++ attribute of type `int`. A constant indicating that no image should be used for an item.

Class API¶

class wx.dataview.TreeListCtrl(Window)¶

Possible constructors:

TreeListCtrl()

TreeListCtrl(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
             style=TL_DEFAULT_STYLE, name=TreeListCtrlNameStr)

A control combining TreeCtrl and ListCtrl features.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default constructor, call Create later.

This constructor is used during two-part construction process when it is impossible or undesirable to create the window when constructing the object.

__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=TL_DEFAULT_STYLE, name=TreeListCtrlNameStr)

Full constructing, creating the object and its window.

See Create for the parameters description.

Parameters

parent (wx.Window) –
id (wx.WindowID) –
pos (wx.Point) –
size (wx.Size) –
style (long) –
name (string) –

AppendColumn(self, title, width=COL_WIDTH_AUTOSIZE, align=ALIGN_LEFT, flags=COL_RESIZABLE)¶

Add a column with the given title and attributes.

Parameters

title (string) – The column label.
width (int) – The width of the column in pixels or the special wx.COL_WIDTH_AUTOSIZE value indicating that the column should adjust to its contents. Notice that the last column is special and will be always resized to fill all the space not taken by the other columns, i.e. the width specified here is ignored for it.
align (Alignment) – Alignment of both the column header and its items.
flags (int) – Column flags, currently can include wx.COL_RESIZABLE to allow the user to resize the column and wx.COL_SORTABLE to allow the user to resort the control contents by clicking on this column.

Return type

int

Returns

Index of the new column or -1 on failure.

AppendItem(self, parent, text, imageClosed=-1, imageOpened=-1, data=None)¶

Same as InsertItem with wx.dataview.TLI_LAST.

Parameters

parent (wx.dataview.TreeListItem) –
text (string) –
imageClosed (int) –
imageOpened (int) –
data (ClientData) –

Return type

wx.dataview.TreeListItem

AreAllChildrenInState(self, item, state)¶

Return True if all children of the given item are in the specified state.

This is especially useful for the controls with TL_3STATE style to allow to decide whether the parent effective state should be the same state, if all its children are in it, or CHK_UNDETERMINED.

Parameters

item (wx.dataview.TreeListItem) –
state (CheckBoxState) –

Return type

bool

See also

UpdateItemParentStateRecursively

AssignImageList(self, imageList)¶

Sets the image list and gives its ownership to the control.

The image list assigned with this method will be automatically deleted by wx.TreeCtrl as appropriate (i.e. it takes ownership of the list).

Parameters: imageList (wx.ImageList) –

See also

SetImageList .

CheckItem(self, item, state=CHK_CHECKED)¶

Change the item checked state.

Parameters

item (wx.dataview.TreeListItem) – Valid non-root tree item.
state (CheckBoxState) – One of wx.CHK_CHECKED, wx.CHK_UNCHECKED or, for the controls with wx.dataview.TL_3STATE or wx.dataview.TL_USER_3STATE styles, wx.CHK_UNDETERMINED.

CheckItemRecursively(self, item, state=CHK_CHECKED)¶

Change the checked state of the given item and all its children.

This is the same as CheckItem but checks or unchecks not only this item itself but all its children recursively as well.

Parameters

item (wx.dataview.TreeListItem) –
state (CheckBoxState) –

ClearColumns(self)¶: Delete all columns.

See also

DeleteAllItems

Collapse(self, item)¶

Collapse the given tree branch.

Parameters: item (wx.dataview.TreeListItem) –

Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=TL_DEFAULT_STYLE, name=TreeListCtrlNameStr)¶

Create the control window.

Can be only called for the objects created using the default constructor and exactly once.

Parameters

parent (wx.Window) – The parent window, must be not None.
id (wx.WindowID) – The window identifier, may be ID_ANY.
pos (wx.Point) – The initial window position, usually unused.
size (wx.Size) – The initial window size, usually unused.
style (long) – The window style, see their description in the class documentation.
name (string) – The name of the window.

Return type

bool

DeleteAllItems(self)¶: Delete all tree items.

DeleteColumn(self, col)¶

Delete the column with the given index.

Parameters: col – Column index in 0 to GetColumnCount (exclusive) range.
Return type: bool
Returns: True if the column was deleted, False if index is invalid or deleting the column failed for some other reason.

DeleteItem(self, item)¶

Delete the specified item.

Parameters: item (wx.dataview.TreeListItem) –

EnsureVisible(self, item)¶

Call this to ensure that the given item is visible.

Parameters: item (wx.dataview.TreeListItem) –

New in version 4.1/wxWidgets-3.1.0.

Expand(self, item)¶

Expand the given tree branch.

Parameters: item (wx.dataview.TreeListItem) –

GetCheckedState(self, item)¶

Return the checked state of the item.

The return value can be wx.CHK_CHECKED, wx.CHK_UNCHECKED or wx.CHK_UNDETERMINED.

Parameters: item (wx.dataview.TreeListItem) –
Return type: wx.CheckBoxState

static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)¶

Parameters: variant (WindowVariant) –
Return type: VisualAttributes

GetColumnCount(self)¶: Return the total number of columns.

GetColumnWidth(self, col)¶

Get the current width of the given column in pixels.

Parameters: col –
Return type: int

GetDataView(self)¶

Return the view part of this control as wx.dataview.DataViewCtrl.

This method may return None in the future, non DataViewCtrl-based, versions of this class, use GetView unless you really need to use wx.dataview.DataViewCtrl methods on the returned object.

Return type: wx.dataview.DataViewCtrl

GetFirstChild(self, item)¶

Return the first child of the given item.

Item may be the root item.

Return value may be invalid if the item doesn’t have any children.

Parameters: item (wx.dataview.TreeListItem) –
Return type: wx.dataview.TreeListItem

GetFirstItem(self)¶

Return the first item in the tree.

This is the first child of the root item.

Return type: wx.dataview.TreeListItem

See also

GetNextItem

GetItemData(self, item)¶

Get the data associated with the given item.

The returned pointer may be None.

It must not be deleted by the caller as this will be done by the control itself.

Parameters: item (wx.dataview.TreeListItem) –
Return type: ClientData

GetItemParent(self, item)¶

Return the parent of the given item.

All the tree items visible in the tree have valid parent items, only the never shown root item has no parent.

Parameters: item (wx.dataview.TreeListItem) –
Return type: wx.dataview.TreeListItem

GetItemText(self, item, col=0)¶

Return the text of the given item.

By default, returns the text of the first column but any other one can be specified using col argument.

Parameters

item (wx.dataview.TreeListItem) –
col –

Return type

string

GetNextItem(self, item)¶

Get item after the given one in the depth-first tree-traversal order.

Calling this function starting with the result of GetFirstItem allows iterating over all items in the tree.

The iteration stops when this function returns an invalid item, i.e.

item = tree.GetFirstItem()

while item.IsOk():
    item = tree.GetNextItem(item)

    # Do something with every tree item ...

Parameters: item (wx.dataview.TreeListItem) –
Return type: wx.dataview.TreeListItem

GetNextSibling(self, item)¶

Return the next sibling of the given item.

Return value may be invalid if there are no more siblings.

Parameters: item (wx.dataview.TreeListItem) –
Return type: wx.dataview.TreeListItem

GetRootItem(self)¶

Return the (never shown) root item.

Return type: wx.dataview.TreeListItem

GetSelection(self)¶

Return the currently selected item.

This method can’t be used with multi-selection controls, use GetSelections instead.

The return value may be invalid if no item has been selected yet. Once an item in a single selection control was selected, it will keep a valid selection.

Return type: wx.dataview.TreeListItem

GetSelections(self)¶

Returns a list of all selected items. This method can be used in both single and multi-selection case.

Return type: PyObject

GetSortColumn(self)¶

Return the column currently used for sorting, if any.

If the control is currently unsorted, the function simply returns False and doesn’t modify any of its output parameters.

Return type: tuple
Returns: ( bool, col, ascendingOrder )

GetView(self)¶

Return the view part of this control as a wx.Window.

This method always returns not None pointer once the window was created.

Return type: Window

InsertItem(self, parent, previous, text, imageClosed=-1, imageOpened=-1, data=None)¶

Insert a new item into the tree.

Parameters

parent (wx.dataview.TreeListItem) – The item parent. Must be valid, may be GetRootItem .
previous (wx.dataview.TreeListItem) – The previous item that this one should be inserted immediately after. It must be valid but may be one of the special values wx.dataview.TLI_FIRST or wx.dataview.TLI_LAST indicating that the item should be either inserted before the first child of its parent (if any) or after the last one.
text (string) – The item text.
imageClosed (int) – The normal item image, may be wx.NO_IMAGE to not show any image.
imageOpened (int) – The item image shown when it’s in the expanded state.
data (ClientData) – Optional client data pointer that can be later retrieved using GetItemData and will be deleted by the tree when the item itself is deleted.

Return type

wx.dataview.TreeListItem

IsExpanded(self, item)¶

Return whether the given item is expanded.

Parameters: item (wx.dataview.TreeListItem) –
Return type: bool

IsSelected(self, item)¶

Return True if the item is selected.

This method can be used in both single and multiple selection modes.

Parameters: item (wx.dataview.TreeListItem) –
Return type: bool

PrependItem(self, parent, text, imageClosed=-1, imageOpened=-1, data=None)¶

Same as InsertItem with wx.dataview.TLI_FIRST.

Parameters

parent (wx.dataview.TreeListItem) –
text (string) –
imageClosed (int) –
imageOpened (int) –
data (ClientData) –

Return type

wx.dataview.TreeListItem

Select(self, item)¶

Select the given item.

In single selection mode, deselects any other selected items, in multi-selection case it adds to the selection.

Parameters: item (wx.dataview.TreeListItem) –

SelectAll(self)¶

Select all the control items.

Can be only used in multi-selection mode.

SetColumnWidth(self, col, width)¶

Change the width of the given column.

Set column width to either the given value in pixels or to the value large enough to fit all of the items if width is wx.COL_WIDTH_AUTOSIZE.

Notice that setting the width of the last column is ignored as this column is always resized to fill the space left by the other columns.

Parameters

col –
width (int) –

SetImageList(self, imageList)¶

Sets the image list.

The image list assigned with this method will not be deleted by the control itself and you will need to delete it yourself, use AssignImageList to give the image list ownership to the control.

Parameters: imageList (wx.ImageList) – Image list to use, may be None to not show any images any more.

SetItemComparator(self, comparator)¶

Set the object to use for comparing the items.

This object will be used when the control is being sorted because the user clicked on a sortable column or SetSortColumn was called.

The provided pointer is stored by the control so the object it points to must have a life-time equal or greater to that of the control itself. In addition, the pointer can be None to stop using custom comparator and revert to the default alphabetical comparison.

Parameters: comparator (wx.dataview.TreeListItemComparator) –

SetItemData(self, item, data)¶

Set the data associated with the given item.

Previous client data, if any, is deleted when this function is called so it may be used to delete the current item data object and reset it by passing None as data argument.

Parameters

item (wx.dataview.TreeListItem) –
data (ClientData) –

SetItemImage(self, item, closed, opened=-1)¶

Set the images for the given item.

See InsertItem for the images parameters descriptions.

Parameters

item (wx.dataview.TreeListItem) –
closed (int) –
opened (int) –

SetItemText(self, *args, **kw)¶

Overloaded Implementations:

SetItemText (self, item, col, text)

Set the text of the specified column of the given item.

Parameters

item (wx.dataview.TreeListItem) –
col –
text (string) –

SetItemText (self, item, text)

Set the text of the first column of the given item.

Parameters

item (wx.dataview.TreeListItem) –
text (string) –

SetSortColumn(self, col, ascendingOrder=True)¶

Set the column to use for sorting and the order in which to sort.

Calling this method resorts the control contents using the values of the items in the specified column. Sorting uses custom comparator set with SetItemComparator or alphabetical comparison of items texts if none was specified.

Notice that currently there is no way to reset sort order.

Parameters

col – A valid column index.
ascendingOrder (bool) – Indicates whether the items should be sorted in ascending (A to Z) or descending (Z to A) order.

UncheckItem(self, item)¶

Uncheck the given item.

This is synonymous with CheckItem(wxCHK_UNCHECKED).

Parameters: item (wx.dataview.TreeListItem) –

Unselect(self, item)¶

Deselect the given item.

This method can be used in multiple selection mode only.

Parameters: item (wx.dataview.TreeListItem) –

UnselectAll(self)¶

Deselect all the control items.

Can be only used in multi-selection mode.

UpdateItemParentStateRecursively(self, item)¶

Update the state of the parent item to reflect the checked state of its children.

This method updates the parent of this item recursively: if this item and all its siblings are checked, the parent will become checked as well. If this item and all its siblings are unchecked, the parent will be unchecked. And if the siblings of this item are not all in the same state, the parent will be switched to indeterminate state. And then the same logic will be applied to the parents parent and so on recursively.

This is typically called when the state of the given item has changed from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have wx.dataview.TL_3STATE flag. Notice that without this flag this function can’t work as it would be unable to set the state of a parent with both checked and unchecked items so it’s only allowed to call it when this flag is set.

Parameters: item (wx.dataview.TreeListItem) –

WidthFor(self, text)¶

Get the width appropriate for showing the given text.

This is typically used as second argument for AppendColumn or with SetColumnWidth .

Parameters: text (string) –
Return type: int

Properties¶

ColumnCount¶: See GetColumnCount

DataView¶: See GetDataView

FirstItem¶: See GetFirstItem

NO_IMAGE¶: A public C++ attribute of type int. A constant indicating that no image should be used for an item.

RootItem¶: See GetRootItem

Selection¶: See GetSelection

Selections¶: See GetSelections

SortColumn¶: See GetSortColumn and SetSortColumn

View¶: See GetView

Navigation

wx.dataview.TreeListCtrl¶

Window Styles¶

Events Emitted by this Class¶

Class Hierarchy¶

Methods Summary¶

Properties Summary¶

Class API¶

Methods¶

Properties¶