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 ecb-deactivate-hook to <adv-func>.
4. Now you have the best of both worlds: The problematic package works and you have the ECB-behavior of <adv-func> as if it would be adviced.

Here is an example: Suppose you must deactivating the advice for switch-to-buffer-other-window. Then you deactivate this function with this option and you can use ecb-switch-to-buffer-other-window instead. Bind the shortcut you normally use for switch-to-buffer-other-window to ecb-switch-to-buffer-other-window (use ecb-activate-hook for this) and rebind it to the original function in the ecb-deactivate-hook.

User Option: advice-window-functions-signal-error

Signal an error if an adviced function can not do its job. If not nil then an error is signaled if one of the adviced functions (see ecb-advice-window-functions) can not do its job. So for example if the user tries to split the compile-window or an ecb-tree-window or if one tries to switch to another buffer in one of the ecb-tree-windows. For details see the documentation of each of the adviced functions to get info when an error is signaled.

If this option is nil then no error is signaled but the called adviced function does simply nothing.

Default is nil but it can also be useful to signal errors - so you see when call a function in a situation which is not supported by this function.

User Option: fix-window-size

Fix size of the ECB-windows/buffers even after frame-resizing. The fix type (valid values are nil, t, width and height) can either be set on a layout-basis (means a different value for each layout) or one value can be set for all layouts.

For a detailed description of the valid values see description of window-size-fixed which is newly introduced in GNU Emacs 21 and is only available there. Therefore this option takes only effect with GNU Emacs 21.

Note1: Manually resizing the ECB-windows via enlarge-window, shrink-window, mouse-drag-vertical-line and mouse-drag-mode-line is still possible even if the window-sizes are fixed for frame-resizing!

Note2: The description of window-size-fixed in the Elisp-info-manual is more detailed than the description offered by C-h v!

Note3: With current Emacs 21.2.X there seems to be no distinction between width, height and t. Therefore this option takes no effect (means all ecb-windows have always unfixed sizes) if ecb-compile-window-height is not nil.

Per default no window-size fixing has been done.

User Option: hide-ecb-windows-after-hook

Hooks run direct after the ECB windows have been hidden. Hiding was done either by ecb-toggle-ecb-windows or ecb-hide-ecb-windows.

IMPORTANT: Hiding the ECB-windows is internally done by calling ecb-redraw-layout and therefore also the hooks ecb-redraw-layout-before-hook and ecb-redraw-layout-after-hook are evaluated. The hook-sequence is analogous to that described in ecb-show-ecb-windows-after-hook.

User Option: hide-ecb-windows-before-hook

Hook run direct before the ECB windows will be hidden. Hiding is done either by ecb-toggle-ecb-windows or ecb-hide-ecb-windows. This means that at runtime of this hook all the ECB-tree-windows of current layout are visible.

IMPORTANT: Hiding the ECB-windows is internally done by calling ecb-redraw-layout and therefore also the hooks ecb-redraw-layout-before-hook and ecb-redraw-layout-after-hook are evaluated. The hook-sequence is analogous to that described in ecb-show-ecb-windows-before-hook.

User Option: ignore-display-buffer-function

Adviced display-buffer ignores display-buffer-function. This means, that the adviced version of display-buffer (see ecb-advice-window-functions) ignores the value of display-buffer-function when called for the ecb-frame. If this variable should not be ignored then the function of display-buffer-function is completely responsible which window is used for the buffer to display - no smart ECB-logic will help to deal best with the ECB-window-layout! You can define if and when display-buffer-function should be ignored:

• only when durable compile window is used - i.e. if ecb-compile-window-height is not nil

• always when ECB is active - that means ignore when ECB is active otherwise not - this is the default value

• never, the adviced version of display-buffer always uses the value of display-buffer-function if the value is a function.

User Option: ignore-special-display

Ignore special-display-handling. This means, that all values of special-display-function, special-display-buffer-names and special-display-regexps are ignored

• only when durable compile window is used - i.e. if ecb-compile-window-height is not nil - this is the default value.

• always when ECB is active - that means no special-display-handling of buffers when ECB is active

• never, i.e. special-dislay-handling depends on the values of the options special-display-function, special-display-buffer-names and special-display-regexps.

User Option: layout-always-operate-in-edit-window

Adviced window functions work always in the edit-window. If we are in an ECB special buffer (methods, directories, etc), and any of the adviced windowing functions is called interactively (see ecb-advice-window-functions), we will select first an edit-window according to the value of ecb-mouse-click-destination. This is useful if you have any functions that use such functions and you don't want them to fail with an error complaining that the current buffer can not be split, or something similar.

Because this may not be desirable in all situations and for all adviced functions this can be enabled separately for every advicable function (see also ecb-advice-window-functions). If the symbol of an adviced function is contained in the value of this option, then a edit-window is first selected otherwise either an error is reported or some other special reaction (depends on ecb-advice-window-functions-signal-error); see the documentation of the adviced functions for this.

For other-window, other-window-for-scrolling and switch-to-buffer-other-window this makes no sense, therefore you can not enable this for them.

Per default this is enabled for switch-to-buffer and display-buffer.

User Option: layout-debug-mode

