dTreeView is a control that contains a hierarchical set of items arranged in a tree-like format. Each item, or node, can have zero or many sub-nodes, each of which can also have sub-nodes, etc. Nodes that contain child information can be expanded to display the children, or collapsed to hide the children. Nodes are objects with their own properties and methods, with a base class of
Trees have a root node, which may or may not be displayed; you can controls that with the
ShowRootNode property explained below. You add nodes to the tree by calling
newNode = tree.appendNode(parent, text), where
parent is the parent node to which you want to add the child node, and
text is the displayed text for the node. This will return a reference to the newly-created child node. You can later remove a node by calling
Adding nodes in this fashion can be tedious, so there is also the
treeFromStructure() method. This accepts a nested list structure in the format:
children list consists of zero or more entries of the same format. To illustrate, the
addDummyData() method constructs such a list structure:
[This is the root, [['First Child'], [Second Child, [['Grandkid #1'], [Grandkid #2, ['Great-Grandkid #1']], ['Grandkid #3']]], ['Third Child']]]
Some of the more useful properties for dTreeView:
- BaseNodes - (list): Returns the root node if
True; otherwise, returns all the lowest-level sibling nodes.
- Editable - (bool): When
True, users can edit the text of the nodes.
- MultipleSelect - (bool): When
True, users can select more than one node at once by control-clicking or shift-clicking.
- NodeClass - (dNode): Allows you to define a custom subclass of
dNodethat contains special format options or other behaviors. Any nodes added to the tree will be of this class. Default=
- Selection - (int or list of ints): Returns the index of the currently-selected node (when
False), or a list of selected nodes (when
- ShowButtons - (bool): When
True(default), the expand/collapse buttons are displayed. When
False, you must double-click on a node to expand or collapse it. Must be set when the tree is constructed.
- ShowLines - (bool): When
True, the lines connecting the various nodes are drawn. Must be set when the tree is constructed. May have no effect on some platforms, such as OS X, where the native control does not support it.
- ShowRootNode - (bool): Determines whether the root node of the tree is displayed. Must be set when the tree is constructed.
- ShowRootNodeLines - (bool): Determines if the lines connecting the root node to its children are drawn. On large trees these lines may be visually confusing, so it can help to turn them off. Must be set when the tree is constructed.
Some of the more useful methods for dTreeView:
- clear() - (None): Removes all nodes from the tree.
- getRoodNode() - (dNode): Returns the root node for the tree.
- appendNode(parentNode, text) - (dNode): Appends a child node with the given text to the specified parent node.
- removeNode(node) - (None): Removes the specified node.
- expand(node) - (None): Expands the specified node.
- collapse(node) - (None): Collapses the specified node.
- expandAll() - (None): Expands all nodes.
- collapseAll() - (None): Collapses all nodes.
- showNode(node) - (None): Ensures that the given node is visible. If it is contained in collapsed parents, those parents are expanded to make this node visible.
- addImage(img, key) - (None): Adds the specified image to the tree's image list. The optional
keycan be used to later retrieve the image; otherwise, it is retrieved by position in the list.
- setNodeImg(node, key, state="normal") - (None): Sets the specified node's image to the image corresponding to the specified
keyfor a given state. May also optionally pass the index of the image in the image list rather than the key. Valid states are:
- nodeForObject(obj) - (dNode): Given an object, returns the node whose
Objectproperty matches, or
Noneif no nodes match.
- getParentNode(node) - (dNode): Given a node, returns its parent.
- getChildren(node) - (list): Given a node, returns all its child nodes.
- getDescendents(node) - (list): Given a node, returns all its child nodes, along with their children, etc.
- getSiblings(node) - (list): Given a node, returns a list of all its siblilng nodes.
- nextSibling(node) - (dNode): Given a node, returns the next sibling node, or
Noneif it has no higher siblings.
- priorSibling(node) - (dNode): Given a node, returns the prior sibling node, or
Noneif it has no lower siblings.
- nextNode(node) - (dNode): Given a node, returns the first child node if the current node has children. If it has no children, returns the next sibling. If there are no next siblings, returns the next sibling of the parent node. If the parent node has no more siblings, returns the next sibling of the grandparent node, etc. Returns
Noneif we are at the absolute bottom of the flattened tree structure. Sometimes referred to as flatdown navigation.
- priorNode(node) - (dNode): Given a node, returns the last child of its prior sibling node. If there are no prior siblings, returns the parent. Sometimes referred to as flatup navigation.
- find(searchVal, top=None) - (list): Searches the nodes collection for all nodes that match whose text matches the passed search value (if a text value was passed). If a wxPython
TreeItemIDobject is passed, returns a list nodes matching that
itemIDvalue. If a specific node is passed in the top property, the search is limited to descendents of that node.
- findPattern(searchPattern, top=None) - (list): Allows for regexp pattern matching in order to find matching nodes using less-than-exact matches. If a specific node is passed in the
topproperty, the search is limited to descendents of that node.
- treeFromStructure(stru, topNode=None) - (None): Given a list of nested lists in the format
[nodeText, [list of childnodes]], constructs the appropriate tree. If
topNodeis given, the tree starts at that node; otherwise, it clears the tree and builds the structure from the root node.
- makeDirTree(dirPath, wildcard=None, showHidden=False) - (None): Given a path, constructs a tree that reflects the directory structure. Options are to specify a wildcard, which will only display matching file names, and whether or not to show hidden files.
Some of the more useful properties for dNode:
Note: dNode objects have all the normal font and formatting properties:
- Caption - (str): The text displayed on the node.
- Children - (list of nodes): Returns a list of all child nodes for this node.
- Descendents - (list): Returns a list of all child nodes and all their children, their children's children, etc.
- Expanded - (bool): Determines if the node is in an expanded or collapsed state.
- FullCaption - (str): Full dot-separated string of the captions of this node and its ancestors. Read-only.
- Image - (int): The index of the image to be displayed on this node, based on the containing tree's image list.
- IsRootNode - (bool): Returns True if this node is the root node. Read-only.
- Object - (object): Any node can have an arbitrary object associated with it; it can be text, an integer, a control; anything. This property allows you to set and retrieve this associated object.
- Selected - (bool): Determines if this node is currently selected.
- Siblings - (list): Returns a list of all sibling nodes for this node.
See the Dabo Class Documentation for an exhaustive documentation of this control's Properties, Events and Methods. (Note that this documentation is no longer live, but it's still available via the Internet Archive).