Node:A new tree-node, Next:, Previous:A new tree-buffer, Up:tree-buffer


How to create a new tree-node

When a new tree-buffer has been created, then the most senseful programming-task is adding some tree-nodes to it.

Content of a tree-node

A tree-node is an object which stores in special slots several data necessary to link the node with other nodes, to display the node and to hold some associated node-data (e.g. a tag created by the semantic-library).

A tree-node can have the following slots:

NAME
The name of the node. Regardless how the node is displayed; see SHRINK-NAME and DISPLAYED-NAME.
TYPE
The type of the node; must currently be an interger! The type is used to classify the nodes, so for example all nodes of a certain type can display the same popup-menu - see tree-buffer-create or A new tree-buffer which parts of a tree-buffer are distinguished by node-types.
DATA
The data of the node; This can be any arbitrary emacs-lisp-object. This slots holds that data asscociated with the node and represented by the node in the tree-buffer. Example: Assume a tree-buffer displaying a directory-tree where each node just displays as its name the name of (sub)directories, but not the full path. The full path is stored in the DATA-slot of a node so when clicking onto this node the asscociated directory can be open for example in a dired-buffer.
EXPANDABLE
If not nil then the node is expandable means it has children.
EXPANDED
If not nil then the node is currently expanded, means its children are visible in the tree-buffers as subnodes of the node.
PARENT
The parent tree-node. This is the link to the father (rsp. mother ;-) of the node. It must be a object of type tree-node!
CHILDREN
List of children tree-nodes. They must be all objects of type tree-node!
SHRINK-NAME
Decides if the NAME can be shortened when displayed in a narrow tree buffer window. The following values are valid:
INDENTSTR
Containes the full indentation-string for the node. So a single node can easily be redrawn.
DISPLAYED-NAME
Contains the current displayed name of the node. The displayed name can be different from the NAME according to the value of SHRINK-NAME.
Creating a new tree-node and adding it to the tree

A new tree-node has to be created with the function tree-node-new. This "constructor" accepts the following parameter: NAME, TYPE, DATA, NOT-EXPANDABLE, PARENT and SHRINK-NAME.

For all parameters except NOT-EXPANDABLE the description is available in the slot-description in the section above. If NOT-EXPANDABLE is set to not nil then the slot EXPANDABLE will be set to nil; otherwise to t.

tree-node-new returns a new tree-node.

The new node can either being added implicitely to the tree via the optional PARENT-parameter when calling tree-buffer-new or explicitely by first creating the new node without setting the parent-node but later setting the parent-node via the according accessor (see next section below). Children should only being added with tree-node-add-children - see next section.

Accessing the slots of a tree-node

The section above shows which slots a tree-node have.

A slot with name XXX is getable with the following piece of code: 

(tree-node->xxx <a tree node>)

Here is an example how to get the value of the slot DATA: 

(tree-node->data <a tree node>)

A slot with name XXX is setable with the following piece of code: 

(setf (tree-node->xxx <a tree node>) <new value>)

Again an example with slot DATA which sets this slot to the string "~/a_subdir_of_HOME": 

(setf (tree-node->data <a tree node>) "~/a_subdir_of_HOME")

IMPORTANT: Adding new children to a node should always being done with the function tree-node-add-children because this functions encapsulates all the necessary stuff needed to add children to a node (mainly adding the children itself and setting the node itself as parent for every children).

See The tree-buffer-API for the rest of the API available for tree-nodes.