Navigation

Phoenix Logo

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

styles 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_DEFAULT_STYLE: Style used by the control by default, just wx.dataview.TL_SINGLE currently.

events 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 Class Hierarchy

Inheritance diagram for class TreeListCtrl:

method_summary 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.
Expand Expand the given tree branch.
GetCheckedState Return the checked state of the item.
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.

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

api 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)

overload 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:



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 first 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:
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:
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:

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) –

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

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:
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:
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 first 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:

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

Set the images for the given item.

See InsertItem for the images parameters descriptions.

Parameters:

SetItemText(self, *args, **kw)

overload Overloaded Implementations:


SetItemText (self, item, col, text)

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

Parameters:


SetItemText (self, item, text)

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

Parameters:



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