This subchapter is a general introduction in the main concepts of 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-node1 (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).
The following sequence of tasks is the general recipe for a tree-buffer beginning from creation and ending with the display.
tree-buffer-createfor non ECB-tree-buffers and with the macro
defecb-tree-buffer-creatorwhen the tree-buffer should be used as an ECB-tree-buffer, so it is an ECB-window. See A new tree-buffer for all details.
tree-node-newfor 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.
tree-buffer-updateto 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
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
IMPORTANT: See Programming special windows for details about programming ECB-windows (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.