wx.lib.agw.customtreectrl.GenericTreeItem

This class holds all the information and methods for every single item in CustomTreeCtrl. This is a generic implementation of TreeItem.

Class Hierarchy

Inheritance diagram for class GenericTreeItem:

Methods Summary

__init__	Default class constructor.
AssignAttributes	Assigns the item attributes (font, colours, etc…) for this item.
Attr	Creates a new attribute (font, colours, etc…) for this item.
Check	Checks/unchecks an item. Internal use only.
Collapse	Collapses the item. Internal use only.
DeleteChildren	Deletes the item children. Internal use only.
DeleteWindow	Deletes the window associated to the item (if any). Internal use only.
Enable	Enables/disables the item.
Expand	Expands the item. Internal use only.
Get3StateValue	Gets the state of a 3-state checkbox item.
GetAttributes	Returns the item attributes (font, colours, etc…).
GetCheckedImage	Returns the item check image.
GetChildren	Returns the item’s children.
GetChildrenCount	Gets the number of children of this item.
GetCurrentCheckedImage	Returns the current item check image.
GetCurrentImage	Returns the current item image.
GetData	Returns the data associated to this item.
GetHeight	Returns the height of the item, in pixels.
GetImage	Returns the item image for a particular item state.
GetLeftImage	Returns the leftmost image associated to this item, i.e. the image on the
GetParent	Gets the item parent (another instance of GenericTreeItem or None for
GetSize	Returns the item size.
GetText	Returns the item text.
GetType	Returns the item type.
GetValue	Returns whether the item is checked or not.
GetVisited	Returns whether an hypertext item was visited or not.
GetWidth	Returns the width of the item’s contents, in pixels.
GetWindow	Returns the window associated to the item (if any).
GetWindowEnabled	Returns whether the associated window is enabled or not.
GetWindowSize	Returns the associated window size.
GetX	Returns the x position on an item, in logical coordinates.
GetY	Returns the y position on an item, in logical coordinates.
HasChildren	Returns whether the item has children or not.
HasPlus	Returns whether the item has the plus button or not.
Hide	Hides/shows the item. Internal use only.
HitTest	HitTest method for an item. Called from the main window CustomTreeCtrl.HitTest().
Insert	Inserts an item in the item children list for this item.
Is3State	Returns whether or not the checkbox item is a 3-state checkbox.
IsBold	Returns whether the item font is bold or not.
IsChecked	This is just a maybe more readable synonym for GetValue.
IsEnabled	Returns whether the item is enabled or not. Hidden items always return False.
IsExpanded	Returns whether the item is expanded or not. Hidden items always return False.
IsHidden	Returns whether the item is hidden or not.
IsHyperText	Returns whether the item is hypetext or not.
IsItalic	Returns whether the item font is italic or not.
IsOk	Returns whether the item is ok or not.
IsSelected	Returns whether the item is selected or not.
IsSeparator	Returns whether the item is meant to be an horizontal line separator or not.
OnSetFocus	Handles the wx.EVT_SET_FOCUS event for the window associated with the item.
OnTreeItemCollapsing	Handles the wx.EVT_TREE_ITEM_COLLAPSING event for the window associated with the item.
Set3State	Sets whether the item has a 3-state value checkbox assigned to it or not.
Set3StateValue	Sets the checkbox item to the given state.
SetAttributes	Sets the item attributes (font, colours, etc…).
SetBold	Sets the item font bold.
SetData	Sets the data associated to this item.
SetHasPlus	Sets whether an item has the ‘plus’ button.
SetHeight	Sets the item’s height. Used internally.
SetHilight	Sets the item focus/unfocus.
SetHyperText	Sets whether the item is hypertext or not.
SetImage	Sets the item image.
SetItalic	Sets the item font italic.
SetLeftImage	Sets the item leftmost image, i.e. the image associated to the item on the leftmost
SetText	Sets the item text.
SetType	Sets the item type.
SetVisited	Sets whether an hypertext item was visited or not.
SetWidth	Sets the item’s width. Used internally.
SetWindow	Sets the window associated to the item. Internal use only.
SetWindowEnabled	Sets whether the associated window is enabled or not.
SetX	Sets the x position on an item, in logical coordinates.
SetY	Sets the y position on an item, in logical coordinates.

Class API

class GenericTreeItem(object)

This class holds all the information and methods for every single item in CustomTreeCtrl. This is a generic implementation of TreeItem.

Methods

__init__(self, parent, text="", ct_type=0, wnd=None, image=-1, selImage=-1, data=None, separator=False, on_the_right=True)

Default class constructor. For internal use: do not call it in your code!

Parameters

• parent – the tree item parent, an instance of GenericTreeItem (may be None for root items);

• text (string) – the tree item text;

• ct_type (integer) – the tree item kind. May be one of the following integers:

  ct_type Value	Description
  0	A normal item
  1	A checkbox-like item
  2	A radiobutton-type item

• wnd – if not None, a non-toplevel window to be displayed next to the item, an instance of wx.Window;

• image (integer) – an index within the normal image list specifying the image to use for the item in unselected state;

• selImage (integer) – an index within the normal image list specifying the image to use for the item in selected state; if image > -1 and selImage is -1, the same image is used for both selected and unselected items;

• data (object) – associate the given Python object data with the item;

• separator (bool) – True if the item is a separator, False otherwise.

• on_the_right (bool) – True positions the window on the right of text, False on the left of text and overlapping the image.

Note

Regarding radiobutton-type items (with ct_type = 2), the following approach is used:

• All peer-nodes that are radiobuttons will be mutually exclusive. In other words, only one of a set of radiobuttons that share a common parent can be checked at once. If a radiobutton node becomes checked, then all of its peer radiobuttons must be unchecked.

• If a radiobutton node becomes unchecked, then all of its child nodes will become inactive.

Note

Separator items should not have children, labels, data or an associated window. Other issues/features associated to separator items:

• You can change the color of individual separators by using CustomTreeCtrl.SetItemTextColour(), or you can use CustomTreeCtrl.SetSeparatorColour() to change the color of all separators. The default separator colour is that returned by SystemSettings.GetColour(wx.SYS_COLOUR_GRAYTEXT);

• Separators can be selected just like any other tree item;

• Separators cannot have text;

• Separators cannot have children;

• Separators cannot be edited via the EVT_TREE_BEGIN_LABEL_EDIT event.

---

AssignAttributes(self, attr)

Assigns the item attributes (font, colours, etc…) for this item.

Parameters

attr – an instance of TreeItemAttr.

---

Attr(self)

Creates a new attribute (font, colours, etc…) for this item.

Returns

An instance of TreeItemAttr.

---

Check(self, checked=True)

Checks/unchecks an item. Internal use only.

Parameters

checked (bool) – True to check an item, False to uncheck it.

Note

This is meaningful only for checkbox-like and radiobutton-like items.

Note

Always use CustomTreeCtrl.CheckItem instead to update the tree properly and send events.

---

Collapse(self)

Collapses the item. Internal use only.

Note

Always use CustomTreeCtrl.Collapse instead to update the tree properly and send events.

---

DeleteChildren(self, tree)

Deletes the item children. Internal use only.

Parameters

tree – the main CustomTreeCtrl instance.

Note

Always use CustomTreeCtrl.DeleteChildren instead to update the tree properly.

---

DeleteWindow(self)

Deletes the window associated to the item (if any). Internal use only.

Note

Always use CustomTreeCtrl.DeleteItemWindow instead to update the tree properly.

---

Enable(self, enable=True)

Enables/disables the item.

Parameters

enable (bool) – True to enable the item, False to disable it.

Note

Call CustomTreeCtrl.EnableItem instead to update the tree properly.

---

Expand(self)

Expands the item. Internal use only.

Note

Always use CustomTreeCtrl.Expand instead to update the tree properly and send events.

---

Get3StateValue(self)

Gets the state of a 3-state checkbox item.

Returns

wx.CHK_UNCHECKED when the checkbox is unchecked, wx.CHK_CHECKED when it is checked and wx.CHK_UNDETERMINED when it’s in the undetermined state.

Raise

Exception when the item is not a 3-state checkbox item.

Note

This method raises an exception when the function is used with a 2-state checkbox item.

Note

This method is meaningful only for checkbox-like items.

---

GetAttributes(self)

Returns the item attributes (font, colours, etc…).

Returns

An instance of TreeItemAttr.

---

GetCheckedImage(self, which=TreeItemIcon_Checked)

Returns the item check image.

Parameters

which (integer) – can be one of the following bits:

Item State	Description
TreeItemIcon_Checked	To get the checkbox checked item image
TreeItemIcon_NotChecked	To get the checkbox unchecked item image
TreeItemIcon_Undetermined	To get the checkbox undetermined state item image
TreeItemIcon_Flagged	To get the radiobutton checked image
TreeItemIcon_NotFlagged	To get the radiobutton unchecked image

Returns

An integer index that can be used to retrieve the item check image inside a wx.ImageList.

Note

This method is meaningful only for radio & check items.

---

GetChildren(self)

Returns the item’s children.

Returns

A Python list containing instances of GenericTreeItem, representing this item’s children.

Note

The returned value is a reference to the list of children used internally by the tree. It is advised not to change this list and to make a copy before calling other tree methods as they could change the contents of the list.

---

GetChildrenCount(self, recursively=True)

Gets the number of children of this item.

Parameters

recursively (bool) – if True, returns the total number of descendants, otherwise only one level of children is counted.

---

GetCurrentCheckedImage(self)

Returns the current item check image.

Returns

An integer index that can be used to retrieve the item check image inside a wx.ImageList.

---

GetCurrentImage(self)

Returns the current item image.

Returns

An integer index that can be used to retrieve the item image inside a wx.ImageList.

---

GetData(self)

Returns the data associated to this item.

Returns

A Python object representing the item data, or None if no data has been assigned to this item.

---

GetHeight(self)

Returns the height of the item, in pixels.

This will be 0 when the item is first created and always 0 for hidden items. It is updated when the item is calculated.

---

GetImage(self, which=TreeItemIcon_Normal)

Returns the item image for a particular item state.

Parameters

which (integer) – can be one of the following bits:

Item State	Description
TreeItemIcon_Normal	To get the normal item image
TreeItemIcon_Selected	To get the selected item image (i.e. the image which is shown when the item is currently selected)
TreeItemIcon_Expanded	To get the expanded image (this only makes sense for items which have children - then this image is shown when the item is expanded and the normal image is shown when it is collapsed)
TreeItemIcon_SelectedExpanded	To get the selected expanded image (which is shown when an expanded item is currently selected)

Returns

An integer index that can be used to retrieve the item image inside a wx.ImageList.

---

GetLeftImage(self)

Returns the leftmost image associated to this item, i.e. the image on the leftmost part of the client area of CustomTreeCtrl.

Returns

An integer index that can be used to retrieve the item leftmost image inside a wx.ImageList.

---

GetParent(self)

Gets the item parent (another instance of GenericTreeItem or None for root items.

Returns

An instance of GenericTreeItem or None for root items.

---

GetSize(self, x, y, theButton)

Returns the item size.

Parameters

• x (integer) – the current item’s x position;

• y (integer) – the current item’s y position;

• theButton – an instance of the main CustomTreeCtrl.

Returns

A tuple of (x, y) dimensions, in pixels, representing the item’s width and height.

---

GetText(self)

Returns the item text.

Returns

A string containing the item text.

---

GetType(self)

Returns the item type.

See also

SetType and __init__ for a description of valid item types.

---

GetValue(self)

Returns whether the item is checked or not.

Note

This is meaningful only for checkbox-like and radiobutton-like items.

---

GetVisited(self)

Returns whether an hypertext item was visited or not.

---

GetWidth(self)

Returns the width of the item’s contents, in pixels.

This is the width of the item’s text plus the widths of the item’s image, checkbox, and window (if they exist). A separator’s width is the width of the entire client area.

---

GetWindow(self)

Returns the window associated to the item (if any).

Returns

An instance of any wx.Window derived class, excluding top-level windows.

---

GetWindowEnabled(self)

Returns whether the associated window is enabled or not.

Returns

True if the associated window is enabled, False if it is disabled.

Raise

Exception when the item has no associated window.

---

GetWindowSize(self)

Returns the associated window size.

---

GetX(self)

Returns the x position on an item, in logical coordinates.

---

GetY(self)

Returns the y position on an item, in logical coordinates.

---

HasChildren(self)

Returns whether the item has children or not.

Returns

True if the item has children, False otherwise.

---

HasPlus(self)

Returns whether the item has the plus button or not.

Returns

True if the item has a ‘plus’ mark, False otherwise.

---

Hide(self, hide)

Hides/shows the item. Internal use only.

Parameters

hide – True to hide the item, False to show it.

Note

Always use CustomTreeCtrl.HideItem instead to update the tree properly.

---

HitTest(self, point, theCtrl, flags=0, level=0)

HitTest method for an item. Called from the main window CustomTreeCtrl.HitTest().

Parameters

• point – the point to test for the hit (an instance of wx.Point);

• theCtrl – the main CustomTreeCtrl tree;

• flags (integer) – a bitlist of hit locations;

• level (integer) – the item’s level inside the tree hierarchy.

See also

CustomTreeCtrl.HitTest() method for the flags explanation.

Returns

A 2-tuple of (item, flags). The item may be None.

---

Insert(self, child, index)

Inserts an item in the item children list for this item.

Parameters

• child – an instance of GenericTreeItem;

• index (integer) – the index at which we should insert the new child.

---

Is3State(self)

Returns whether or not the checkbox item is a 3-state checkbox.

Returns

True if this checkbox is a 3-state checkbox, False if it’s a 2-state checkbox item.

Note

This method is meaningful only for checkbox-like items.

---

IsBold(self)

Returns whether the item font is bold or not.

Returns

True if the item has bold text, False otherwise.

---

IsChecked(self)

This is just a maybe more readable synonym for GetValue. Returns whether the item is checked or not.

Note

This is meaningful only for checkbox-like and radiobutton-like items.

---

IsEnabled(self)

Returns whether the item is enabled or not. Hidden items always return False.

Returns

True if the item is enabled, False if it is disabled.

---

IsExpanded(self)

Returns whether the item is expanded or not. Hidden items always return False.

Returns

True if the item is expanded, False if it is collapsed.

---

IsHidden(self)

Returns whether the item is hidden or not.

---

IsHyperText(self)

Returns whether the item is hypetext or not.

---

IsItalic(self)

Returns whether the item font is italic or not.

Returns

True if the item has italic text, False otherwise.

---

IsOk(self)

Returns whether the item is ok or not.

Note

This method always returns True, it has been added for backward compatibility with the wxWidgets C++ implementation.

---

IsSelected(self)

Returns whether the item is selected or not.

Returns

True if the item is selected, False otherwise.

---

IsSeparator(self)

Returns whether the item is meant to be an horizontal line separator or not.

Returns

True if this item is a separator, False otherwise.

---

OnSetFocus(self, event)

Handles the wx.EVT_SET_FOCUS event for the window associated with the item.

Parameters

event – a FocusEvent event to be processed.

---

OnTreeItemCollapsing(self, event)

Handles the wx.EVT_TREE_ITEM_COLLAPSING event for the window associated with the item.

Parameters

event – a GenericTreeItem to be processed.

---

Set3State(self, allow)

Sets whether the item has a 3-state value checkbox assigned to it or not.

Parameters

allow (bool) – True to set an item as a 3-state checkbox, False to set it to a 2-state checkbox.

Returns

True if the change was successful, False otherwise.

Note

This method is meaningful only for checkbox-like items.

---

Set3StateValue(self, state)

Sets the checkbox item to the given state.

Parameters

state (integer) – can be one of: wx.CHK_UNCHECKED (check is off), wx.CHK_CHECKED (check is on) or wx.CHK_UNDETERMINED (check is mixed).

Raise

Exception when the item is not a 3-state checkbox item.

Note

This method raises an exception when the checkbox item is a 2-state checkbox and setting the state to wx.CHK_UNDETERMINED.

Note

This method is meaningful only for checkbox-like items.

---

SetAttributes(self, attr)

Sets the item attributes (font, colours, etc…).

Parameters

attr – an instance of TreeItemAttr.

---

SetBold(self, bold)

Sets the item font bold.

Parameters

bold (bool) – True to have a bold font item, False otherwise.

Note

Call CustomTreeCtrl.SetItemBold instead to refresh the tree properly.

---

SetData(self, data)

Sets the data associated to this item.

Parameters

data (object) – can be any Python object.

---

SetHasPlus(self, has=True)

Sets whether an item has the ‘plus’ button.

Parameters

has (bool) – True to set the ‘plus’ button on the item, False otherwise.

Note

Call CustomTreeCtrl.SetItemHasChildren instead to refresh the tree properly.

---

SetHeight(self, h)

Sets the item’s height. Used internally.

Parameters

h (integer) – an integer specifying the item’s height, in pixels.

---

SetHilight(self, set=True)

Sets the item focus/unfocus.

Parameters

set (bool) – True to set the focus to the item, False otherwise.

Note

Call CustomTreeCtrl.SelectItem instead to update the tree properly and send events.

---

SetHyperText(self, hyper=True)

Sets whether the item is hypertext or not.

Parameters

hyper (bool) – True to set hypertext behaviour, False otherwise.

Note

Call CustomTreeCtrl.SetItemHyperText instead to refresh the tree properly.

---

SetImage(self, image, which)

Sets the item image.

Parameters

• image (integer) – an index within the normal image list specifying the image to use;

• which (integer) – the image kind.

See also

GetImage for a description of the which parameter.

Note

Call CustomTreeCtrl.SetItemImage instead to refresh the tree properly.

---

SetItalic(self, italic)

Sets the item font italic.

Parameters

italic (bool) – True to have an italic font item, False otherwise.

Note

Call CustomTreeCtrl.SetItemItalic instead to refresh the tree properly.

---

SetLeftImage(self, image)

Sets the item leftmost image, i.e. the image associated to the item on the leftmost part of the CustomTreeCtrl client area.

Parameters

image (integer) – an index within the left image list specifying the image to use for the item in the leftmost part of the client area.

Note

Call CustomTreeCtrl.SetItemLeftImage instead to refresh the tree properly.

---

SetText(self, text)

Sets the item text.

Parameters

text (string) – the new item label.

Raise

Exception if the item is a separator.

Note

Call CustomTreeCtrl.SetItemText to refresh the tree properly.

---

SetType(self, ct_type)

Sets the item type.

Parameters

ct_type (integer) – may be one of the following integers:

ct_type Value	Description
0	A normal item
1	A checkbox-like item
2	A radiobutton-type item

Note

Regarding radiobutton-type items (with ct_type = 2), the following approach is used:

• All peer-nodes that are radiobuttons will be mutually exclusive. In other words, only one of a set of radiobuttons that share a common parent can be checked at once. If a radiobutton node becomes checked, then all of its peer radiobuttons must be unchecked.

• If a radiobutton node becomes unchecked, then all of its child nodes will become inactive.

Note

Call CustomTreeCtrl.SetItemType instead to refresh the tree properly.

---

SetVisited(self, visited=True)

Sets whether an hypertext item was visited or not.

Parameters

visited (bool) – True to set a hypertext item as visited, False otherwise.

Note

Call CustomTreeCtrl.SetItemVisited instead to refresh the tree properly.

---

SetWidth(self, w)

Sets the item’s width. Used internally.

Parameters

w (integer) – an integer specifying the item’s width, in pixels.

---

SetWindow(self, wnd, on_the_right=True)

Sets the window associated to the item. Internal use only.

Parameters

• wnd – a non-toplevel window to be displayed next to the item, any subclass of wx.Window.

• on_the_right (bool) – True positions the window on the right of text, False on the left of text and overlapping the image. New in wxPython 4.0.4.

Raise

Exception if the input item is a separator and wnd is not None.

Note

Always use CustomTreeCtrl.SetItemWindow instead to update the tree properly.

---

SetWindowEnabled(self, enable=True)

Sets whether the associated window is enabled or not.

Parameters

enable (bool) – True to enable the associated window, False to disable it.

Raise

Exception when the item has no associated window.

---

SetX(self, x)

Sets the x position on an item, in logical coordinates.

Parameters

x (integer) – an integer specifying the x position of the item.

---

SetY(self, y)

Sets the y position on an item, in logical coordinates.

Parameters

y (integer) – an integer specifying the y position of the item.