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

11.3.3 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:

The name of the node. Regardless how the node is displayed; see SHRINK-NAME and DISPLAYED-NAME.
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.
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.
If not nil then the node is expandable means it has children.
If not nil then the node is currently expanded, means its children are visible in the tree-buffers as subnodes of the node.
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!
List of children tree-nodes. They must be all objects of type tree-node!
Decides if the NAME can be shortened when displayed in a narrow tree buffer window. The following values are valid:
Containes the full indentation-string for the node. So a single node can easily be redrawn.
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.