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


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.

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.


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 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
Return type

bool



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



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


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