Tree buffer styles - ecb-home/ecb GitHub Wiki

Displaying the Trees With Different Styles

ECB offers three different styles for the tree-buffers in the ECB-windows. Two of the styles are ascii-based and one style uses images for drawing the tree-structure.

Basic Knowledge About The Styles

There are nine image-names which define the control- and guide-symbols to draw the tree. Here is the list of the allowed image-names and the related corresponding ascii-symbols:

  • open (“[-]”): The control-symbol displayed for an opened tree-node which has several subnodes. Clicking onto this control closes the node.
  • close (“[+]”): The control-symbol displayed for a closed tree-node, i.e. an expandable node with subnodes but all subnodes are hidden. Clicking onto this control opened the node and displays its subnodes - if there are any. If it has no subnodes the empty-symbol will be displayed.
  • empty (“[x]”): The symbol displayed for an empty node. An empty node is a node which could have subnodes but has currently none.
  • leaf (“*”): The symbol displayed for a node which can not have any subnodes so it is a “leaf” in the tree.
  • guide (“|”): The symbol used for drawing vertical “guide-lines” for opened nodes. See the example below.
  • no-guide (“ ”): Sometimes invisible guide-lines are needed to draw the tree.
  • end-guide (“`”): The symbol used for the guide-line of the last subnode of an opened node.
  • handle (“-”): The symbol displayed before every subnode. Each handle is connected to a guide-line - either a normal guide or an end-guide.
  • no-handle (“ ”): An invisible handle.

A tree will be build-up with these elements like follows:

[-] node-with-subnodes      (open)
 |-[+] not-empty-subnode1   (guide+handle+close)
 |-[x] empty-subnode        (guide+handle+empty)
 `-[-] not-empty-subnode2   (end-guide+handle+open)
    |-* leaf-1              (no-guide+no-handle+guide+handle+leaf)
    `-* leaf-2              (no-guide+no-handle+end-guide+handle+leaf)

How To Customize the ASCII-Styles

The ECB-option eco-tree-buffer-style offers two different styles completely drawn with ascii-controls and -guides.

Ascii-style with guide-lines (value ascii-guides) [1]:

[-] ECB
 |  [+] code-save
 `- [-] ecb-images
     |  [-] directories
     |   |  [-] height-15
     |   |   |  * close.xpm
     |   |   |  * empty.xpm
     |   |   |  * leaf.xpm
     |   |   `- * open.xpm
     |   |  [+] height-17
     |   |  [+] height-19
     |   `- [+] height-21
     |  [x] history
     |  [x] methods
     `- [x] sources

Ascii-style without guide-lines (value ascii-no-guides) - this is the style used by ECB <= 1.96:

[-] ECB
    [+] code-save
    [-] ecb-images
        [-] directories
            [-] height-15
                * close.xpm
                * empty.xpm
                * leaf.xpm
                * open.xpm
            [+] height-17
            [+] height-19
            [+] height-21
        [x] history
        [x] methods
        [x] sources

The tree-layout of both ascii-styles can be affected with the options eco-tree-indent and ecb-tree-expand-symbol-before (the examples above have set 4 for the former and true for the latter one). For the guide-style the face and color of the guide- and handle-symbols can be customized with the option ecb-tree-guide-line-face (default is the equal-named face).

Footnotes

[1] For a better look&feel of such a tree-buffer ECB displays only the last subnode of an opened node with a handle!

Which Images Are Used For The Tree

Depending on the value of eco-tree-buffer-style and the image-support of Emacs, the tree-buffer try to use images instead of strings to draw a nice-looking tree.

If images can and should be used then the option ecb-tree-image-icons-directories tells ECB where to search for suitable image-icons for each of the nine image-names (see above). An image is used for displaying a control with name “XXX” if one of the directories of ecb-tree-image-icons-directories contains an image-file with basename “ecb-XXX” and an extension which is supported by Emacs. Currently supported extensions are “.xpm”, “.png”, “.gif”, “.jpeg”, .”jpg” and “.xbm”.

Example: To display the control with name “open” with a suitable image then one of the directories of ecb-tree-image-icons-directories must contain a file with name “ecb-open.xpm” or “ecb-open.png” etc. See the description of this option to get all important details how and in which sequence ECB searches the directories of ecb-tree-image-icons-directories.

ECB comes with predefined default-images usable for every tree-buffer and special images for the Directories- and the Methods-tree-buffer. They are defined in several different heights - so for the most senseful font-heights of a tree-buffer a fitting image-size should be available. The shipped images reside either in the subdirectory "ecb-images" of the ECB-installation or - if ECB is installed as regular XEmacs-package - in the ECB-etc data-directory (the directory returned by evaluating (locate-data-directory "ecb"). If you do not want to change the images then you normally have nothing to do because the default value of ecb-tree-image-icons-directories points already to the correct image-directories.

A special remark for XEmacs:

At least XEmacs 21.14 (but probably previous versions too) has a bug in its display-engine which prevents adjacent images to be displayed correctly. The effect is, that in a row of two or more adjacent images (e.g. end-guide+handle+open - see the tree-example above) always all images are masked by the last one, means only the last one is visible. If at least one normal character (e.g. a space) is placed between two images then the images are displayed correctly. Therefore ECB has implemented the following work-around to get best possible results with XEmacs: open-, close-, empty-, leaf-, guide-, end-guide- and no-guide-images are displayed with images and the handle- and the no-handle-images are displayed with the corresponding ascii-symbols (which is “-” rsp. “ ”). The face (the color) of the handle-symbol is customizable via the option ecb-tree-guide-line-face.

This bug is already reported to the XEmacs-team. If your XEmacs has fixed this bug then add the following to your .emacs-file (or whereever your emacs-setup is located):

(setq tree-buffer-enable-xemacs-image-bug-hack nil)

Then ECB uses images without any special work-around with XEmacs too. Just try it - if the tree-buffers look ugly then the XEmacs-bug is probably not fixed correctly.

Special Images for the Methods-Buffer

ECB can display all the semantic-tags in the Method-buffer with special icons for methods, variables and classes - each of them with a different icon dependend of the protection of the tag. This feature can be disabled/enabled via the option ecb-display-image-icons-for-semantic-tags. All the special images are located in that directory where the option ecb-tree-image-icons-directories point to for methods.