Next: , Previous: ecb-general, Up: Customizable options


7.3.2 Group ecb-tree-buffer

This group contains general settings related to the tree-buffers of ECB:

— User Option: basic-buffer-sync

Synchronize the basic ECB-buffers automatically with current edit buffer.

The basic ECB-buffers are the buffers for directories, sources, methods and history.

If 'always then the synchronization takes place always a buffer changes in the edit window, if nil then never. If a list of major-modes then only if the major-mode of the new buffer belongs NOT to this list.

But in every case the synchronization takes only place if the current-buffer in the edit-window has a relation to files or directories. Examples for the former one are all programming-language-modes, Info-mode too, an example for the latter one is dired-mode. For all major-modes related to non-file/directory-buffers like help-mode, customize-mode and others never an autom. synchronization will be done!

It's recommended to exclude at least Info-mode because it makes no sense to synchronize the ECB-windows after calling the Info help. Per default also dired-mode is excluded but it can also making sense to synchronize the ECB-directories/sources windows with the current directory in the dired-buffer.

IMPORTANT NOTE: Every time the synchronization is done the hook ecb-basic-buffer-sync-hook is evaluated.

— User Option: basic-buffer-sync-delay

Time Emacs must be idle before the special ECB-buffers are synchronized. Synchronizing is done with the current source displayed in the edit window. If nil then there is no delay, means synchronization takes place immediately. A small value of about 0.25 seconds saves CPU resources and you get even though almost the same effect as if you set no delay.

— User Option: basic-buffer-sync-hook

Hook run at the end of ecb-basic-buffer-sync. See documentation of ecb-basic-buffer-sync for conditions when synchronization takes place and so in turn these hooks are evaluated.

Precondition for such a hook: Current buffer is the buffer of the currently selected edit-window.

Postcondition for such a hook: Point must stay in the same edit-window as before evaluating the hook.

Important note: If the option ecb-basic-buffer-sync is not nil the function ecb-basic-buffer-sync is running either every time Emacs is idle or even after every command (see ecb-basic-buffer-sync-delay). So these hooks can be really called very often! Therefore each function of this hook should/must check in an efficient way at beginning if its task have to be really performed and then do them only if really necessary! Otherwise performance of Emacs could slow down dramatically!

It is strongly recommended that each function added to this hook uses the macro ecb-do-if-buffer-visible-in-ecb-frame at beginning! See ecb-speedbar-buffer-sync and ecb-eshell-buffer-sync for examples how to use this macro!

— User Option: bucket-node-display

How ECB displays bucket-nodes in a ECB tree-buffer. Bucket-nodes have only one job: Nodes with similar properties will be dropped into one bucket for such a common property and all these nodes will be added as children to the bucket-node. Besides being expandable and collapsable a bucket-node has no senseful action assigned. Examples for bucket-nodes are ”[+] Variables”, “[+] Dependencies” etc. in the Methods-buffer or buckets which combine filenames with same extension under a bucket-node with name this extension.

This option defines how bucket-node should be displayed. The name of the bucket-node is computed by ECB but you can define a prefix, a suffix and a special face for the bucket-node

The default are empty prefix/suffix-strings and ecb-bucket-node-face. But an alternative can be for example '(”[” “]” nil) which means no special face and a display like “[+] [<bucket-name>]”.

— User Option: common-tree-buffer-after-create-hook

Local hook running at the end of each tree-buffer creation. Every function of this hook is called once without arguments direct after creating a tree-buffer of ECB and it's local key-map. So for example a function could be added which performs calls of local-set-key to define new keybindings for EVERY tree-buffer.

The following keys must not be rebind in all tree-buffers:

— User Option: mouse-click-destination

Destination of a mouse-button click. Defines in which edit-window (if splitted) ECB does the “right” action (opening a source, jumping to a method/variable etc.) after clicking with the primary mouse-button (see ecb-primary-secondary-mouse-buttons) onto a node. There are two possible choices:

This is if the user has clicked either with the primary mouse-button or has activated a popup-menu in the tree-buffer.

If the edit-area is not splitted this setting doesn't matter.

