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

General description of tree-buffers

This subchapter is a general introduction in the main concepts of a tree-buffer.

What is a tree-buffer?

A tree-buffer is meant to display certain informations (e.g. a directory-tree) in a tree-structure consisting of tree-nodes. Every line in a tree-buffer displays exactly one tree-node. Each node has exactly one parent-node and can have any arbitrary number of children-nodes. If a tree-node has no children then it is called a leaf. A tree-node contains several "slots" wheras the most important ones are the "name", "displayed-name" and "data". See A new tree-node for a detailed explanation.

The difference between a natural tree like a fir and a tree-buffer is that the root(-node) of a tree-buffer is not visible but only its children. In the example below the nodes parent-node-1 and parent-node-2 are the children of the invisible root-node. Each tree-buffer has exactly one root-node which is created automatically by `tree-buffer-create'.

If a tree-node contains at least one child it is displayed with a special expand/collapse-symbol (see the example below). This symbol allows expanding (rsp. collapsing) the tree-node wheras expanding means to display the children-nodes and collapsing means to hide the childrens of a tree-node.

Here is an example of a tree-buffer:

<root-node>  ------------------------[root-node (invisible)]
    [+] <parent-node-1>  -------.
    [-] <parent-node-2>  -------|
        [-] <expanded>  --------|
            <leaf-node-1>  -----|
            <leaf-node-2>  -----|-----[tree-nodes]
            <leaf-node-3>  -----|
            <leaf-node-4>  -----|
        [+] <collapsed>  -------´
         |
         `-----------------[expand/collapse-symbol]

In most cases an action is triggered when clicking with the mouse onto a tree-node¹ (e.g. clicking onto "leaf-node-1" or "parent-node-1" in the example above). Which action is triggered by which key depends on what you specify at creation-time of the tree-buffer - see A new tree-buffer for details.

The creation-interface of a tree-buffer allows defining special popup-menus when clicking with the right mouse-button (of course also possible via keyboard, see Tree-buffer keybindings) onto a tree-node (e.g. some senseful actions possible for directory-nodes like grepping this directory or performing version-control actions for this directory or something else).

General recipe for a tree-buffer

The following sequence of tasks is the general recipe for a tree-buffer beginning from creation and ending with the display.

1. Create the tree-buffer Creating a new tree-buffer has to be done with tree-buffer-create for non ECB-tree-buffers and with the macro defecb-tree-buffer-creator when the tree-buffer should be used as an ECB-tree-buffer, so it is an ECB-interactor. See A new tree-buffer for all details.
2. Add tree-nodes to the tree-buffer Adding nodes to the new tree-buffer (means make the new tree-buffer the current buffer and call tree-node-new for a new tree-node (note that a root-node for this tree-buffer has been autom. created by tree-buffer-create!). The first tree-node you add to a tree-buffer must have always the root-node (avaliable via tree-buffer-get-root) as parent-node. The next nodes can have either one of the fromerly added nodes or the root-node too. All tree-nodes haveing the root-node as parent will be displayed at the toplevel of the tree-buffer. See A new tree-node for all details.
3. Display the tree-buffer with current nodes and state When you are finished building up the tree-node-structure call tree-buffer-update to display the current tree-structure (again after making the tree-buffer the current-buffer). See Updating a tree-buffer for all details.

IMPORTANT: First a call of tree-buffer-update updates the display of a tree-buffer, means shows all the tree-nodes in an emacs-buffer! Neither creating a tree-buffer nor adding tree-nodes display anything; this just builds the internal tree-structure.

IMPORTANT: See Programming special windows for details about programming interactors (special windows) regardless if they were build as tree or not. There you can find a.o. how to automatically synchronizing a special window with the current edit-buffer.

Footnotes

1. Of course using the keyboard is also possible, see Tree-buffer keybindings.