5. Customizing ECB

This chapter describes how to customize ECB for your personal taste. The first section introduces some general aspects (which you should really know!), the second one gives an overview of the most important options and the third one lists all options of ECB (divided into the customize groups).

5.1 General aspects for customizing ECB

This chapter contains all important informations you should know about customizing ECB. The first section gives an answer to the question "setq or customize" and the second section describes what to do when you have to customize ECB for a lot of people.

5.1.1 Setq or customize - what should i use?

The best way to customize all the options of ECB is via the customize-feature of (X)Emacs, i.e. means calling the commands customize-option or customize-group etc. This is also the strongly recommended way!

But of course you can also use setq or some Elisp-code to change the values of many but not all of the options. The values of the following options MUST NOT be changed via setq or Elisp-code but only with the customize-feature!

• ecb-advice-window-functions
• ecb-bucket-node-display
• ecb-compile-window-height
• ecb-compile-window-temporally-enlarge
• ecb-compile-window-width
• ecb-exclude-parents-regexp
• ecb-fix-window-size
• ecb-font-lock-tags
• ecb-highlight-tag-with-point-delay
• ecb-key-map
• ecb-layout-name
• ecb-layout-window-sizes
• ecb-mode-line-data
• ecb-mode-line-display-window-number
• ecb-mode-line-prefixes
• ecb-show-node-info-in-minibuffer
• ecb-show-tags
• ecb-source-path
• ecb-toggle-layout-sequence
• ecb-tag-display-function
• ecb-tree-RET-selects-edit-window
• ecb-type-tag-display
• ecb-type-tag-expansion
• ecb-use-speedbar-instead-native-tree-buffer
• ecb-window-sync-delay
• ecb-windows-height
• ecb-windows-width

5.1.2 Site-wide customizing of ECB

If you are the administrator for an Emacs-site, means you are responsible for the basic customization of a lot of Emacs users, then you maybe need a way to customize Emacs and ECB without changing everyones `.emacs'-file and normally you will do this with the file `site-start.el'. You can customize all options of ECB in a central `site-start.el' (even the options mentioned above!) but you MUST NOT do this via setq but you have to use a mechanism like the following(23)!

This section describes two methods how to pre-customize ECB site-wide. The elisp-code contained in the following two subsections has to be copied to the file `site-start.el' before it can be used.

But ensure for both methods that you customize the options with the correct lisp format. Read carefully the docstrings of the options you want to customize from within Elisp-code!

5.1.2.1 Storing all option-settings in the users custom-file

The mechanism described here defines all site-wide-settings in a file `site-lisp.el' but stores the values in the users custom-file which is probably `.emacs'!

First two helper functions are needed, namely customize-option-get-value and customize-save-variable-save whereas the latter one sets the value for an option via the customize-mechanism (and is therefore allowed for the setq-forbidden options!) but only if the option has no saved value until now (i.e. the user has not saved this option for future sessions until now)

