DTreeView

From Dabo Wiki
Jump to: navigation, search

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

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 tree.removeNode(nodeReference).

Adding nodes in this fashion can be tedious, so there is also the treeFromStructure() method. This accepts a nested list structure in the format:

["text", [children]]

where the 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 ShowRootNode is 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 dNode that contains special format options or other behaviors. Any nodes added to the tree will be of this class. Default=dNode.
  • Selection - (int or list of ints): Returns the index of the currently-selected node (when MultipleSelect is False), or a list of selected nodes (when MultipleSelect is True).
  • 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 key can 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 key for a given state. May also optionally pass the index of the image in the image list rather than the key. Valid states are: "normal", "expanded", "selected", and "selectedexpanded".
  • nodeForObject(obj) - (dNode): Given an object, returns the node whose Object property matches, or None if 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 None if it has no higher siblings.
  • priorSibling(node) - (dNode): Given a node, returns the prior sibling node, or None if 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 None if 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 TreeItemID object is passed, returns a list nodes matching that itemID value. 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 top property, 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 topNode is 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: BackColor, Font, FontBold, FontDescription, FontFace, FontInfo, FontItalic, FontSize, FontUnderline, ForeColor

  • 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).