A new tree-node - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Next: Updating a tree-buffer, 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.

##### 11.3.3.1 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:
  - `beginning`: The NAME is truncated at the beginning so the end is always visible.
  - `end`: The NAME is truncated at the end. If the tree-node is EXPANDABLE the name is truncated so that the expand symbol is visible.
  - `nil`: The NAME is never truncated. In this case DISPLAYED-NAME is equal to NAME.
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.

##### 11.3.3.2 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.

##### 11.3.3.3 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.