(defun customize-option-get-value (option type)
  "Return the value of a customizable option OPTION with TYPE, where TYPE
can either be 'standard-value \(the default-value of the defcustom) or
'saved-value \(the value stored durable by the user via customize)."
  (let ((val (car (get option type))))
    (cond ((not (listp val)) val)
          ((equal 'quote (car val)) (car (cdr val)))
          (t (car val)))))

(defun customize-save-variable-save (option value &optional override)
  "Calls `customize-save-variable' with OPTION and VALUE if OPTION is a
custom-type and if OPTION has no saved-value until now.
If OVERRIDE is a function or lambda-form then it is called with two arguments:
- OLD-SAVED-VAL: The saved value of OPTION
- NEW-VALUE: see argument VALUE.
OVERRIDE is only called if OPTION has already a saved-value. If OVERIDE
returns not nil then `customize-save-variable' is called for OPTION with VALUE
even if OPTION has no saved-value until now."
  (and (get option 'custom-type)
       (or (not (get option 'saved-value))
           (and (functionp override)
                (funcall override
                         (customize-option-get-value option 'saved-value)
                         value)))
       (progn
         (message "Overriding saved value for option %s with %s" option value)
         (customize-save-variable option value))))

With customize-save-variable-save all ECB-options can be site-wide pre-customized like follows:

(customize-save-variable-save 'ecb-show-tags
                              '((include collapsed nil)
                                (parent collapsed nil)
                                (type flattened nil)
                                (variable collapsed name)
                                (function flattened name)
                                (rule flattened name)
                                (section flattened nil)
                                (def collapsed name)
                                (t collapsed name)))
(customize-save-variable-save 'ecb-font-lock-tags t)
;; add here more options of ECB it you want

5.1.2.2 Using a special setq for site-wide settings

The mechanism above saves the pre-customized values always in the users custom-file (probably `.emacs'). If this is not preferred, then you can use the following mechanism but of course the offered setq-save is only allowed for options which are not setq-forbidden (see section 5.1.1 Setq or customize - what should i use?).

The mechanism below does not change the users custom-file. This mechanism is needed especially if ECB should be autoloaded and all site-wide settings should first loaded when ECB is activated by the user. This can be achieved for example via(24):

(require 'ecb-autoloads))
(eval-after-load "ecb"
  '(require 'site-ecb))

In such a situation the whole custom-file of a user is mostly loaded before ECB is activated and therefore before the site-wide-settings are loaded. So the users own customizations are loaded before the site-wide ones.

The setq-save-mechanism described below prevents the users own customisations contained in his custom-file from being overridden by the site-wide setq-settings. If setq would be used for the site-wide settings then in an autoload-situation the site-wide settings would override the users-settings and this should not be done!

First two helper-macros are needed:

(defmacro custom-saved-p (option)
  "Return only not nil if OPTION is a defcustom-option and has a
saved value. Option is a variable and is literal \(not evaluated)."
  `(and (get (quote ,option) 'custom-type)
        (get (quote ,option) 'saved-value)))

(defmacro setq-save (option value)
  "Sets OPTION to VALUE if and only if OPTION is not already saved
by customize. Option is a variable and is literal \(not evaluated)."
  `(and (not (custom-saved-p ,option))
        (set (quote ,option) ,value)))

With setq-save all "not-setq-forbidden"-ECB-options can be site-wide pre-customized like follows:

(setq-save ecb-tree-indent 4)
(setq-save ecb-tree-expand-symbol-before t)
(setq-save ecb-primary-secondary-mouse-buttons 'mouse-1--mouse-2)

5.2 The most important options of ECB

Here are the most important options (it is recommended to check at least the following options before working with ECB). You can customize them via the customize-group "ecb-most-important" or via the command ecb-customize-most-important.

ecb-source-path

Where ECB can find your sources. You must set this option!

ecb-show-help-format

Should the online help of ECB be displayed in the standard Info format or in HTML format in a web-browser.

ecb-auto-activate

ecb-major-modes-show-or-hide

Auto. activation of ECB after start (see section 3.2 Automatic activation and deactivation) or major-mode-based showing or hiding the ecb-windows.

ecb-winman-escreen-number

ecb-winman-winring-name

Support of several window-managers (see section 8.16 Support of several Emacs-window-managers).

ecb-key-map

All ECB-keybindings incl. a common prefix-key (see section 4.2 Working with the keyboard in the ECB-windows).

ecb-new-ecb-frame

Should ECB create a new frame at activation time.

ecb-primary-secondary-mouse-buttons

ecb-mouse-click-destination

Define how to use the mouse (see section 4.1 Working with the mouse in the ECB-windows).

ecb-tree-buffer-style

ecb-tree-expand-symbol-before

ecb-tree-indent

ecb-truncate-lines

The look&feel of the trees in the tree-buffers. The former option defines the general style of the tree-buffers and the latter ones allow to customize the ascii-style tree-buffers (maybe you like a value of 4 for the latter one if you display the expand-symbol before (see section 8.17 Displaying the trees of the ECB-windows with different styles).

ecb-source-file-regexps

Which files will (not) be shown in ECB.

ecb-show-node-info-in-minibuffer

When and which node-info should be displayed in the minibuffer?

ecb-layout-name

ecb-compile-window-height

ecb-compile-window-width

ecb-other-window-behavior

The ECB layout, means which windows you want to be displayed in the ECB-frame and also the location of these windows (see section 4.8.1 Changing and customizing the ECB-layout).

ecb-compilation-buffer-names

Which buffers should be treaten as "compilation-buffers" and therefore displayed in the compile-window of ECB - if there is any.

ecb-tag-display-function

ecb-type-tag-display

ecb-type-tag-expansion

ecb-show-tags

How to display the entries in the ECB-method window for semantic supported sources (see section 4.6.3 Customizing the display of the Methods-buffer). These options take only effect for semantic-sources (see Definition of semantic- and non-semantic-sources).

ecb-process-non-semantic-files

Displaying file-contents for not by semantic supported files too, e.g. for LaTeX- and perl-sources (see section 8.14 Parsing and displaying non-semantic sources).

But to make ECB working best for you it is also recommended to have a look at 5.3 All customizable options of ECB!

5.3 All customizable options of ECB

All customization of ECB is divided into the following "customize groups". You can highly customize all the ECB behavior/layout so just go to these groups and you will see all well documented ECB-options.

Please note: All options in the following subsections are listed without the prefix "ecb-" (e.g. the option ecb-layout-name is listed with name "layout-name"). This has been done for a better readable option index. See section Option Index.

5.3.1 Group ecb-general

This group contains general settings for the Emacs code browser:

User Option: activate-before-layout-draw-hook

Normal hook run at the end of activating the ecb-package by running ecb-activate. This hooks are run after all the internal setup process but directly before(!) drawing the layout specified in ecb-layout (means before dividing the frame into several windows).

A senseful using of this hook can be maximizing the Emacs-frame for example, because this should be done before the layout is drawn because ECB computes the size of the ECB-windows with the current frame size! If you need a hook-option for the real end of the activating process (i.e. after the layout-drawing) look at ecb-activate-hook.

IMPORTANT: The difference between this hook and ecb-redraw-layout-before-hook is that the latter one is evaluated always before the layout is redrawn (for example after calling ecb-redraw-layout) whereas the former one (this hook) is only evaluated exactly once during the activation-process of ECB. So during the activation process there is the following sequence of hooks:

1. ecb-activate-before-layout-draw-hook \(this one)
2. ecb-redraw-layout-before-hook
3. <Drawing the layout>
4. ecb-redraw-layout-after-hook
5. ecb-activate-hook

User Option: activate-hook

Hook run at the end of activating ECB by ecb-activate. This hooks are run at the real end of the activating process, means after the layout has been drawn!. If you need hooks which are run direct before the layout-drawing look at ecb-activate-before-layout-draw-hook.

User Option: activation-selects-ecb-frame-if-already-active

Trying to activate an already activated ECB selects the ECB-frame. If t then the ECB-frame is selected, if nil then it is not. If 'ask then ECB asks if the ECB-frame should be selected if the current-frame is not the ecb-frame.

User Option: auto-activate

Automatically startup ECB when Emacs starts up. This should only be true if you always want to run ecb-activate.

User Option: auto-compatibility-check

Check at ECB-startup if all ECB-options have correct values. If not nil then all ECB-options are checked if their current value have the correct type. It the type is incorrect the option is either auto. upgraded to the new type or reset to the default-value of current ECB if no upgrade is possible. This feature can also upgrade options which are renamed in current ECB and try to transform the old-value to the new named option. After startup all upgraded or reset options are displayed with their old (before upgrade/reset) and new values. See also the commands ecb-upgrade-options and ecb-display-upgraded-options. If this option is off then the user can perform the check and reset manually with ecb-upgrade-options. See section 7.2 Automatic upgrading of options.

User Option: before-activate-hook

Normal hook run at the beginning of activating the ecb-package by running ecb-activate. These hooks run before any other tasks of the activating process are performed. If any of these hooks returns nil then ECB will not be activated!

This can be used to check some conditions and then only start ECB if all conditions are true. For example a function could be added which returns only nil if Gnus is running. Then calling ecb-activate or ecb-minor-mode will only start ECB if Gnus is not already running.

User Option: before-deactivate-hook

Normal hook run at the beginning of deactivating ECB by running ecb-deactivate. These hooks run before any other tasks of the deactivating process are performed. If any of these hooks returns nil then ECB will not be deactivated! See also ecb-before-activate-hook.

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: clear-caches-before-activate

Clear all ECB internal caches before startup. If t then ECB clears all its internal caches before starting up. Caches are used for files- and subdirs (see ecb-cache-directory-contents and ecb-cache-directory-contents-not) for semantic-tags and for the history-filter.

This caches are completely clean at load-time of the ECB-library!

Default is nil, because is makes sense not to clear these caches at start-time because ECB is often deacticated temporally especially in combination with window-managers like escreen.el. In these situations the internal state of ECB should be preserved for next activation.

User Option: current-buffer-sync-hook

Normal hook run at the end of ecb-current-buffer-sync.

See documentation of ecb-current-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 current selected edit-window.

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

Important note: If ecb-window-sync is not nil ecb-current-buffer-sync is running either every time Emacs is idle or even after every command (see ecb-window-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-current-buffer-sync and ecb-eshell-current-buffer-sync for examples how to use this macro!

User Option: deactivate-hook

Normal hook run at the end of deactivating (but before the ecb-layout is cleared!) ECB by running ecb-deactivate.

User Option: debug-mode

If not nil ECB displays debug-information in the Messages-buffer. This is done for some critical situations concerning semantic-tags and their overlays (or extends for XEmacs). Normally you should not need this switched on! But if you get errors like "destroyed extend" for XEmacs or "wrong-argument-type" concerning overlays for GNU Emacs then you should switch on this option and submitting a bug-report to the ecb-mailing-list (ecb-submit-problem-report) after getting the error again!

User Option: grep-function

Function used for performing a grep. The popup-menu of the tree-buffers "Directories", "Sources" and "History" offer to grep the "current" directory:

• Directory-buffer: The grep is performed in the current popup-directory after clicking the right mouse-button onto a node.
• Sources-buffer: The grep is performed in the current selected directory.
• History-buffer: The grep is performed in the directory of the current popup-source after clicking the right mouse-button onto a node.

User Option: grep-find-function

Function used for performing a recursive grep. For more Details see option `ecb-grep-function' and replace "grep" with "recursive grep".

User Option: key-map

Specifies all keybindings for the ECB minor-mode key-map. The value is a cons-cell where the car is a common-prefix key for all the keybindings. The cdr is a list of keybindings each of them a list again. A key-binding has the following form:

'(<common-prefix-flag> <keysequence> <function>) where

<common-prefix-flag>

If t then the common-prefix-key defined as car of the value (see above) is used.

<keysequence>

If the common prefix-key is used then the final key-binding is the concatenation of the common-prefix-key (see above) and this keysequence.

<function>:

The function to bind to the key. This can also be a lambda-expression .

It is highly recommended to use one of the standard keys C-c or C-x as first key of your common-prefix-key!

You MUST change this option via customize to take effect!

All keysequences must be inserted as a string and must follow the syntax needed by read-kbd-macro or kbd. This means you can insert the key in the same manner C-h k displays keysequences. Here is the summary of the syntax:

Text is divided into "words" separated by whitespace. Except for the words described below, the characters of each word go directly as characters of the keysequence. The whitespace that separates words is ignored. Whitespace in the macro must be written explicitly, as in C-c SPC.

• The special words RET, SPC, TAB, DEL, LFD, ESC, and NUL represent special control characters. The words must be written in uppercase.

• A word in angle brackets, e.g., <return>, <down>, <left> or <f1>, represents a function key. (Note that in the standard configuration, the function key <return> and the control key RET are synonymous.). You can use angle brackets on the words RET, SPC, etc., but they are not required there.

• Keys can be written by their ASCII code, using a backslash followed by up to six octal digits. This is the only way to represent keys with codes above ÿ.

• One or more prefixes M- (meta), C- (control), S- (shift), A- (alt), H- (hyper), and s- (super) may precede a character or key notation. For function keys, the prefixes may go inside or outside of the brackets: C-<down> = <C-down>. The prefixes may be written in any order: M-C-x = C-M-x. Prefixes are not allowed on multi-key words, e.g., C-abc, except that the Meta prefix is allowed on a sequence of digits and optional minus sign: M--123 = M-- M-1 M-2 M-3.

• The ^ notation for control characters also works: ^M = C-m.

User Option: major-modes-show-or-hide

List of major-modes which show or hide the ecb-windows. The value is a cons-cell where the car contains all major-mode-symbols which should show the special ecb-windows and the cdr contains all major-mode-symbols which should hide the special ecb-windows. If the symbol of a major-mode is neither contained in the car-"show-list" nor in the cdr-"hide-list" then the visibility-state of the ecb-windows does not change.

User Option: minor-mode-text

String to display in the mode line when ECB minor mode is active. (When the string is not empty, make sure that it has a leading space.)

Because for ECB it is quite obvious if it is active or not when the ECB-windows are visible this text is only display in the modeline if the ECB-windows are hidden.

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:

• left-top: Does the "right" action always in the left/topmost edit-window.
• last-point: Does the "right" action always in that edit-window which had the point before.

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: run-ediff-in-ecb-frame

Run ediff-sessions in the same frame as ECB is running. If not nil then ECB ensures that ediff runs in the same frame as ECB and ECB restores exactly the "before-ediff"-window-layout after quiting ediff. If nil then ediff decides in which frame it will run - depending on the current window-layout (e.g. if the ecb-windows are currently hidden) this can be the ecb-frame but this can also be a newly created frame or any other frame.

User Option: stealthy-tasks-delay

Time Emacs must be idle before ECB runs its stealthy tasks. Currently ECB performes the following stealthy tasks:

Prescann directories for emptyness

Prescann directories and display them as empty or not-empty in the directories-buffer. See the documentation of the option ecb-prescan-directories-for-emptyness for a description.

File is read only

Check if sourcefile-items of the directories- or sources-buffer are read-only or not. See documentation of the option ecb-sources-perform-read-only-check.

Version-control-state

Checks the version-control-state of files in directories which are managed by a VC-backend. See the option ecb-vc-enable-support.

Here the interval is defined ECB has to be idle before starting with these stealthy tasks. It can be a floating-point value in seconds. The value can also be changed during running ECB.

User Option: tip-of-the-day

Show tip of the day at start time of ECB.

User Option: tip-of-the-day-file

File where tip-of-the-day cursor is stored.

User Option: use-recursive-edit

Tell ECB to use a recursive edit. If set then it can easily be deactivated by (keyboard-escape-quit).

User Option: version-check

Checks at start-time if the requirements are fulfilled. It checks if the required versions of the libraries semantic, eieio and speedbar are installed and loaded into Emacs.

It is strongly recommended to set this option to not nil!

User Option: window-sync

Synchronize the ECB-windows automatically with current edit window. 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 current active 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-current-buffer-sync-hook is evaluated.

User Option: window-sync-delay

Time Emacs must be idle before the ECB-windows are synchronized with current 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.

5.3.2 Group ecb-tree-buffer

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

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:

• RET and all combinations with Shift and Ctrl
• TAB
• C-t

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:

• ECB Directories: Expanding/collapsing nodes and displaying files in the ECB Sources buffer.

• ECB sources/history: Opening the file in that edit-window specified by the option ecb-mouse-click-destination.

• ECB Methods: Jumping to the method in that edit-window specified by the option ecb-mouse-click-destination.

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):

• ECB Directories: Refreshing the directory-contents-cache (see ecb-cache-directory-contents).

• ECB sources/history: Only displaying the source-contents in the method-buffer but not displaying the source-file in the edit-window.

• ECB Methods: Narrowing to the clicked method/variable/ect... (see ecb-tag-visit-post-actions). This works only for semantic supported sources but not for imenu- or etags-supported ones!

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

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:

• primary: mouse-2, secondary: C-mouse-2 (means mouse-2 while CTRL-key is pressed). This is the default setting.
• primary: mouse-1, secondary: C-mouse-1
• primary: mouse-1, secondary: mouse-2

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: show-node-info-in-minibuffer

Node info to display in a tree-buffer. Define which node info should displayed in a tree-buffer after mouse moving over the node or after a shift click onto the node.

For every tree-buffer you can define "when" node info should be displayed:

• always: Node info is displayed by moving with the mouse over a node.
• if-too-long: Node info is only displayed by moving with the mouse over a node does not fit into the window-width of the tree-buffer window. In the ECB directories buffer this means also if a node is shortened or if the node has an alias (see ecb-source-path).
• shift-click: Node info is only displayed after a shift click with the primary mouse button onto the node.
• never: Node info is never displayed.

For every tree-buffer you can define what info should be displayed:

• Directory-buffer:
  • name: Only the full node-name is displayed.
  • path: The full-path of the node is displayed.

• Sources-buffer:
  • name: Only the full node-name is displayed.
  • file-info: File infos for this file are displayed.
  • file-info-full: Fill infos incl. full path for this file are displayed.
• History-buffer: see Directories-buffer.
• Methods-buffer:
  • name: Only the full node name is displayed.
  • name+type: The full name + the type of the node (function, class, variable) is displayed.

Do NOT set this option directly via setq but use always customize!

User Option: tree-RET-selects-edit-window

In which tree-buffers RET should finally select an edit-window. If one of the symbols ecb-directories-buffer-name, ecb-sources-buffer-name, ecb-methods-buffer-name or ecb-history-buffer-name is contained in this list then hitting RET in the associated tree-buffer selects as last action the right edit-window otherwise only the right action is performed (opening a new source, selecting a method etc.) but point stays in the tree-buffer.

A special remark for the ecb-directories-buffer-name: Of course here the edit-window is only selected 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 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 ecb-toggle-RET-selects-edit-window the behavior of RET 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-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! 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-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 five-element list where:

1. element: 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>".
2. element: Directory for special images for the Directories-buffer.
3. element: Directory for special images for the Sources-buffer.
4. element: Directory for special images for the Methods-buffer.
5. element: Directory for special images for the History-buffer.

The directories of the element 2 - 5 are additional image-directories which are searched first for images needed for the respective tree-buffer. If the image can not be found in this directory then the default-directory (1. element) is searched. If the image can't even found there the related ascii-symbol is used.

All but the first element (the default directory) can be nil.

ECB comes with images in four diffenent 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.

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-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:

• Left-arrow: If node is expanded then it will be collapsed otherwise point jumps to the next "higher" node in the hierarchical tree (higher means the next higher tree-level or - if no higher level available - the next higher node on the same level).

• Right-arrow: If node is not expanded then it will be expanded. Onto a not expandable node the horizontal arrow-keys go one character in the senseful correct direction.

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

User Option: truncate-lines

Truncate lines in ECB buffers. 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.

5.3.3 Group ecb-directories

This group contains settings for the directories-buffer in the ECB:

User Option: add-path-for-not-matching-files

Add path of a file to ecb-source-path if not already contained. This is done during the auto. windows synchronization which happens if a file is opened not via the file/directory-browser of ECB. In such a situation ECB adds the path of the new file auto. to ecb-source-path at least temporally for the current Emacs session. This option defines two things:

1. Should only the root-part (which means for Unix-like systems always '/' and for windows-like systems the drive) of the new file be added as source-path to ecb-source-path or the whole directory-part? For remote-files (e.g. tramp, ange-ftp- or efs-files) the root-part is the complete host-part + the root-dir at that host (example: /berndl@ecb.sourceforge.net:/ would be the root-part of /berndl@ecb.sourceforge.net:/tmp/test.txt).
2. Should this path be added for future sessions too?

The value of this option is a cons-cell where the car is a boolean for 1. and the cdr is a boolean for 2.

A value of not nil for the car (1.) is reasonably if a user often opens files not via the ECB-browser which are not located in any of the paths of ecb-source-path because then only one path for each drive (windows) or the root-path (Unix) is added to the directory buffer of ECB.

User Option: auto-expand-directory-tree

Automatically expand the directory tree to the current source file. There are three options:

• best: Expand the best-matching source-path
• first: Expand the first matching source-path
• nil: Do not automatically expand the directory tree.

User Option: after-directory-change-hook

Hook which run directly after the selected directory has changed. This means not onyl after a click onto a directory in the directory-window of ECB but it means this hook runs always when the current directory changes regardless of the trigger of this change. So for example it runs also when you just switches from one buffer to another via switch-to-buffer or switch-to-buffer-other-window and the directory of these filebuffers is different but only when auto-synchronizing of the ECB-windows is on (see ecb-window-sync). It runs not when switching between buffers and the associated files reside in the same directory.

Each function added to this hook will be called with two arguments: The directory which was current _before_ the directory-change-trigger and the directory which was now the current (i.e. after the trigger).

Example: If you switch from a filebuffer "~/.emacs" to a filebuffer "/tmp/test.txt" then the functions of this hook will be called with the two arguments "~" and "/tmp".

User Option: cache-directory-contents

Cache contents of directories.

This can be useful if ecb-source-path contains directories with many files and subdirs, especially if these directories are mounted net-drives ("many" means here something > 500, dependent of the speed of the net-connection and the machine). Or if it contains remote-source-paths which means paths in the sense of tramp, ange-ftp or efs. For these directories actualizing the sources- and/or directories- buffer of ECB (if displayed in current layout!) can slow down dramatically so a caching increases speed a lot. The value of this option is a list where each element is a cons-cell and looks like:

(<dir-regexp> . <filenumber threshold>) with

<dir-regexp>:

Regular expression a directory must match to be cached.

<filenumber threshold>:

Number of directory contents must exceed this number.

A directory will only be cached if and only if the directory-name matches at least one rexexp of this option and its content-number exceeds the related threshold AND the directory-name matches NOT any regexp of ecb-cache-directory-contents-not!

The cache entry for a certain directory will be refreshed and actualized only by using the POWER-click (see ecb-primary-secondary-mouse-buttons) in the directories-buffer of ECB (see section 4.1 Working with the mouse in the ECB-windows).

Default-value: ECB caches the contents of all remote directories regardless of the size and all other directories if more than 50 entries are contained.

Examples:

An entry ("/usr/home/john_smith/bigdir*" . 1000) means the contents of every subdirectory of the home-directory of John Smith will be cached if the directory contains more than 1000 entries and its name begins with "bigdir".

An entry (".*" . 1000) caches every directory which has more than 1000 entries.

An entry ("^/\\([^:/]*@\\)?\\([^@:/]*\\):.*" . 0) caches every remote (in the sense of tramp, ange-ftp or efs) directory regardless of the number of entries."

Please note: If you want your home-dir being cached then you MUST NOT use "~" because ECB tries always to match full path-names!

User Option: cache-directory-contents-not

Do not cache the contents of certain directories. The value of this option is a list where the each element is a regular expression a directory must match if it should not being cached.

If a directory-name matches at least one of the regexps of this option the directory-contents will never being cached. See ecb-cache-directory-contents to see when a directory will be cached.

This option can be useful when normally all directories with a certain amount of content (files and subdirs) should be cached but some special directories not. This can be achieved by:

• Setting ecb-cache-directory-contents to ((".*" . 500)): Caches all directories with more then 500 entries

• Setting ecb-cache-directory-contents-not to a value which matches these directories which should not being cached (e.g. ("/usr/home/john_smith") excludes the HOME-directory of John Smith from being cached).

Please note: If you want your home-dir exclude from being cached then you MUST NOT use "~" because ECB tries always to match full path-names!

User Option: directories-buffer-after-create-hook

Local hook running after the creation of the directories-buffer. Every function of this hook is called once without arguments direct after creating the directories-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 only for the directories-buffer of ECB.

The following keys must not be rebind in the directories-buffer: F2, F3 and F4

User Option: directories-buffer-name

Name of the ECB directory buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. " *ECB Directories*".

If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-directory-buffer by this name, e.g. by a call of set-buffer.

Changes for this option at runtime will take affect only after deactivating and then activating ECB again!

User Option: directories-menu-sorter

Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to re-arrange the menu-entries of the combined menu-entries of the user-menu-extensions of ecb-directories-menu-user-extension and the built-in-menu ecb-directories-menu. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries.

The function get one argument, a list of menu-entries. For the format of this argument see ecb-directories-menu-user-extension. The function must return a new list in the same format. Of course this function can not only re-arrange the entries but also delete entries or add new entries.

User Option: directories-menu-user-extension

Static user extensions for the popup-menu of the directories buffer. Value is a list of elements of the following type: Each element defines a new menu-entry and is either:

1. Menu-command: A list containing two sub-elements, whereas the first is the function (a function symbol) being called if the menu-entry is selected and the second is the name of the menu-entry.

2. Separator: A one-element-list and the element is the string "---": Then a non-selectable menu-separator is displayed.

3. Submenu: A list where the first element is the title of the submenu displayed in the main-menu and all other elements are either menu-commands (see 1) or separators (see 2) or another submenu (see c). This allows deep nested menu-submenu-structures. Currently a level of 4 is allowed but in general there could be an infinite depth of nesting but it makes no sense - if possible at all - to define infinite nested defcustom-types. So there is a limit of 4 levels but tis is not a hard limit: Just increase the value of the ecb-max-submenu-depth BEFORE first loading ECB!

The function of a menu-command must follow the following guidelines: Such a function must be defined with the macro tree-buffer-defpopup-command! This macro defines a new popup-command whereas the newly defined command gets one argument NODE. See the docstring of tree-buffer-defpopup-command for further details.

Example for the definition of such a menu-function:

(tree-buffer-defpopup-command ecb-my-special-dir-popup-function "Prints the name of the directory of the node under point." (let ((node-data=dir (tree-node-get-data node))) (message ``Dir under node: %s'' node-data=dir)))

Per default the static user-extensions are added at the beginning of the built-in menu-entries of ecb-directories-menu but the whole menu can be re-arranged with ecb-directories-menu-sorter.

These menu-extensions are static. A dynamic menu-extension can be achieved via ecb-directories-menu-user-extension-function.

User Option: directories-menu-user-extension-function

Dynamic user extensions for the popup-menu of the directories buffer. A function which has to return a list in the same format like the option ecb-directories-menu-user-extension. This function is called when the user opens the popup-menu for the directories buffer.

Per default the dynamic user-extensions are added in front of the static extensions of ecb-directories-menu-user-extension but the whole menu can be re-arranged with ecb-directories-menu-sorter.

User Option: display-default-dir-after-start

Automatically display current default-directory after activating ECB.

If a file-buffer is displayed in the current active edit-window then ECB synchronizes its tree-buffers to this file-buffer - at least if the option ecb-window-sync it not nil. So for this situation ecb-display-default-dir-after-start takes no effect but this option is for the case if no file-buffer is displayed in the edit-window after startup:

If true then ECB selects autom. the current default-directory after activation even if no file-buffer is displayed in the current active edit-window. This is useful if ECB is autom. activated after startup of Emacs and Emacs is started without a file-argument. So the directory from which the startup has performed is auto. selected in the ECB-directories buffer and the ECB-sources buffer displays the contents of this directory.

User Option: excluded-directories-regexps

Directories that should not be included in the directories list. The value of this variable should be a list of regular expression.

User Option: prescan-directories-for-emptyness

Prescan directories for emptyness. ECB does this so directories are displayed as empty in the directories-buffer even without user-interaction (i.e. in previous ECB-versions the emptyness of a directory has been first checked when the user has clicked onto a directory). ECB optimizes this check as best as possible but if a directory contains a lot of subdirectories which contain in turn a lot of entries, then expanding such a directory or selecting it would take of course more time as without this check - at least at the first time (all following selects of a directory uses the cached information if its subdirectories are empty or not). Therefore ECB performs this check stealthy (see ecb-stealthy-tasks-delay) so normally there should no performance-decrease or additional waiting-time for the user. There is one exception: For remote directories (in the sense of tramp, ange-ftp, or efs) this check can descrease performance even if performed stealthy and interruptable. Therefore this option offers three possible settings:

• t Switch on this feature

• unless-remote Switch on this feature but not for remote directories. The term "remote" means here directories which are used via tramp, ange-ftp or efs. So mounted directories are counted not as remote directories here even if such a directory is maybe hosted on a remote machine. But normally only directories in a LAN are mounted so there should be no performance-problems with such mounted directories.

• nil Switch off this feature completely.

The option ecb-prescan-directories-exclude-regexps offers are more fine granularity to exclude certain directories from this prescan.

User Option: host-accessible-check-valid-time

Time in seconds a cached accessible-state of a remote host is valid. This option is a list where each element specifies how long for a certain remote host the cached ping-state (i.e. if the host is accessible or not) should be valid. During this time-intervall ECB pings such a remote host only once, all other checks use the cached value of that real check. But it the cached value is older than the value of this option ECB will ping again.

Per default ECB discards after 1 minute the cached ping-state of each remote host. But if you are sure that a certain remote host is always accessible (i.e. means in consequence that you are always online when working with ECB and remote-paths) then add an entry to this option with a high valid-interval.

Examples: An entry (".*sourceforge.*" . 3600) ensures that all remote hosts machting the string "sourceforge" will only once pinged during one hour. Or (".*" . 300) would ensure that every remote host would be pinged only once during 5 minutes.

User Option: ping-options

List of options for the ping program. These options can be used to limit how many ICMP packets are emitted. Ping is used to test if a remote host of a remote path (e.g. a tramp-, ange-ftp- or efs-path) is accessible See also ecb-ping-program.

User Option: ping-program

Program to send network test packets to a host. See also ecb-ping-options.

User Option: prescan-directories-exclude-regexps

Which directories should be excluded from the empty-prescan. If a directory matches any of the regexps of this option it will not be prescanned for emptyness - This option takes only effect if ecb-prescan-directories-for-emptyness is not nil.

User Option: show-sources-in-directories-buffer

Show source files in directories buffer.

User Option: source-path

Paths where to find code sources. Each path can have an optional alias that is used as it's display name. If no alias is set, the path is used as display name.

User Option: source-path

Paths where to find code sources. Each path can have an optional alias that is used as it's display name. If no alias is set, the path is used as display name.

Lisp-type of tis option: The value must be a list L whereas each element of L is either

• a simple string which has to be the full path of a directory (this string is displayed in the directory-browser of ECB) or

• a 2-element list whereas the first element is the full path of a directory (string) and the second element is an arbitrary alias (string) for this directory which is then displayed instead of the underlying directory.

User Option: use-speedbar-instead-native-tree-buffer

If true then uses speedbar for directories, sources or methods. This means that speedbar is integrated in the ECB-frame and is displayed in that window normally displaying the standard ECB-directories-buffer, ECB-sources-buffer or ECB-methods-buffer.

This option takes effect in all layouts which contain either a directory window, a sources window or a method window.

This option can have four valid values:

• nil: Do not use speedbar (default)
• dir: Use speedbar instead of the standard directories-buffer
• source: Use speedbar instead of the standard sources-buffer
• method: Use speedbar instead of the standard methods-buffer

Note: For directories and sources a similar effect and usability is available by setting this option to nil (or method) and setting ecb-show-sources-in-directories-buffer to not nil, because this combination displays also directories and sources in one window.

ecb-use-speedbar-instead-native-tree-buffer is for people who like the speedbar way handling directories and source-files or methods and want it in conjunction with ECB.

5.3.4 Group ecb-sources

This group contains settings for the sources-buffer in the ECB:

User Option: read-only-check-exclude-regexps

Which directories should be excluded from the sources-read-only-check. If a directory matches any of the regexps of this option their sources will not be checked if they are writable - This option takes only effect if ecb-sources-perform-read-only-check is not nil.

User Option: show-source-file-extension

Show the file extension of source files.

User Option: source-file-regexps

Specifies which files are shown as source files.

This is done on directory-base, which means for each directory-regexp the files to display can be specified. If more than one directory-regexp matches the current selected directory then always the first one (and its related file-exclude/include-regexps) is used! If no directory-regexp matches then all files are displayed for the currently selected directory.

Important note: It is recommended that the *LAST* element of this list should contain an always matching directory-regexp (".*")!

So the value of this option is a list of cons-cells where the car is a directory regexp and the cdr is a 2 element list where the first element is a list of exclude regexps and the second element is a list of include regexps. A file is displayed in the source-buffer of ECB iff: The file does not match any of the exclude regexps OR the file matches at least one of the include regexps.

But regardless of the value of this option a file F is never displayed in the sources-buffer if the directory matches ecb-sources-exclude-cvsignore and the directory contains a file .cvsignore which contains F as an entry!

There are three predefined and useful combinations of an exclude and include regexp:

• All files

• All, but no backup, object, lib or ini-files (except .emacs and .gnus). This means all files except those starting with ".", "#" or ending with "~", ".elc", ".obj", ".o", ".lib", ".dll", ".a", ".so". (but including .emacs and .gnus)

• Common source file types (.c, .java etc.)

In addition to these predefined values a custom exclude and include combination can be defined.

Tips for the directory- and file-rexexps: "$^" matches no files/directories, ".*" matches all files/directories.

User Option: sources-buffer-after-create-hook

Local hook running after the creation of the sources-buffer. Every function of this hook is called once without arguments direct after creating the sources-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 only for the sources-buffer of ECB.

User Option: sources-buffer-name

Name of the ECB sources buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. "*ECB Sources*".

If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-sources-buffer by this name, e.g. by a call of set-buffer.

Changes for this option at runtime will take affect only after deactivating and then activating ECB again!

User Option: sources-exclude-cvsignore

Specify if files contained in a `.cvsignore' should be excluded.

Value is a list of regular expressions or nil. If you want to exclude files listed in a `.cvsignore'-file from being displayed in the ecb-sources-buffer then specify a regexp for such a directory.

If you want to exclude the contents of `.cvsignore'-files for every directory then you should add one regexp ".*" which matches every directory.

If you never want to exclude the contents of `.cvsignore'-files then set this option to nil.

User Option: sources-menu-sorter

Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to sort the menu-entries of the combined menu-entries of the user-menu-extensions of ecb-sources-menu-user-extension and the built-in-menu ecb-sources-menu. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries.

For the guidelines for such a sorter-function see ecb-directories-menu-sorter.

User Option: sources-menu-user-extension

Static user extensions for the popup-menu of the sources buffer. For further explanations see ecb-directories-menu-user-extension.

The node-argument of a menu-function contains as data the filename of the source for which the popup-menu has been opened.

Per default the static user-extensions are added at the beginning of the built-in menu-entries of ecb-sources-menu but the whole menu can be re-arranged with ecb-sources-menu-sorter.

User Option: sources-menu-user-extension-function

Dynamic user extensions for the popup-menu of the sources buffer. A function which has to return a list in the same format like the option ecb-sources-menu-user-extension. This function is called when the user opens the popup-menu for the sources buffer.

Per default the dynamic user-extensions are added in front of the static extensions of ecb-sources-menu-user-extension but the whole menu can be re-arranged with ecb-sources-menu-sorter.

User Option: sources-perform-read-only-check

Check if source-items in the tree-buffers are read-only. If a sourcefile is read-only then it will be displayed with that face set in the option ecb-source-read-only-face.

Because this check can be take some time if files are used via a mounted net-drive ECB performs this check stealthy (see ecb-stealthy-tasks-delay) so normally there should no performance-decrease or additional waiting-time for the user. But to get sure this option offers three choices: t, unless-remote and nil. See ecb-prescan-directories-for-emptyness for an explanation for these three choices.

The option ecb-read-only-check-exclude-regexps offers are more fine granularity to exclude the sources of certain directories from the read-only state-check.

User Option: sources-sort-ignore-case

Ignore case for sorting the source-files of the Sources-buffer. See also ecb-sources-sort-method.

User Option: sources-sort-method

Defines how the source files are sorted.

• name: Sorting by name.
• extension: Sorting first by extension and then by name.
• nil: No sorting, means source files are displayed in the sequence returned by directory-files (called without sorting).

See also ecb-sources-sort-ignore-case

5.3.5 Group ecb-methods

This group contains settings for the methods-buffer in the ECB:

User Option: auto-expand-tag-tree

Expand the methods-tag-tree automatically if node invisible.

This option has only an effect if option ecb-highlight-tag-with-point is switched on too. There are three possible choices:

• nil: No auto. expanding of the method buffer.
• expand-spec: Auto expand the method-buffer nodes if the node belonging to current tag under point is invisible because its parent-node is collapsed. But expanding is only done if the type of the tag under point in the edit-buffer is contained in ecb-methods-nodes-expand-spec.
• all: Like expand-spec but expands all tags regardless of the setting in ecb-methods-nodes-expand-spec.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: auto-expand-tag-tree-collapse-other

Auto. expanding the tag-tree collapses all not related nodes. There are several choices:

• Only if on tag: This means collapsing all nodes which have no relevance for the currently highlighted node will be collapsed, because they are not necessary to make the highlighted node visible. But do this only if point stays onto a tag in the selected edit-window.

• Always: Same as before but collapse also when point doesn't stays on a tag (e.g. between two defuns in elisp) in the selected edit-window. This means in such a situation a full collapsing of the methods-buffer.

• Never: Do not automatically collapse the methods-buffer.

User Option: auto-update-methods-after-save

Automatically updating the ECB method buffer after saving a source.

User Option: default-tag-filter

Default tag-filters for certain files. This option allow to define default tag-filters for certain files which are applied automatically after loading such a file into a buffer. The possible filters are the same as offered by the command ecb-methods-filter and they are applied in the same manner - the only difference is they are applied automatically. Please be aware that symbol-filters (e.g. protection-symbols like public or private) must not be inserted with quotes whereas a filter-regexp has to be inserted with surrounding double-quotes! In addition backslashes in a regexp have to be doubled!

For each file-spec (a major-mode plus a file-regexp which both specify a file for which filters should be applied) there can be as much filters as needed - they are layered like with ecb-methods-filter too.

Tag-classes which are completely hidden or excluded by the option ecb-show-tags will never being displayed in the Methods-buffer regardless of the filters of this option!

User Option: display-image-icons-for-semantic-tags

Display nice and pretty icons for semantic-tags in the Methods-buffer. This option takes only effect if Emacs can display images and if ecb-tree-buffer-style is set to image.

User Option: exclude-parents-regexp

Regexps which parent classes should not be shown in the methods buffer (see also ecb-show-parents). If nil then all parents will be shown if ecb-show-parents is not nil.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: expand-methods-switch-off-auto-expand

Switch off auto expanding in the ECB-method buffer. If on then auto expanding is switched off after explicit expanding or collapsing by ecb-expand-methods-nodes.

This is done with ecb-toggle-auto-expand-tag-tree so after the switch off the auto expanding feature can again switched on quickly.

But after explicitly expanding/collapsing the methods-buffer to a certain level the auto. expanding could undo this when the node belonging to current tag under point in the current active edit-window is invisible after ecb-expand-methods-nodes - then the auto. expand feature would make this node immediately visible and destroys the explicitly set expand-level.

User Option: font-lock-tags

Adds font-locking (means highlighting) to the ECB-method buffer.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: highlight-tag-with-point

How to highlight the method or variable under the cursor.

• highlight-scroll: Always scroll the method buffer, so the current method of the edit-window is highlighted in the method-window.
• highlight: Only highlight the current method of the edit window in the method window if the method is visible in the method-window.
• nil: No highlighting is done.

See also ecb-highlight-tag-with-point-delay.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: highlight-tag-with-point-delay

Time Emacs must be idle before current tag is highlighted. If nil then there is no delay, means current tag is highlighted 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. But such a delay prevents also "jumping backward/forward" during scrolling within java-classes if point goes out of method-definition into class-definition. Therefore the default value is a delay of 0.25 seconds.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: methods-buffer-after-create-hook

Local hook running after the creation of the methods-buffer. Every function of this hook is called once without arguments direct after creating the methods-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 only for the methods-buffer of ECB.

User Option: methods-buffer-name

Name of the ECB methods buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. " *ECB Methods*".

If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-methods-buffer by this name, e.g. by a call of set-buffer.

Changes for this option at runtime will take affect only after deactivating and then activating ECB again!

User Option: methods-filter-replace-existing

How the methods-filter should be applied to existing filters. There are three different choices:

• never: This is the default and means that calling ecb-methods-filter always adds the new filter on top of already existing filters. So you can combine several filter to one combined like this example: 'Display only all public methods having the string "test" in its name.' With this setting the filters can only be cleared by calling ecb-methods-filter and then choosing "nothing".

• always: This means that ecb-methods-filter always clears a previous filter before applying the new one.

• ask: ECB asks if the new filter should replace the existing ones.

User Option: methods-menu-sorter

Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to sort the menu-entries of the combined menu-entries of the user-menu-extensions of ecb-methods-menu-user-extension and the built-in-menu ecb-methods-menu. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries.

For the guidelines for such a sorter-function see ecb-directories-menu-sorter.

User Option: methods-menu-user-extension

Static user extensions for the popup-menu of the methods buffer. For further explanations see ecb-directories-menu-user-extension.

The node-argument of a menu-function contains as data the semantic-tag of the method/variable/tag for which the popup-menu has been opened.

Per default the static user-extensions are added at the beginning of the built-in menu-entries of ecb-methods-menu but the whole menu can be re-arranged with ecb-methods-menu-sorter.

User Option: methods-menu-user-extension-function

Dynamic user extensions for the popup-menu of the methods buffer. A function which has to return a list in the same format like the option ecb-methods-menu-user-extension. This function is called when the user opens the popup-menu for the methods buffer. For an example how such a function can be programmed see ecb-methods-menu-editwin-entries.

Per default the dynamic user-extensions are added in front of the static extensions of ecb-methods-menu-user-extension but the whole menu can be re-arranged with ecb-methods-menu-sorter.

User Option: methods-nodes-collapse-spec

Semantic tag-types collapsed by ecb-expand-methods-nodes. For valid values of this option see ecb-methods-nodes-expand-spec!

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: methods-nodes-expand-spec

Semantic tag-types expanded by ecb-expand-methods-nodes.

The value of this option is either the symbol all (all tags are expanded regardless of their type) or a list of symbols where each symbol is a valid semantic tag-type. For a description of semantic tag types see option ecb-show-tags.

But this option also defines if bucket-nodes in the ECB-method-buffer (e.g. "[Variables]") should be expanded. Therefore valid symbols for this list are also all cars of the variable returned by ecb--semantic-symbol->name-assoc-list.

If there is a bucket-name (the node-name stripped of the settings in ecb-bucket-node-display) which is not contained as cdr in the value returned by ecb--semantic-symbol->name-assoc-list then the symbol with this bucket-name as name is also a valid symbol for this list. Example: In ECB there are buckets "[Parents]". The bucket-name is "Parents" and the valid symbol-name is then Parents.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: methods-separate-prototypes

Separate function-prototypes from the real functions. This is for example useful for C++ and C because these languages distinct between a method-prototype (rsp. function-prototype for C) and the method (rsp. function for C) itself. If this option is not nil then ECB separates the prototypes from the real function/methods. Then with ecb-show-tags the user can define different display-settings for each of them. If this option is nil then the prototypes and the real functions are filled in the same bucket and displayed plain and there is no sorting between prototypes and functions possible. If this option is switched on then it is senseful that ecb-show-tags contains for all modes which distinct between prototypes and real functions/methods two entries for the tag-type 'function - see the documentation of this option.

User Option: post-process-semantic-taglist

Define mode-dependent post-processing for the semantic-taglist. This is an alist where the car is a major-mode symbol and the cdr is a list of function-symbols of functions which should be used for post-processing the taglist (returned by ecb--semantic-bovinate-toplevel) for a buffer in this major-mode. The first function in the list is called with current semantic taglist of current buffer and must return a valid taglist again. All other functions are called with the result-taglist of its preceding function and have to return a new taglist again.

For oo-programming languages where the methods of a class can be defined outside the class-definition (e.g. C++, Eieio) the function ecb-group-function-tags-with-parents can be used to get a much better method-display in the methods-window of ECB, because all method implementations of a class are grouped together.

Another senseful usage is to filter out certain tags, e.g. prototype tags in c-mode. For this you can set ecb-filter-c-prototyp-tags.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: show-only-positioned-tags

Show only nodes in the method-buffer which are "jump-able". If not nil then ECB displays in the method-buffer only nodes which are "jump-able", i.e. after selecting it by clicking or with RET then ECB jumps to the corresponding location in the edit-window. Example: With CLOS or Eieio source-code there can exist some position-less nodes like variable-attributes in a defclass form which are only displayed if this option is nil. Displaying such nodes can be senseful even if they can not be jumped.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: show-tags

How to show tags in the methods buffer first time after find-file. This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

The car is either a major-mode symbol or the special symbol 'default which means if no setting for a certain major-mode is defined then the cdr of the 'default cons-cell is used. This option should always contain a default-setting!

The cdr is a list where each element represents a type of tags:

(<tag type> <display type> <sort method>)

There can be more than 1 element for a certain <tag type>. This is for example useful for C++ and C because these languages distinct between a method-prototype (rsp. function-prototype for C) and the method (rsp. function for C) itself. The default value of these option contains two entries for <tag type> is function whereas the first one is responsible for the "real" methods (rsp. functions) and the second one for the prototypes. So if the methods should be flattened and the prototypes collapsed the show-tags-list for C++ and C must contain two entries for <tag type> function, the first one defined as flattened and the second one defined as collapsed.

The tags in the methods buffer are displayed in the order as they appear in this list.

<tag type>

A Semantic tag type symbol (function, variable, rule, include etc.) or one of the following:

• t: All tag types not specified anywhere else in the list.
• parent: The parents of a type.

<display type>

A symbol which describes how the tags of this type shall be shown:

• expanded: The tags are shown in an expanded node.
• collapsed: The tags are shown in a collapsed node.
• flattened: The tags are added to the parent node.
• hidden: The tags are not shown.

<sort method>

A symbol describing how to sort the tags of this type:

• name: Sort by the tag name.
• access: Sort by tag access (public, protected, private) and then by name.
• nil: Don't sort tags. They appear in the same order as in the source buffer.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: tag-display-function

Function to use for displaying tags in the methods buffer. This functionality is set on major-mode base, i.e. for every major-mode a different function can be used. The value of this option is a list of cons-cells:

• The car is either a major-mode symbol or the special symbol 'default which means if no function for a certain major-mode is defined then the cdr of the 'default cons-cell is used.
• The cdr is the function used for displaying a tag in the related major-mode.

Every function is called with 3 arguments:

1. The tag
2. The parent-tag of tag (can be nil)
3. The value of ecb-font-lock-tags.

Every function must return the display of the tag as string, colorized if the third argument is not nil.

The following functions are predefined:

• For each element E of ecb--semantic-format-function-alist exists a function with name "ecb--<(cdr E)>". These functions are just aliase to the builtin format-functions of semantic. See the docstring of these functions to see what they do. Example: (semantic-name-nonterminal . semantic-format-tag-name) is an element of ecb--semantic-format-function-alist. Therefore the alias-function for this element is named ecb--semantic-format-tag-name.
• For every cdr in ecb--semantic-format-function-alist with name "semantic-XYZ" a function with name "ecb-XYC" is predefined. The differences between the semantic- and the ECB-version are:
  • The ECB-version displays for type tags only the type-name and nothing else (exception: In c++-mode a template specifier is appended to the type-name if a template instead a normal class).
  • The ECB-version displays type-tags according to the setting in ecb-type-tag-display. This is useful for better recognizing different classes, structs etc. in the ECB-method window.

  For all tags which are not types the display of the ECB-version is identical to the semantic version. Example: For ecb--semantic-format-tag-name (one of the builtin semantic formatters) the pendant is ecb-format-tag-name.

This functionality also allows the user to display tags as UML. To enable this functionality set the function for a major-mode \(e.g. jde-mode) to ecb--semantic-format-tag-uml-concise-prototype, ecb--semantic-format-tag-uml-prototype, or ecb--semantic-format-tag-uml-abbreviate the ECB-versions of these functions.

If the value is nil, i.e. neither a function for a major-mode is defined nor the special 'default, then ecb--semantic-format-tag-prototype is used for displaying the tags.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: tag-jump-sets-mark

Set the mark after jumping to a tag from the ECB-method buffer. If set the user can easily jump back.

User Option: tag-visit-post-actions

Actions to perform after visiting a tag from the Method-buffer. With this option actions can be added which will be performed after visiting the start of the tag in the source-buffer.

This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

• The car is either a major-mode symbol or the special symbol 'default.

• The cdr is a list of action-functions or nil.

ECB first performs all actions defined for the special symbol 'default (if any) and then all actions defined for current major-mode (if any).

ECB offers some predefined senseful action-functions. Currently there are: ecb-tag-visit-highlight-tag-header ecb-tag-visit-smart-tag-start ecb-tag-visit-recenter ecb-tag-visit-recenter-top ecb-tag-visit-goto-doc-start ecb-tag-visit-narrow-tag See the documentation of these function for details what they do.

But you can add any arbitrary function if the following conditions are fulfilled: The function gets the semantic tag as argument, returns the (new) point after finishing its job and the function must not put the point outside the tag-boundaries of the tag-argument.

User Option: type-tag-display

How to display semantic type-tags in the methods buffer. Normally all tag displaying, colorizing and facing is done by semantic according to the value returned by ecb--semantic-format-face-alist and the semantic display-function (e.g. one from ecb--semantic-format-tag-functions). But sometimes a finer distinction in displaying the different type specifiers of type-tags can be useful. For a description when this option is evaluated look at ecb-tag-display-function!

This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

• The car is either a major-mode symbol or the special symbol 'default which means if no setting for a certain major-mode is defined then the cdr of the 'default cons-cell is used.

• The cdr is a list of 3-element-lists:
  1. First entry is a semantic type specifier in string-form. Current available type specifiers are for example "class", "interface", "struct", "typedef" and "enum". In addition to these ones there is also a special ECB type specifier "group" which is related to grouping tags (see ecb-post-process-semantic-taglist and ecb-group-function-tags-with-parents). Any arbitrary specifier can be set here but if it is not "group" or not known by semantic it will be useless.
  2. Second entry is a flag which indicates if the type-specifier string from (1.) itself should be removed (if there is any) from the display.
  3. Third entry is the face which is used in the ECB-method window to display type-tags with this specifier. ECB has some predefined faces for this (ecb-type-tag-class-face, ecb-type-tag-interface-face, ecb-type-tag-struct-face, ecb-type-tag-typedef-face, ecb-type-tag-union-face, ecb-type-tag-enum-face and ecb-type-tag-group-face) but any arbitrary face can be set here. This face is merged with the faces semantic already uses to display a tag, i.e. the result is a display where all face-attributes of the ECB-face take effect plus all face-attributes of the semantic-faces which are not set in the ECB-face (with XEmacs this merge doesn't work so here the ECB-face replaces the semantic-faces; this may be fixed in future versions).

The default value is nil means there is no special ECB-displaying of type-tags in addition to the displaying and colorizing semantic does. But a value like the following could be a useful setting:

((default ("class" t ecb-type-tag-class-face) ("group" nil ecb-type-tag-group-face)) (c-mode ("struct" nil ecb-type-tag-struct-face) ("typedef" nil ecb-type-tag-typedef-face)))

This means that in c-mode only "struct"s and "typedef"s are displayed with special faces (the specifiers itself are not removed) and in all other modes "class"s and grouping-tags (see ecb-tag-display-function, ecb-group-function-tags-with-parents) have special faces and the "class" specifier-string is removed from the display.

This options takes only effect for semantic-sources - means sources supported by semantic!

User Option: type-tag-expansion

Default expansion of semantic type-tags. Semantic groups type-tags in different type-specifiers. Current available type specifiers are for example "class", "interface", "struct", "typedef", "union" and "enum". In addition to these ones there is also a special ECB type-specifier "group" which is related to grouping tags (see ecb-post-process-semantic-taglist).

This option defines which type-specifiers should be expanded at file-open-time. Any arbitrary specifier can be set here but if it is not "group" or not known by semantic it will be useless.

This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

• The car is either a major-mode symbol or the special symbol default which means if no setting for a certain major-mode is defined then the cdr of the default cons-cell is used.

• The cdr is either a list of type-specifiers which should be expanded at file-open-time or the symbol all-specifiers (then a type-tag is always expanded regardless of its type-specifier).

This options takes only effect for semantic-sources - means sources supported by semantic!

5.3.6 Group ecb-history

This group contains settings for the history-buffer in the ECB:

User Option: history-buffer-after-create-hook

Local hook running after the creation of the history-buffer. Every function of this hook is called once without arguments direct after creating the history-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 only for the history-buffer of ECB.

User Option: history-buffer-name

Name of the ECB history buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. "*ECB History*".

If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-history-buffer by this name, e.g. by a call of set-buffer.

Changes for this option at runtime will take affect only after deactivating and then activating ECB again!

User Option: history-exclude-file-regexps

List of regexps which exclude source-files from being historized. Be aware that each always full filenames (ie. incl. full path) are matched against these regexps! Therefore be carefore with regexps beginning with ^!

User Option: history-item-name

The name to use for items in the history buffer.

User Option: history-menu-sorter

Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to sort the menu-entries of the combined menu-entries of the user-menu-extensions of ecb-history-menu-user-extension and the built-in-menu ecb-history-menu. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries.

For the guidelines for such a sorter-function see ecb-directories-menu-sorter.

User Option: history-menu-user-extension

Static user extensions for the popup-menu of the history buffer. For further explanations see ecb-directories-menu-user-extension.

The node-argument of a menu-function contains as data the filename of the source for which the popup-menu has been opened.

Per default the static user-extensions are added at the beginning of the built-in menu-entries of ecb-history-menu but the whole menu can be re-arranged with ecb-history-menu-sorter.

User Option: history-menu-user-extension-function

Dynamic user extensions for the popup-menu of the history buffer. A function which has to return a list in the same format like the option ecb-history-menu-user-extension. This function is called when the user opens the popup-menu for the history buffer.

Per default the dynamic user-extensions are added in front of the static extensions of ecb-history-menu-user-extension but the whole menu can be re-arranged with ecb-history-menu-sorter.

User Option: history-sort-ignore-case

Ignore case for sorting the history-entries. See also ecb-history-sort-method.

User Option: history-sort-method

Defines how the entries in the history-buffer are sorted.

• name: Sorting by name (default).
• extension: Sorting first by extension and then by name.
• nil: No sorting, means the most recently used buffers are on the top of the history and the seldom used buffers at the bottom.

See also ecb-history-sort-ignore-case.

User Option: kill-buffer-clears-history

Define if kill-buffer should also clear the history. There are three options:

• auto: Removes automatically the corresponding history-entry after the buffer has been killed.
• ask: Asks, if the history-entry should be removed after the kill.
• nil: kill-buffer does not affect the history (this is the default).

5.3.7 Group ecb-layout

This group contains settings for the screen-layout of the ECB:

User Option: activate-before-new-frame-created-hook

Normal hook run before the new ECB-frame is created if ecb-new-ecb-frame is not nil (otherwise this hook is not evaluated).

User Option: advice-window-functions

Advice functions to be more intelligent if used with ECB. You can choose the following functions to be adviced by ECB so they behave as if the edit-window(s) of ECB would be the only windows(s) of the ECB-frame:

• other-window For this one see also the option ecb-other-window-behavior!
• delete-window
• delete-other-windows
• delete-windows-on
• split-window-horizontally
• split-window-vertically
• split-window If this advice is enabled then split-window-vertically and split-window-horizontally are autom. enabled too!
• switch-to-buffer
• switch-to-buffer-other-window
• display-buffer Especially if ecb-compile-window-height is not nil it is strongly recommended not to disable this advice!
• other-window-for-scrolling If this advice is enabled then the behavior of the following functions depends on ecb-other-window-behavior:
  • scroll-other-window
  • scroll-other-window-down
  • beginning-of-buffer-other-window
  • end-of-buffer-other-window
• balance-windows: Only the edit-windows are balanced

For working most conveniently with ECB it is the best to advice all these functions, because then all the standard shortcuts of these functions are also usable with ECB without doing anything else. Also other packages can interact best with ECB if these functions are all adviced. If these adviced functions are called in another frame than the ECB-frame they behave all exactly like the not adviced versions!

But please read also the following:

Normally all packages should work correct with ECB and it´s adviced functions but if there occur problems with a package cause of some of these adviced functions ECB offers the following fall-back solution:

1. Deactivate in ecb-advice-window-functions all the adviced-functions which make problems with other packages.
2. For every of the advice-able functions <adv-func> ECB offers a interactively function named "ecb-<adv-func>" which does exactly the same as the adviced version of <adv-func>. Use "ecb-<adv-func>" instead the original one to get the proper ECB behavior even if the function is not adviced anymore.
3. You can bind in ecb-activate-hook the standard-shortcut of <adv-func> to "ecb-<adv-func>" and rebind it in