Write debug-information about layout-operations in the Messages-buffer. Normally there should be no need to set this option to true but if there are problems to display buffers in the compile-window of ECB (e.g. buffers which should be displayed there aren't or the temporally enlarging-mechanism does not do what you think it should do etc...) then please do the following steps:

1. Set ecb-layout-debug-mode to not nil

2. Reproduce the wrong behavior exactly by repeating all the operations which lead to the problem.

3. Now send immediately a bug report with ecb-submit-problem-report.

4. Set ecb-layout-debug-mode back to nil if you do not want further debugging output in the *Messages* buffer

User Option: layout-name

Select a window layout of ECB. Value is any arbitrary string. There are four different types of layouts: left, right, top and left-right, which means the location of the ECB-tree-windows in the ECB-frame. Currently there are 20 predefined layouts; names see below. You can savely try out any of them by changing this value and saving it only for the current session. If you are sure which layout you want you can save it for future sessions. To get a picture of the layout for name <name> call `ecb-show-layout-help'. ecb-layout-function-9.

Currently available layouts:

• Left layouts: left1 left2 left3 left4 left5 left6 left7 left8 left9 left10 left11 left12 left13 left14 left15

• Right layouts: right1

• Top layouts: top1 top2

• Left-right layouts: leftright1 leftright2

Regardless of the settings you define here: If you have destroyed or changed the ECB-screen-layout by any action you can always go back to this layout with ecb-redraw-layout

User Option: layout-window-sizes

Specifies the sizes of the ECB windows for each layout. The easiest way (and also the strongly recommended way) to change this variable is to change the window sizes by dragging the window borders using the mouse and then store the window sizes by calling the command ecb-store-window-sizes. Next time the layout is redrawn the values stored in this option will be used.

If ecb-store-window-sizes is used then the windows sizes are stored per default as fractions of current frame-width and -height of the ecb-frame, so the stored values will "work" for other frame sizes too. But if you call ecb-store-window-sizes with a prefix-argument then the fixed values of current width and height are stored!

If this option is set "by hand" (i.e. not by ecb-store-window-sizes) then the following is important:

• It is recommended to use fractions of frame-width and -height!.
• The order of the sequence of the inserted window sizes must be the same as other-window (the not-adviced version!) would walk!

User Option: maximize-ecb-window-after-selection

If not nil maximize current tree-window after selection. When selecting another not-tree-window after such an automatic maximizing all tree-windows of current layout are displayed again. But a tree-window is not maximized if either a node has been selected via primary- oder secondarc mouse-button or the popup-menu of that tree-buffer has been opened.

User Option: new-ecb-frame

Create a new frame at activation time of ECB.

User Option: other-window-behavior

The behavior of ECB concerning getting an "other window". This has an effect if either other-window or other-window-for-scrolling is adviced by ECB, see ecb-advice-window-functions. The following settings are possible:

all:

ECB will cycle through all windows of the ECB-frame or scroll simply the next window in the ECB-frame, means it behaves like the original other-window rsp. the original other-window-for-scrolling.

only-edit:

ECB will only cycle through the edit-windows of ECB or only scroll another edit-window. If the selected window is not an edit-window then it behaves like with value all.

edit-and-compile:

Like only-edit plus the compile window if any. If the selected window is neither an edit-window nor the compile-window then it behaves like with value all.

smart:

With this setting ECB tries to choose the other-window-destination or the "other window" to scroll in a smart and intuitive way: If point is in one of the edit-windows and if the edit-area is splitted then always the "next" edit-window is choosen (whereas the next edit-window of the last edit-window is the first edit-window)- if the edit-area is unsplitted then the compile-window is used if there is one. In the context of an other-window-call the ARG of other-window will be taken into account.

If one of the special ecb-windows is selected then always the "next" ecb-window is choosen (whereas the next ecb-window of the last ecb-window is the first ecb-window). In the context of an other-window-call the ARG of other-window will be taken into account. If there is only one ecb-window then ECB considers also the edit-windows

If the compile-window is selected then always the last edit-window which had the point will be used unless other-window has been called with a prefix-argument unequal 1.

If there is an active minibuffer:

Regardless of the allowed values above ECB handles the situation of an active minibuffer during a call to other-window or scroll-other-window like follows:

If the minibuffer-window is selected then ECB always chooses the window minibuffer-scroll-window points to (when this variable is set, otherwise the compile-window or the last selected edit-window is choosen) when the called command is called to choose the 1. next window (always true for scrolling another window or true when other-window called without prefix-arg or with prefix-arg equal 1). Otherwise the window ARG steps away is choosen (in case of other-window).

If there is an active minibuffer but the minibuffer-window is not selected then other-window and scroll-other-window behave like the original version.

In addition to the allowed values above the value of this option can also be a function:

A function:

This function gets seven arguments:

1. A canonical list of all currently visible windows of the ecb-frame
2. A canonical list of all currently visible edit-windows
3. A canonical list of all currently visible ecb-windows
4. The window-object of the compile-window if there is any.
5. The minibuffer-window of the ECB-frame if there is an active minibuffer.
6. The result of the function ecb-where-is-point - see the documentation of this function for details.
7. An integer which indicates how many steps away from the current selected window the "other-window" is. Is nil when this function is called in another context then for other-window.

The function has to return a window-object which is then used as "other window" for the command other-window or for scrolling another window (e.g. with scroll-other-window). Such a function has to handle properly all situation for itself. ecb-get-other-window-smart is an example for such a function.

User Option: redraw-layout-after-hook

Hooks run direct before the ECB windows will be shown either by ecb-toggle-ecb-windows or ecb-show-ecb-windows. This means that at runtime of this hook the ECB-windows are already visible.

User Option: redraw-layout-before-hook

Hooks run direct before the ECB-layout will be redrawn by either ecb-redraw-layout.

User Option: redraw-layout-quickly

If non-nil, we will attempt to redraw the layout quickly. Please read also carefully the documentation of ecb-redraw-layout.

User Option: select-edit-window-on-redraw

Select the first edit window on ecb-redraw-layout.

User Option: show-ecb-windows-after-hook

Hooks run direct before the ECB windows will be shown either by ecb-toggle-ecb-windows or ecb-show-ecb-windows. This means that at runtime of this hook the ECB-windows are already visible.

IMPORTANT: Showing the hidden ECB-windows is internally done by calling ecb-redraw-layout and therefore also the hooks ecb-redraw-layout-before-hook and ecb-redraw-layout-after-hook are evaluated. So there is the following sequence of hooks during the process of showing the hidden ECB-windows:

1. ecb-show-ecb-windows-before-hook
2. ecb-redraw-layout-before-hook
3. <redrawing the layout to show the hidden ECB-windows>
4. ecb-redraw-layout-after-hook
5. ecb-show-ecb-windows-after-hook

So be aware which code you add to which hook!

User Option: show-ecb-windows-before-hook

Hooks run direct before the ECB windows will be shown either by ecb-toggle-ecb-windows or ecb-show-ecb-windows. This means that at runtime of this hook the ECB-windows are still hidden.

IMPORTANT: Showing the hidden ECB-windows is internally done by calling ecb-redraw-layout and therefore also the hooks ecb-redraw-layout-before-hook and ecb-redraw-layout-after-hook are evaluated. So there is the following sequence of hooks during the process of showing the hidden ECB-windows:

1. ecb-show-ecb-windows-before-hook
2. ecb-redraw-layout-before-hook
3. <redrawing the layout to show the hidden ECB-windows>
4. ecb-redraw-layout-after-hook
5. ecb-show-ecb-windows-after-hook

So be aware which code you add to which hook!

User Option: split-edit-window-after-start

Sets if and how the edit window should be splitted after ECB-start. But be aware: This option determines only if and how the edit-window should be splitted at start-time of ECB. There are five different values allowed for this option:

• nil: Do not split the edit-area of ECB after activation, i.e. there will be only one edit-window after starting ECB.

• horizontal: Split the edit-area in 2 edit-windows side by side.

• vertical: Split the edit-area in 2 edit-windows, one above the other.

• before-activation: Split the edit-area as before the ECB-start, i.e. the edit-area will have after start a window-layout as the whole frame had before the start of ECB.

• before-deactivation: Split the edit-area into a window-layout ECB had in its edit-area direct before the ECB-deactivation. This value preserves the full state between activations of ECB, i.e. the visibility of the ECB-windows, the visibility of a compile-window and also the full split-state of the edit-area. But this can only be done if important layout-options have not been changed in the meanwhile. These are the options ecb-layout-name, ecb-compile-window-height, ecb-compile-window-width, ecb-windows-width and ecb-windows-height.

Default value is before-deactivation.

Some remarks to the value before-activation: If this value has been set then ECB needs three permanent adivces even when ECB is deactivated: split-window, delete-window and delete-other-windows. But these advices do not change any behavior of these functions but only storing in an internal ECB-variable the facts that a window has been splitted or deleted. In addition to this these advices are 100% error-save, means the functionality of the original functions will be performed in every(!) case even if within the advice an error occurs (but normally there can no errors occur in these advices because they are very simple). Conclusion: If you want really all ECB-advices being disabled after deactivating ECB then you have to set this option to other values then before-activation. But setting this variable to this value is really completely save.

User Option: toggle-layout-sequence

Toggle sequence for layout toggling with ecb-toggle-layout. Every element of this list has to be a valid layout-name i.e. either one of the predefined layouts or one of the user-defined layouts.

You can add here as many layouts as you want but to use this option most effective you should not add more than 2 or 3 layouts so every layout can be accessed very fast by toggling with ecb-toggle-layout. It is also senseful to add layouts which have the same principal outline, i.e. all their tree-buffers are on the same side of the frame and the tree-buffer-"column" (or -"row") has identical size for the layouts.

Recommended values are for example:

• ("left10" "left15"), toggles between methods and directories/history
• ("left10" "left13"), toggles between methods and directories
• ("left10" "left14"), toggles between methods and history
• ("left10" "left13" "left14"), toggles between methods, history and directories

See also option ecb-show-sources-in-directories-buffer.

This option makes only sense if the value is a list with more than 1 element!

User Option: windows-height

The height of the ECB windows in lines for top-layouts. If the number is less than 1.0 the width is a fraction of the frame height.

User Option: windows-width

The width of the ECB windows in columns for left- and right layouts. If the number is less than 1.0 the width is a fraction of the frame width.

5.3.8 Group ecb-compilation

This group contains settings for the compile window of ECB:

User Option: compilation-buffer-names

Additional buffer names that should be displayed in the compile-window. Buffer names can either be defined as strings or as regexps. If the buffer-name of a buffer matches one of the defined string or regexp then it will be displayed in the compile-window of ECB even if compilation-buffer-p says nil for this buffer.

It is not recommended to add the eshell-buffer-names to this list because ECB already handles the eshell-integration as best as possible (see section 8.10 Optimal using of eshell in ECB).

See also the options ecb-compilation-major-modes and ecb-compilation-predicates.

User Option: compilation-major-modes

Additional major-mode that should be displayed in the compile-window. All buffers of a major-mode contained in this list are displayed in the compile-window even if compilation-buffer-p says nil for such a buffer.

It is not recommended to add eshell-mode to this list because ECB already handles the eshell-integration as best as possible (see section 8.10 Optimal using of eshell in ECB).

User Option: compilation-predicates

Predicates when a buffer should be treated as compilation-buffer. Every element of this list has to be a function or lambda-expression which gets as argument a buffer-object and which has to return not nil when this buffer should be treated as compilation-buffer (even if compilation-buffer-p says nil) and therefore be displayed in the compile-window of ECB (if there is any).

In combination with the values of ecb-compilation-buffer-names and ecb-compilation-major-modes ECB decides when a buffer is displayed in the compile-window.

Default value is the function comint-check-proc which returns not nil when the buffer is related to a living process.

User Option: compile-window-height

Height of the durable compilation-window of ECB. If you want a compilation window shown at the bottom of the ECB-layout then set here the height of it (Default is a height of 5). If you redraw the current layout with ecb-redraw-layout then the compilation window (if any) has the height you set here. If the number is less than 1.0 the height is a fraction of the frame height.

If you do not set a durable compilation window then doing a compilation or displaying temp-buffers (e.g. *Help*-buffers) splits temporally the edit window vertically if the edit window is not splitted already or uses another edit window temporally for compilation output if the edit window is already splitted. This is the recommended value for this option because this is the standard-behavior of Emacs.

Beware: If you set a durable compilation window then ECB displays all buffers for which ecb-compilation-buffer-p returns not nil in that durable compilation window. If a buffer which should being displayed there is not displayed there then try to modify the options ecb-compilation-buffer-names, ecb-compilation-major-modes or ecb-compilation-predicates (in this sequence).

See also the options ecb-compile-window-temporally-enlarge and ecb-enlarged-compilation-window-max-height and also the command ecb-toggle-compile-window-height!

ECB offers the functionality of such a durable compile-window regardless if the special ECB-windows are visible or not (see the command ecb-toggle-ecb-windows).

Regardless of the settings you define here: If you have destroyed or changed the ECB-screen-layout by any action you can always go back to this layout with ecb-redraw-layout

User Option: compile-window-prevent-shrink-below-height

Allow the compile-window to be shrunken below its height. A non nil value means ECB prevents the compile-window from being shrunken below the threshold of ecb-compile-window-height by displaying temp-buffers (e.g. *Help* etc.) or after running compilations or greps. But interactively it is always allowed to shrink it to every height!

If nil then ECB does nothing to prevent being shrunken below the value of ecb-compile-window-height.

Default is t.

User Option: compile-window-temporally-enlarge

Let Emacs temporally enlarge the compile-window of the ECB-layout. This option has only an effect if ecb-compile-window-height is not nil!

The following values are possible:

• after-display: After displaying a "compilation-buffer" (in the sense of ecb-compilation-buffer-p!) in the compile-window of ECB. For the max. height of the enlarged compile-window see the option ecb-enlarged-compilation-window-max-height.

• after-selection: Selecting the ecb-compile-window auto. enlarges it and de-selecting (means leaving ecb-compile-window) auto. shrinks it. Enlarging and shrinking the ecb-compile-window is done with ecb-toggle-compile-window-height. See also the documentation of this function!

• both: The combination of 'after-display and 'after-selection.

• nil: ECB fixes always the height of the ecb-compile-window at the value of ecb-compile-window-height.

To restore the ECB-layout after such a buffer-enlarge just call ecb-toggle-compile-window-height or ecb-redraw-layout.

User Option: compile-window-width

Width of the compile-window.

Possible values are frame and edit-window. With frame the compile-window looks like:

------------------------------------------------------- | | | | Directories | | | | | |--------------| edit-window(s) | | | | | Methods | | | | | ------------------------------------------------------- | | | Compilation | | | -------------------------------------------------------

With edit-window the compile-window looks like:

------------------------------------------------------- | | | | Directories | | | | | |--------------| edit-window(s) | | | | | Methods | | | | | | |--------------------------------------- | | | | | Compilation | | | | -------------------------------------------------------

This option takes only effect if ecb-compile-window-height is not nil!

User Option: change-layout-preserves-compwin-state

Changing the layout preserves the state of the compile-window. This is for example useful if the user toggles between several layouts (see ecb-toggle-layout) and wants to preserve the hidden-state of the compile-window.

User Option: enlarged-compilation-window-max-height

The max height of the compile-window after enlarging it. The max height of the compilation window after enlarged by ecb-toggle-compile-window-height. The following values are allowed:

best:

ECB fits the height of the compile-window exactly to the size of its current contents but never shrinks below the value of ecb-compile-window-height or enlarges over the half of the frame-height of the ECB-frame. The values of the options compilation-window-height and temp-buffer-max-height are taken into account dependent of the current major-mode of the buffer in the compile-window: If compilation-mode then compilation-window-height is used otherwise temp-buffer-max-height.

half:

1/2 the frame-height of the ECB-frame

Any number:

Max height in lines. If the number is less than 1.0 the height is a fraction of the frame height (e.g. 0.33 results in a max-height of 1/3 the frame-height).

User Option: scroll-other-window-scrolls-compile-window

scroll-other-window scrolls always the compile-window. For all details about the scroll-behavior of scroll-other-window see the advice documentation of other-window-for-scrolling.

5.3.9 Group ecb-create-layout

This group contains settings for creating new ECB-layouts:

User Option: create-layout-file

File where all layouts created by ecb-create-new-layout are stored.

User Option: ecb-create-layout-frame-height

Frame height of the layout creation frame.

User Option: ecb-create-layout-frame-width

Frame width of the layout creation frame.

5.3.10 Group ecb-face-options

This group contains settings for all faces used in ECB:

User Option: directories-general-face

Basic face for the ECB directories buffer. This defines the basic face the whole directory buffer should displayed with. If the face ecb-default-general-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-general-face.

Changes take first effect after finishing and reactivating ECB!

User Option: directory-face

Face used for highlighting current directory in the directories buffer. If the face ecb-default-highlight-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-highlight-face.

Changes take first effect after finishing and reactivating ECB!

User Option: directory-not-accessible-face

Face for not accessible dirs in the directories buffer.

User Option: history-face

Face used for highlighting current history-entry in the history buffer. If the face ecb-default-highlight-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-highlight-face.

Changes take first effect after finishing and reactivating ECB!

User Option: history-general-face

Basic face for the ECB directory buffer. This defines the basic face the whole history buffer should displayed with. If the face ecb-default-general-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-general-face.

Changes take first effect after finishing and reactivating ECB!

User Option: method-face

Face used for highlighting current method, class or variable in the methods buffer. If the face ecb-default-highlight-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-highlight-face.

Changes take first effect after finishing and reactivating ECB!

User Option: method-non-semantic-face

Face used for for displaying tags of sources not supported by semantic.

Changes take first effect after finishing and reactivating ECB!

User Option: methods-general-face

Basic face for the ECB methods buffer. This defines the basic face the whole methods buffer should displayed with. If the face ecb-default-general-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-general-face.

Changes take first effect after finishing and reactivating ECB!

User Option: source-face

Face used for highlighting current source in the sources buffer. If the face ecb-default-highlight-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-highlight-face.

Changes take first effect after finishing and reactivating ECB!

User Option: source-in-directories-buffer-face

Face for source files in the directories buffer.

User Option: sources-general-face

Basic face for the ECB sources buffer. This defines the basic face the whole sources buffer should displayed with. If the face ecb-default-general-face is used then the display of all ECB-tree-buffers can be changed by modifying only the face ecb-default-general-face.

Changes take first effect after finishing and reactivating ECB!

User Option: source-read-only-face

Face for read-only sources.

User Option: tag-header-face

Face used for highlighting the tag header after jumping to it by clicking onto a node in the methods buffer.

5.3.11 Group ecb-faces

This group contains all faces used in ECB:

ecb-bucket-node-face:

Face which can be used for displaying bucket tags in the methods buffer. See also ecb-bucket-node-display.

ecb-default-general-face:

Basic face for all ECB tree-buffers. It's recommended to define here the font-family, the font-size, the basic color etc.

In GNU Emacs 21.X all faces (even the face ecb-default-highlight-face) used in the ECB tree-buffers inherit from this face. Therefore the default attributes like font etc. of a face used in a tree-buffer can be very easily changed with face ecb-default-general-face.

With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the options ecb-directories-general-face, ecb-sources-general-face, ecb-methods-general-face and ecb-history-general-face offer the choice to use the face ecb-default-general-face so also with XEmacs and GNU Emacs 20.X the basic face-settings can be easily changed just by customizing the face ecb-default-general-face!

ecb-default-highlight-face:

Define basic face for highlighting the selected node in an ECB tree-buffer.

In GNU Emacs 21.X all highlighting faces in the ECB tree-buffers inherit from this face. Therefore the default attributes like font etc. of a face used in a tree-buffer for highlighting the current tag can be very easily changed with face ecb-default-highlight-face.

With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the options ecb-directory-face, ecb-source-face, ecb-method-face and ecb-history-face offer the choice to use the face ecb-default-highlight-face so also with XEmacs and GNU Emacs 20.X the basic face-settings can be easily changed just by customizing the face ecb-default-highlight-face!

ecb-directories-general-face:

Basic face for the ECB directories buffer. Itīs recommended to define here the font-family, the font-size, the basic color etc.

ecb-directory-face:

Define face used for highlighting current directory in the directories buffer.

ecb-directory-not-accessible-face

Define a face for not accessible dirs in the directories buffer.

ecb-history-face:

Define face used for highlighting current history-entry in the history buffer.

ecb-history-general-face:

Basic face for the ECB history buffer. Itīs recommended to define here the font-family, the font-size, the basic color etc.

ecb-method-face:

Define face used for highlighting current method, class or variable in the methods buffer.

ecb-methods-general-face:

Basic face for the ECB methods buffer. Itīs recommended to define here the font-family, the font-size, the basic color etc.

ecb-method-non-semantic-face:

Define face used for displaying tags of sources not supported by semantic.

ecb-mode-line-data-face

Define face for the data in the mode-line. See ecb-mode-line-data.

ecb-mode-line-prefix-face

Define face for the prefix in the mode-line. See ecb-mode-line-prefixes.

ecb-source-face:

Define face used for highlighting current source in the sources buffer.

ecb-source-in-directories-buffer-face:

Define a face for displaying sources in the directories buffer.

ecb-sources-general-face:

Basic face for the ECB sources buffer. Itīs recommended to define here the font-family, the font-size, the basic color etc.

ecb-source-read-only-face

Define a face for read-only sources

ecb-tag-header-face:

Define face used for highlighting the tag header after jumping to it by clicking onto a node in the methods buffer.

ecb-tree-guide-line-face:

Define face for the guide-lines in the tree-buffers. See the option ecb-tree-buffer-style for a explanation of guide-lines.

ecb-type-tag-class-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-enum-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-group-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-interface-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-struct-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-typedef-face:

Define face used with option ecb-type-tag-display.

ecb-type-tag-union-face:

Define face used with option ecb-type-tag-display.

ecb-mode-line-win-nr-face

Define face for the window-number in the mode-line. See ecb-mode-line-display-window-number.

Just call customize-face <face-name> to customize these faces for your personal taste. Or customize the related option in the group 5.3.10 Group ecb-face-options.

5.3.12 Group ecb-download

This group contains settings for downloading and installing a new ECB from within ECB:

User Option: download-delete-archive

Should the downloaded archive be deleted after successful installation or after failure during the installation-process. Possible values are:

• only-after-success: Archive is only deleted after successful installation but not if a failure occurs during the installation process.
• always: Archive is also deleted if an error occurs.
• nil: Archive will never be deleted.

User Option: download-install-parent-dir

Parent directory where downloaded packages are installed.

ECB installs a downloaded package in this directory, i.e. the downloaded archive X.tar.gz will be extracted in this directory so afterwards this directory contains a new subdirectory X which contains the downloaded package.

This directory must be write-able!

User Option: download-package-version-type

Version type ECB is allowed to download for upgrading.

If you want to upgrade to a newer ECB-version via ecb-download-ecb or if you must upgrade to newer semantic- eieio- and/or speedbar-versions (because ECB requires these newer versions) then this option specifies which version-types are allowed. ECB checks on the download-sites of ECB/semantic/eieio/speedbar which versions are currently available and then downloads always the latest version matching the specified type:

• 2: Get the newest version of all stable versions available.
• 1: Get the newest version of all stable and beta versions available.
• 0: Get the newest version of all stable, beta and alpha versions available.
• -1: Ask before downloading in the minibuffer for a version (TAB-completion of all available versions is possible).

So, 2 means stable, 1 means stable and betas, 0 means stable, betas and alphas and -1 means ask the user for a version.

Per default stable and beta-versions are allowed (value 1).

But all versions must match the restrictions of the specified min- and max-versions of the required packages. For this see the file README!

User Option: download-url

URL where download-able ECB-versions are located. The ECB-archive-file (e.g. ecb-1.70.tar.gz) will be appended to this URL and ecb-download-ecb will try to download this archive.

Note: Normally this URL should never change but who knows...

5.3.13 Group ecb-help

This group contains settings for the ECB online help:

User Option: help-html-path

Path where the ECB online help in HTML format resides. This must be the location of the `ecb.html' which comes with the ECB distribution. If is installed by unpacking the archive available on the ECB website then this is the subdir ecb-help-html-subdir of the installation directory of ECB. If it is installed as XEmacs-package (e.g. via the package manager of XEmacs) then this is probably either the directory "../../html/" or "../../etc/ecb/html/" (both relative to the Elisp directory of ECB).

The path can either be an absolute path or a path relative to the directory where the Elisp files of ECB are.

Normally there should be no need to change this option!

User Option: help-info-path

Path where the ECB online help in info format resides. This must be the location of the `ecb.info' which comes with the ECB distribution. If is installed by unpacking the archive available on the ECB website then this is the subdir ecb-help-info-subdir of the installation directory of ECB. If it is installed as XEmacs-package (e.g. via the package manager of XEmacs) then this is probably the directory "../../info/" (relative to the Elisp directory of ECB).

The path can either be an absolute path or a path relative to the directory where the Elisp files of ECB are.

Normally there should be no need to change this option!

User Option: show-help-format

The format ecb-show-help shows its online help. Allowed values are 'info (for the Info format) and 'html (for HTML format). If the value is 'html then browse-url-browser-function says which browser is used.

Note: If you got ECB as a standard XEmacs-package maybe the HTML-online-documentation is not included.

5.3.14 Group ecb-eshell

This group contains settings for eshell integration within the ECB:

User Option: eshell-auto-activate

Startup the eshell and display it in the compile-window. If current layout does not display a compile-window (see ecb-compile-window-height) then nothing is done.

User Option: eshell-enlarge-when-eshell

Enlarge the compile-window if it is selected by eshell. This takes only effect if the command eshell is called!

User Option: eshell-fit-window-to-command-output

Fit the compile-window after an eshell-command to the output. This is done by the function ecb-eshell-fit-window-to-output which is added to eshell-post-command-hook ie. which is running autom. after each eshell-command.

User Option: eshell-synchronize

Synchronize eshell with the default-directory of current source-buffer. The synchronization is done by ecb-eshell-current-buffer-sync which can be called interactively but normally it is called autom. by the ecb-current-buffer-sync-hook.

5.3.15 Group ecb-speedbar

5.3.16 Group ecb-non-semantic

This group contains settings for parsing and displaying non-semantic files:

User Option: auto-save-before-etags-methods-rebuild

Automatic saving of current buffer before rebuilding its methods.

This option is only relevant for sources which are supported and parsed by etags (see ecb-process-non-semantic-files). Because etags is an external tool a source-buffer can only be reparsed if the buffer is saved to disk. So the command ecb-rebuild-methods-buffer checks for sources which are not supported by semantic or imenu if either this option is t or if the major-mode of the source-buffer is contained in this list: In both cases ECB saves the current source-buffer before it re-runs etags for reparsing the source. If nil or if the major-mode is not contained then no automatic saving will be done!

For all source supported by semantic or by imenu this option takes no effect.

User Option: non-semantic-exclude-modes

Exclude modes from parsing with imenu or etags. Per default, ECB tries to parse all file-types not supported by semantic with imenu or etags or some other method (for details see the option ecb-non-semantic-parsing-function). If a file-type can not be parsed by semantic, imenu or etags than this simply results in an empty method-buffer for this file. But nevertheless you will get a message "Sorry, no support for a file of that extension" which comes from the speedbar-library and can not switched off. Therefore if a major-mode is known as not parse-able by semantic, imenu or etags it can be added to this option and then it will be excluded from being tried to parsed.

User Option: non-semantic-methods-initial-expand

Initially expand all tags for not by semantic supported sources. This option can be customized on a major-mode basis, i.e. if a major-mode is contained in this option then all tags for this modes will be initially expanded - otherwise not.

User Option: non-semantic-parsing-function

Define mode-dependent parsing functions for non-semantic files. This is an alist where the car is a major-mode symbol and the cdr is a function-symbol of a function which should be used for parsing a non-semantic buffer, i.h. a buffer for which no semantic grammar exists. Such a function gets one argument - the filename of current buffer - and has to generate and return a tag/tag list which is understandable by speedbar-insert-generic-list. speedbar has already included two functions speedbar-fetch-dynamic-imenu and speedbar-fetch-dynamic-etags which can be used for parsing buffers with imenu rsp. etags.

This option takes only effect if ecb-process-non-semantic-files is not nil: Then ECB checks for non-semantic buffers if current major-mode is contained in this option and if yes, then the specified parsing function is called; if not then the cars of the elements of speedbar-dynamic-tags-function-list are called in that sequence they are listed in this variable. See option speedbar-dynamic-tags-function-list for further details.

In most cases imenu-parsing is preferable over etags-parsing because imenu operates on Emacs-buffers and needs no external tool and therefore parsing works also if current contents of a buffer are not saved to disk. But maybe sometimes etags may return better parsing results

IMPORTANT: if imenu-parsing should be used then the option speedbar-use-imenu-flag must be set to not nil!

User Option: process-non-semantic-files

Display content of non-semantic-files in the ECB-methods-buffer. See also ecb-non-semantic-parsing-function.

User Option: rebuild-non-semantic-methods-before-hook

Hook running at beginning of the function ecb-rebuild-methods-buffer-for-non-semantic. This function is always called by the command ecb-rebuild-methods-buffer for not semantic supported source-types.

Every function of this hook gets one argument: The complete filename of the current source-buffer in the edit-window. The Method-buffer is only rebuild by ecb-rebuild-methods-buffer-for-non-semantic if either the hook contains no function (the default) or if no function of this hook returns nil! See run-hook-with-args-until-failure for description how these function are processed.

5.3.17 Group ecb-winman

This group contains settings for supporting several window-managers:

User Option: winman-escreen-number

Number of the escreen which is reserved for ECB. If you go to the escreen with this number you go always to the escreen with activated ECB. All other escreen-numbers are escreens with deactivated ECB!

User Option: winman-winring-name

Name of the winring-window-configuration reserved for ECB. If you go to the window-configuration with this name you go always to the window-configuration with activated ECB. All other window-configuration are configurations with deactivated ECB!

5.3.18 Group ecb-mode-line

This group contains settings for the modelines of the ECB-tree-buffers:

User Option: mode-line-data

Data shown in the modelines of the special ECB-buffers. Everey element of this list is a cons-cell where the car is used to define a buffer-name and the cdr to define the modeline-data for that buffer. For details about how to defining a buffer-name see ecb-mode-line-prefixes - its completely the same.

The cdr is the data for ths modeline and can either be the symbol sel-dir or sel-source whereas the former one displays the current selected directory as modeline-data and the latter one the current selected source-file (without path).

In addition to these two predefined values for every special ECB-buffer a plain string (which is displayed) or a function can be specified which gets three args (name of the buffer, current selected directory and current selected source-file) and must return a string which will be displayed in the modeline (or nil if no data should be displayed). Such a function can add the text-property help-echo to the result-string. Then this help-string will be displayed when the user moves the mouse over this section of the modeline.

If a special ECB-buffer should not display special data in its modeline then this buffer-name should either not being added to this option or added with "No data" (= nil as cdr).

The whole modeline of the special ECB-buffer consists of the prefix of ecb-mode-line-prefixes and the data of ecb-mode-line-data - eventually prepended by the window-number, see ecb-mode-line-display-window-number.

User Option: mode-line-data-face

Face used for the data in the mode-line. See ecb-mode-line-data. For XEmacs the face should inherit from the face modeline (see set-face-parent)!

User Option: mode-line-display-window-number

Display in the modeline of every special ECB-window the window-number. The left-top-most window in a frame has the window-number 0 and all other windows are numbered with increasing numbers in the sequence, functions like other-window or next-window would walk through the frame.

This can be used to jump to windows by number with commands like:

(defun my-switch-to-window-number (number) ``Switch to the nth window'' (interactive ``P'') (if (integerp number) (select-window (nth number (window-list)))))

Currently this feature is only available for GNU Emacs 21.X, because neither GNU Emacs < 21 nor XEmacs can evaluate dynamically forms in the mode-line.

User Option: mode-line-prefixes

Prefixes shown in the modelines of the special ECB-buffers. The displayed prefix then looks like: "[ <PREFIX>[: ]]", means if a prefix is defined for an special ECB-buffer then a single space is prepended and if there is additional text to display (e.g. the current directory in the sources buffer, see ecb-mode-line-data) then also the string ": " is appended.

Everey element of this list is a cons-cell where the car is used to define a buffer-name and the cdr to define the modeline-prefix for that buffer.

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 define a prefix for one of the builtin ECB-tree-buffers because then simply the related option-symbol can be used. To add a prefix for the builtin directories tree-buffer just set the symbol ecb-directories-buffer-name as car.

The cdr is the prefix for a buffer and can either be a string which used as it is or a function-symbol which is called with three argument (the buffer-name, the current selected directory and the current selected source-file) and must return either nil (for no prefix) or a string which is then used a prefix. Such a function can add the text-property help-echo to the result-string. Then this help-string will be displayed when the user moves the mouse over this section of the modeline.

If a special ECB-buffer should not have a prefix in its modeline then this buffer-name should either not being added to this option or added with "No prefix" (= nil as cdr).

User Option: mode-line-prefix-face

Face used for the prefix in the mode-line. See ecb-mode-line-prefixes. For XEmacs the face should inherit from the face modeline (see set-face-parent)!

User Option: mode-line-win-nr-face

Face used for the window-number in the mode-line. See ecb-mode-line-display-window-number. For XEmacs the face should inherit from the face modeline (see set-face-parent)!

5.3.19 Group ecb-version-control

This group contains settings for the version-control-support of ECB:

User Option: vc-directory-exclude-regexps

Which directories should be excluded from VC-state-check. If a directory matches any of the regexps of this option the VC-state of its sources will not be checked - This option takes only effect if ecb-vc-enable-support is not nil.

User Option: vc-enable-support

Enable support for version-control (VC) systems. If on then in the directories-buffer (if the value of the option ecb-show-sources-in-directories-buffer is on for current layout), the sources-buffer and the history-buffer all file-items are displayed with an appropriate icon in front of the item-name to indicate the VC-state of this item. If off then no version-control-state checking is done.

Because this check can be take some time if files are managed by a not local Version-control-server 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 the option ecb-prescan-directories-for-emptyness for an explanation for these three choices.

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

See ecb-vc-supported-backends and ecb-vc-state-mapping how to customize the VC-support itself.

User Option: vc-state-mapping

Mapping between VC-states from the backends and ECB-known VC-states. ECB understands the following state-values:

up-to-date

The working file is unmodified with respect to the latest version on the current branch, and not locked.

edited

The working file has been edited by the user. If locking is used for the file, this state means that the current version is locked by the calling user.

needs-patch

The file has not been edited by the user, but there is a more recent version on the current branch stored in the master file.

needs-merge

The file has been edited by the user, and there is also a more recent version on the current branch stored in the master file. This state can only occur if locking is not used for the file.

added

The working file has already been added/registered to the VC-system but not yet commited.

unlocked-changes

The current version of the working file is not locked, but the working file has been changed with respect to that version. This state can only occur for files with locking; it represents an erroneous condition that should be resolved by the user.

ignored

The version-control-system ignores this file (e.g. because included in a .cvsignore-file in case of CVS).

unknown

The state of the file can not be retrieved; probably the file is not under a version-control-system.

All state-values a check-vc-state-function of ecb-vc-supported-backends can return must have a mapping to one of the ECB-state-values listed above. If for a certain backend-VC-state no mapping can be found then per default 'edited is assumed!

The default value of this option maps already the possible returned state-values of vc-state and vc-recompute-state (both GNU Emacs) and vc-cvs-status (Xemacs) to the ECB-VC-state-values.

User Option: vc-supported-backends

Define how to to identify the VC-backend and how to check the state. The value of this option is a list containing cons-cells where the car is a function which is called to identify the VC-backend for a DIRECTORY and the cdr is a function which is called to check the VC-state of the FILEs contained in DIRECTORY.

Identify-backend-function: It gets a full directory-name as argument - always without ending slash (rsp. backslash for native Windows-XEmacs) - and has to return a unique symbol for the VC-backend which manages that directory (e.g. 'CVS for the CVS-system or 'RCS for the RCS-system) or nil if the file is not managed by a version-control-system.

Check-vc-state-function: It gets a full filename (ie. incl. the complete directory-part) and has to return a symbol which indicates the VC-state of that file. The possible returned values of such a check-vc-state-function have to be mapped with ecb-vc-state-mapping to the allowed ECB-VC-state values.

ECB runs for a certain DIRECTORY all identify-backend-functions in that order they are listed in this option. For the first which returns a value unequal nil the associated check-state-function is used to retrieve the VC-state of all sourcefiles in that DIRECTORY.

There is no need for the identify-backend-function or the check-vc-state-function to cache any state because ECB automatically caches internally all necessary informations for directories and files for best possible performance.

To prepend ECB from checking the VC-state for any file set ecb-vc-enable-support to nil.

Default value for GNU Emacs: Support for CVS, RCS, SCCS and Subversion (for the later one the most recent version of the VC-package incl. the vc-svn library is needed) is added per default. To identify the VC-backend the functions ecb-vc-managed-by-CVS, ecb-vc-managed-by-RCS rsp. ecb-vc-managed-by-SCCS rsp. ecb-vc-managed-by-SVN are used. For all three backends the function ecb-vc-state of the VC-package is used.

Default value for XEmacs: XEmacs contains only a quite outdated VC-package, especially there is no backend-independent check-vc-state-function available (like vc-state for GNU Emacs). Only for CVS a check-vc-state-function is available: vc-cvs-status. Therefore ECB adds per default only support for CVS and uses ecb-vc-managed-by-CVS rsp. vc-cvs-status.

Example for GNU Emacs: If vc-recompute-state (to get real state-values not only heuristic ones) should be used to check the state for CVS-managed files and vc-state for all other backends then an element (ecb-vc-dir-managed-by-CVS . vc-recompute-state) should be added at the beginning of this option.

User Option: vc-xemacs-exclude-remote-cvs-repository

Exclude directories with a remote cvs-repository from VC-check. This option takes only effect for XEmacs and is needed cause of the outdated VC-package of XEmacs which offers no heuristic state-checking and also no option vc-cvs-stay-local. So this option takes only effect if vc-cvs-stay-local is not avaiable. In this case ECB treats directories which are managed by CVS but have a remote repository as if the directory would be not managed by CVS (so the files are not checked for their VC-state). This si done to avoid blocking XEmacs when running full cvs-commands (e.g. "cvs status") over the net.

Note: When ECB can find the option vc-cvs-stay-local then this option will automatically take no effect regardless which Emacs-version is used.