A click with the secondary mouse-button (see again ecb-primary-secondary-mouse-buttons does the “right” action always in another edit-window related to the setting in this option: If there are two edit-windows then the “other” edit-window is used and for more than 2 edit-windows the “next” edit-window is used (whereas the next edit-window of the last edit-window is the first edit-window).

Note: If the tree-buffers are used with the keyboard instead with the mouse then this option takes effect too because RET is interpreted as primary mouse-button and C-RET as secondary mouse-button!

— User Option: primary-secondary-mouse-buttons

Primary- and secondary mouse button for using the ECB-buffers. A click with the primary button causes the main effect in each ECB-buffer:

A click with the primary mouse-button while the SHIFT-key is pressed called the POWER-click and does the following (depending on the ECB-buffer where the POWER-click occurs):

In addition always the whole node-name is displayed in the minibuffer after a POWER-click (for this see also ecb-methods-show-node-info).

The secondary mouse-button is for opening (jumping to) the file in another edit-window (see the documentation ecb-mouse-click-destination).

The following combinations are possible:

Please note: If the tree-buffers are used with the keyboard instead with the mouse then RET is interpreted as primary mouse-button and C-RET as secondary mouse-button!

If you change this during ECB is activated you must deactivate and activate ECB again to take effect

— User Option: tree-buffer-style

The style of the tree-buffers. There are three different styles available:

Image-style (value image): Very nice and modern - just try it. For this style the options ecb-tree-indent and ecb-tree-expand-symbol-before have no effect! The value 'image means use image-style if images can be displayed with current Emacs-setup \(otherwise auto. 'ascii-style is used). Note: GNU Emacs <= 21.3.X for Windows does not support image-display so ECB uses always 'ascii-guides even when here 'image is set!

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

        [-] 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

With both ascii-styles the tree-layout can be affected with the options ecb-tree-indent and ecb-tree-expand-symbol-before.

— User Option: tree-do-not-leave-window-after-select

Tree-buffers which stay selected after a key- or mouse-selection. If a buffer (either its name or the variable-symbol which holds the name) is contained in this list then selecting a tree-node either by RET or by a mouse-click doesn't leave that tree-buffer after the node-selection but performes only the appropriate action (opening a new source, selecting a method etc.) but point stays in the tree-buffer. In tree-buffers not contained in this option normaly a node-selection selects as “last” action the right edit-window or maximizes the next senseful tree-buffer in case of a currently maximized tree-buffer (see ecb-maximize-next-after-maximized-select).

The buffer-name can either be defined as plain string or with a symbol which contains the buffer-name as value. The latter one is recommended for the builtin ECB-tree-buffers because then simply the related option-symbol can be used.

A special remark for the ecb-directories-buffer-name: Of course here the value of this option is only relevant if the name of the current layout is contained in ecb-show-sources-in-directories-buffer or if the value of ecb-show-sources-in-directories-buffer is 'always and the clicked ot hitted node represents a sourcefile (otherwise this would not make any sense)!

The setting in this option is only the default for each tree-buffer. With the command ecb-toggle-do-not-leave-window-after-select the behavior of a node-selection can be changed fast and easy in a tree-buffer without customizing this option, but of course not for future Emacs sessions!

— User Option: tree-easy-hor-scroll

Scroll step for easy hor. scrolling via mouse-click in tree-buffers. XEmacs has horizontal scroll-bars so invisible parts beyond the right window-border of a tree-buffer can always made visible very easy.

GNU Emacs does not have hor. scroll-bars so especially with the mouse it is quite impossible to scroll smoothly right and left. The functions scroll-left and scroll-right can be annoying and are also not bound to mouse-buttons.

If this option is a positive integer S then in all ECB-tree-buffers the keys M-mouse-1 and M-mouse-3 are bound to scrolling left rsp. right with scroll-step S - clicking with mouse-1 or mouse-2 onto the edge of the modeline has the same effect, i.e. if you click with mouse-1 onto the left (rsp right) edge of the modeline you will scroll left (rsp. right).

Additionally C-M-mouse-1 and C-M-mouse-3 are bound to scrolling left rsp. right with scroll-step window-width - 2.

Default is a scroll-step of 5. If the value is nil then no keys for horizontal scrolling are bound.

— User Option: tree-expand-symbol-before

Show the expand symbol before the items in a tree. When the expand-symbol is located before the items then the tree looks like:

        [-] ECB
            [+] code-save
            [-] ecb-images
                [-] directories

When located after then the tree looks like:

        ECB [-]
          code-save [+]
          ecb-images [-]
            directories [-]

