TreeWidget Reference Manual

Name

TreeWidget - expandable/collapseable tree representation, similar to a foldable content table

Inherits

Pmw.LabeledWidget

Description

TreeWidget is a Python MegaWidget. This means, it uses Greg McFarlane's excellent Pmw framework. See there for general aspects of customization and extension of Python Megawidgets.

TreeWidget displays a tree structure in a Tkinter text widget. Each tree node is displayed in one line, indented according to its depth. This gives a presentation similar to a hierarchical content table. The presentation of internal nodes can be folded (collapsed) or expanded. Folding removes the node's descendants from the display, expansion adds children or (optionally) descendants further down the line. Icons before the node representation show whether the node can be collapsed, expanded or is a leave.

The nodes in the tree must be instances of the (abstract) class NodeData. Such an instance completely determines how the corresponding node itself is presented and what node interactions are possible. The presentation can contain, for example, text, icons, tags bound to commands etc.

TreeWidget provides an update operation which synchronizes the display with (potential) changes in the tree structure. The operation tries to keep an expanded/folded node expanded/folded in the updated tree. Due to limitations in the display algorithm, however, expanded nodes may get folded during update for some tree changes.

TreeWidget instances heavily rely on cyclic data structures (like many Tkinter widgets). Therefore, they are not automatically garbage collected by Python's reference counting collector. They must be explicitely destroyed when no longer needed. I hope, that the class properly manages all internal resources and does not contain memory or other resource leaks.

The display state of a tree node is maintained in TreeNode instances. This class is primarily internal and you will rarely interact with its instances. If you want to restrict update operations to a subtree (for efficiency reasons) or to expand a subtree, then you will use this class' methods.

Options

treeicons

Initialisation option. A sequence of 3 images used as icons for leaves, expandable and collapseable nodes, respectively. The default provides a downside triangle as expandable, an upside triangle as collapsable and a dot as leaf icons.

selectoptions

Initialisation option. A dictionary with tag options for the Select tag. See select method, for details. The default is {'underline':1}.

autoexpand

specifies up to what depth a new tree is expanded automatically. 0 shows only the tree root, 1 shows the root with its children, -1 completely expands the tree. The default is 1.

root

specifies the root of the tree to be displayed. It must be None (do not display a tree) or a NodeData instance. The default is None.

indent

Initialisation option. It specifies the amount of indentation for the tree levels. It must be a Tk text widget tabs specification. The default is 16 (pixels).

disableselection

Initialisation option. It disables the selection export and visualization. The default is 1 (true).

Components

treedisplay

the widget used to display the tree. By default, it is a Pmw.ScrolledText instance.

Component aliases

tree

Alias for treedisplay_text.

Methods

destroy()

destroys the widget and releases all used resources. An explicite destroy is necessary, because this widget is not automatically garbage collected (due to cylic data references).

update()

synchronises the display with (potential) changes in the tree structure.

select(*args)

associates the Select tag with the range(s) given by args.

deselect()

removes all ranges from the Select tag.