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



Group ecb-general

This group contains the following options:

activate-before-layout-draw-hook User Option
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

activate-hook User Option
Normal hook run at the end of activating the ecb-package by running 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.

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

auto-compatibility-check User Option
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 Auto. option-upgrading.

before-activate-hook User Option
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.

before-deactivate-hook User Option
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.

common-tree-buffer-after-create-hook User Option
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 keymap. 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

current-buffer-sync-hook User Option
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 strongle 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!

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

debug-mode User Option
If not nil ECB displays debug-information in the Messages-buffer. This is done for some critical situations concerning semantic-tokens 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!

key-map User Option
Specifies all keybindings for the ECB minor-mode keymap. 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 keybinding has the following form:
'(<common-prefix-flag> <keysequence> <function>) where
<common-prefix-flag>
If t then the common-prefixkey defined as car of the value (see above) is used.
<keysequence>
If the common prefixkey is used then the final keybinding is the concatenation of the common-prefixkey (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-prefixkey!

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.

major-modes-activate User Option
List of major-modes for which ECB shoulb be activated or shown. Do not mistake this option with ecb-auto-activate. The latter one is for activating ECB after Emacs-startup (even without opening a buffer) and this one is for defining for which major-modes ECB should be activated if the mode goes active!

The behaviour is like follows: If a mode is contained in this option ECB is activated after activating this mode (if ECB was deactivated before) or the ECB-windows are shown if ECB was already active but its windows were hidden. In every case ECB is activated with visible ECB-windows afterwards!

For every major mode there can be specified an ecb-layout-name:

  • default: The value customized with ecb-layout-name is choosen.
  • a string: ECB is activated with this layout-name. This changes the value of ecb-layout-name but only for current emacs-session! But the layout is only changed if ECB was activated, if just the ECB-windows were shown, the current layout is used!

There are two additional options:

  • none: No major-modes should activate ECB automatically.
  • a regexp: This means all major-modes which are not listed in ecb-major-modes-deactivate activate ECB except the symbol-name of major-mode matches this regexp. If this option is set then the default regexp excludes all Info- and customize-buffers because this buffers should not change anything in the ECB-activation state.

Any auto. activation is only done if the current-frame is unsplitted to avoid changing unnecessarily or unintentionally the frame-layout if the user just jumps between different windows.

major-modes-deactivate User Option
List of major-modes for which ECB should be deactivated or hidden. Specify if ECB should be deactivated or at least hidden if a major-mode is active. For each major-mode there must be added an action what should be done:
  • hide: ECB just hides all the ECB windows like with ecb-hide-ecb-windows.
  • deactivate: ECB is completely deactivated after activating the major-mode.

There are two additional options:

  • none: No major-modes should deactivate/hide ECB automatically.
  • A cons for the meaning "All except the activated modes of ecb-major-modes-activate". The car of this cons can be:
    • hide-all-except-activated: All major-modes which are not listed in ecb-major-modes-activate hide the ECB-windows.
    • deactivate-all-except-activated: All major-modes which are not listed in ecb-major-modes-activate deactivate ECB.

    The cdr of this cons is a regexp: This means all major-modes which are not listed in ecb-major-modes-activate deactivate/hide ECB except the symbol-name of major-mode matches this regexp. If this option is set then the default regexp excludes all Info- and customize-buffers because this buffers should not change anything in the ECB-activation state.

If a major-mode is listed in ecb-major-modes-activate as well as in ecb-major-modes-deactivate then ECB is activated!

Any auto. deactivation/hiding is only done if the edit-window of ECB is unsplitted and point is in the edit-window to avoid changing unnecessarily or unintentionally the frame-layout if the user just jumps between different edit-windows, the tree-windows and the compile-window of ECB.

There is one exception from this rule: If the edit-window is splitted and one window contains a dired-buffer and a "ECB-deactivating"-file is openend via dired then opening this file deactivates ECB (resp. hides the ECB-windows).

minor-mode-text User Option
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.)

mode-line-prefixes User Option
Prefixes shown in the modelines of the ECB buffers. The displayed prefix then looks like: "[ <PREFIX>[: ]]", means if a prefix is defined for an 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) then also the string ": " is appended.

primary-mouse-jump-destination User Option
Jump-destination of a primary mouse-button click (see ecb-primary-secondary-mouse-buttons) in an ECB-window, if you click onto a source or method or variable. Defines in which edit-window (if splitted) ECB does the "right" action (opening the source, jumping to a method/variable). 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.

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

Note: A click with the secondary mouse-button (see again ecb-primary-secondary-mouse-buttons does the "right" action always in the "other" window related to the setting in this option.

primary-secondary-mouse-buttons User Option
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-primary-mouse-jump-destination.
  • ECB Methods: Jumping to the method in that edit-window specified by the option ecb-primary-mouse-jump-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-token-jump-narrow).

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 the other window (see the documentation ecb-primary-mouse-jump-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

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

show-node-info-in-minibuffer User Option
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 shortend 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!

temp-dir User Option
Specify a directory where ECB can store temporary files.

tip-of-the-day User Option
Show tip of the day at start time of ECB.

tip-of-the-day-file User Option
File where tip-of-the-day cursor is stored.

tree-RET-selects-edit-window User Option
In which tree-buffers RET should finally select an edit-window. If a name of an ECB tree-buffer is contained in this list then hitting RET in this 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 ecb-show-sources-in-directories-buffer is not nil (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!

tree-easy-hor-scroll User Option
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 resp. right with scroll-step S. Additionally C-M-mouse-1 and C-M-mouse-3 are bound to scrolling left resp. 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.

tree-expand-symbol-before User Option
Show the expand symbol before the items in a tree.

tree-incremental-search User Option
Enable incremental search in the ECB-tree-buffers. For a detailed explanation see Using the keyboard. If you change this during ECB is activated you must deactivate and activate ECB again to take effect.

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

tree-navigation-by-arrow User Option
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!

truncate-lines User Option
Truncate lines in ECB buffers. If you change this during ECB is activated you must deactivate and activate ECB again to take effect.

truncate-long-names User Option
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.

use-recursive-edit User Option
Tell ECB to use a recursive edit so that it can easily be deactivated by (keyboard-escape-quit).

version-check User Option
If not nil ECB checks at start-time if the required versions of semantic and eieio are installed and loaded into Emacs. It is strongly recommended to set this option to not nil!

window-sync User Option
Synchronize the ECB-windows automatically with current edit window. The real synchronization is done by ecb-current-buffer-sync. If always then the synchronization by ecb-current-buffer-sync 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 by ecb-current-buffer-sync takes only place if the current-buffer in the edit-window has a relation to files or directories. Examples for the former one are all programming-language-modes, Info-mode too, an example for the latter one is dired-mode. For all major-modes related to non-file/directory-buffers like help-mode, customize-mode and others never an autom. synchronization will be done!

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

IMPORTANT NOTE: The synchronization is done by ecb-current-buffer-sync and therefore the hook ecb-current-buffer-sync-hook is evaluated every time ecb-current-buffer-sync is called (see above and documentation of ecb-current-buffer-sync)!

window-sync-delay User Option
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.