The after-example above use a value of 2 for ecb-tree-indent whereas the before-example uses a value of 4.

It is recommended to display the expand-symbol before because otherwise it could be that with a deep nested item-structure with and/or with long item-names (e.g. a deep directory-structure with some long subdirectory-names) the expand-symbol is not visible in the tree-buffer and the tree-buffer has to be horizontal scrolled to expand an item.

— User Option: tree-image-icons-directories

Directories where the images for the tree-buffer can be found. This is a cons cell where:

car: Default directory where the default images for the tree-buffer can be found. It should contain an image for every name of tree-buffer-tree-image-names. The name of an image-file must be: “ecb-<NAME of TREE-BUFFER-TREE-IMAGE-NAMES>.<ALLOWED EXTENSIONS>”.

cdr: This is a list where each element is a cons again with: car is the buffer name of the tree-buffer for which a special image-path should be used. The buffer-name can either be defined as plain string or with a symbol which contains the buffer-name as value. The latter one is recommended for the builtin ECB-tree-buffers because then simply the related option-symbol can be used (e.g. the symbol ecb-directories-buffer-name). The cdr is the the full-path of an additional image-directorie which is searched first for images needed for the related tree-buffer. If the image can not be found in this directory then the default-directory (see above) is searched. If the image can't even be found there the related ascii-symbol is used - which is defined in tree-buffer-tree-image-names. If a tree-buffer is not contained in this list then there is no additional special image-directory for it.

ECB comes with predefined images in several different heights - so for the most senseful font-heights of a tree-buffer a fitting image-size should be available. The 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 (locate-data-directory “ecb”).

— User Option: tree-incremental-search

Enable incremental search in the ECB-tree-buffers. For a detailed explanation see the online help section “Working with the keyboard in the ECB buffers”. If you change this during ECB is activated you must deactivate and activate ECB again to take effect.

— User Option: tree-indent

Indent size for tree buffer. If you change this during ECB is activated you must deactivate and activate ECB again to take effect.

— User Option: tree-make-parent-node-sticky

Make the parent-node sticky in the headerline of the tree-buffer.

If not nil then the first line of the tree-buffer is used as header-line which is used to display the next unvisible parent of the first visible node as sticky, so always the parent of a node is visible and clickable. If a node has no parent then just the next node above is displayed in the header-line. The node displayed in the header-line is exactly in the same manner clickable as all other nodes.

See also ecb-tree-stickynode-indent-string.

This feature is only available with Gnu Emacs, not with XEmacs.

— User Option: tree-mouse-action-trigger

When the tree-buffer mouse-action should be triggered. This option determines the moment a mouse-action in a tree-buffer is triggered. This can be either direct after pressing a mouse-button (value button-press) or not until releasing the mouse-button (value: button-release).

If you change this during ECB is activated you must deactivate and activate ECB again to take effect!

— User Option: tree-navigation-by-arrow

Enable smart navigation in the tree-windows by horiz. arrow-keys. If not nil then the left- and right-arrow keys work in the ECB tree-window in the following smart way if onto an expandable node:

If this option is changed the new value takes first effect after deactivating ECB and then activating it again!

— User Option: tree-stickynode-indent-string

String used to indent the stickynode. This string is used to match the space used by scrollbars and fringe so it does not appear that the node-name is moving left/right when it lands in the sticky line.

Normally the needed value is computed automatically by ECB. But if the result is not matching this option allows to customize the indent-string. The default value is computed by the function tree-buffer-sticky-default-indent-string, so you can change the needed value with that starting-point.

Changing this option takes only effect after restarting Emacs!

— User Option: tree-truncate-lines

Truncate lines in ECB buffers. If a buffer (either its name or the variable-symbol which holds the name) is contained in this list then line-truncation is switched on for this buffer otherwise it is off.

The buffer-name can either be defined as plain string or with a symbol which contains the buffer-name as value. The latter one is recommended to switch on line-truncation for one of the builtin ECB-tree-buffers because then simply the related option-symbol can be used. To truncate lines in the builtin directories tree-buffer just add the symbol ecb-directories-buffer-name to this option.

If you change this during ECB is activated you must deactivate and activate ECB again to take effect.

— User Option: truncate-long-names

Truncate long names that don't fit in the width of the ECB windows. If you change this during ECB is activated you must deactivate and activate ECB again to take effect.