This is ecb.info, produced by makeinfo version 4.8 from ecb.texi.

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* ECB: (ecb).           Emacs Code Browser
END-INFO-DIR-ENTRY


File: ecb.info,  Node: ecb-tree-buffer,  Next: ecb-directories,  Prev: ecb-general,  Up: Customizable options

7.3.2 Group ecb-tree-buffer
---------------------------

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

 -- User Option: basic-buffer-sync
     Synchronize the basic ECB-buffers automatically with current edit buffer.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     The following keys must not be rebind in all tree-buffers:
        - `RET' and all combinations with `Shift' and `Ctrl'

        - `TAB'

        - `C-t'

 -- 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: 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-methods-show-node-info').

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

     The following combinations are possible:

        - 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: tree-buffer-style
     The style of the tree-buffers.  There are three different styles
     available:

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

     Ascii-style with guide-lines (value `ascii-guides'):
        [-] ECB
         |  [+] code-save
         `- [-] ecb-images
             |  [-] directories
             |   |  [-] height-15
             |   |   |  * close.xpm
             |   |   |  * empty.xpm
             |   |   |  * leaf.xpm
             |   |   `- * open.xpm
             |   |  [+] height-17
             |   |  [+] height-19
             |   `- [+] height-21
             |  [x] history
             |  [x] methods
             `- [x] sources

     Ascii-style without guide-lines (value `ascii-no-guides') - this is the
     style used by ECB <= 1.96:
        [-] ECB
            [+] code-save
            [-] ecb-images
                [-] directories
                    [-] height-15
                        * close.xpm
                        * empty.xpm
                        * leaf.xpm
                        * open.xpm
                    [+] height-17
                    [+] height-19
                    [+] height-21
                [x] history
                [x] methods
                [x] sources

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

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

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

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

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

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

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

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

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

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

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

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

     When located after then the tree looks like:

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

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

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

 -- User Option: tree-image-icons-directories
     Directories where the images for the tree-buffer can be found. This is a
     cons cell where:

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

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

     ECB comes with predefined images in several different heights - so for
     the most senseful font-heights of a tree-buffer a fitting image-size
     should be available. The images reside either in the subdirectory
     "ecb-images" of the ECB-installation or - if ECB is installed as regular
     XEmacs-package - in the ECB-etc data-directory (the directory returned
     by (locate-data-directory "ecb").

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

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

 -- User Option: tree-make-parent-node-sticky
     Make the parent-node sticky in the headerline of the tree-buffer.

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

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

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

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

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

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

        * 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: tree-stickynode-indent-string
     String used to indent the stickynode.  This string is used to match the
     space used by scrollbars and fringe so it does not appear that the
     node-name is moving left/right when it lands in the sticky line.

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

     Changing this option takes only effect after restarting Emacs!

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

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

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

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


File: ecb.info,  Node: ecb-directories,  Next: ecb-sources,  Prev: ecb-tree-buffer,  Up: Customizable options

7.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-basic-buffer-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
     (*note Using the mouse::).

     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.

     If no dynamically evaluated menu-extensions should be added to the
     directories-buffer the function has to return nil. Therefore the
     default-value of this option is `ignore'.

     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: directories-show-node-info
     When to display which node-info in the directories-buffer.  Define which
     node info should be displayed after moving the mouse over a node (or
     after a shift click onto the node) in the directories-buffer.

     You can define "when" a 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.

     You can define "which" info should be displayed:
        - name: Only the full node-name is displayed.

        - path: The full-path of the node is displayed.

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

 -- 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 basic tree-buffers to this file-buffer - at least if
     the option `ecb-basic-buffer-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.

     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-elemet 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.


File: ecb.info,  Node: ecb-sources,  Next: ecb-methods,  Prev: ecb-directories,  Up: Customizable options

7.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 source for
     which the popup-menu has been opened. Use always `ecb-source-get-*' to
     extract whatever you need from the node-data. E.g. use
     `ecb-source-get-filename' to get the full filename of the source of the
     node.

     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.

     If no dynamically evaluated menu-extensions should be added to the
     sources-buffer the function has to return nil. Therefore the
     default-value of this option is `ignore'.

     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 stealthily (see
     `ecb-stealthy-tasks-delay') so normally the user should not see a
     performance-decrease or additional waiting-time. 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-show-node-info
     When to display which node-info in the sources-buffer.  Define which
     node info should be displayed after moving the mouse over a node (or
     after a shift click onto the node) in the sources-buffer.

     You can define "when" a node-info should be displayed: See
     `ecb-directories-show-node-info' for the possible choices.

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

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

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


File: ecb.info,  Node: ecb-methods,  Next: ecb-history,  Prev: ecb-sources,  Up: Customizable options

7.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: disable-semantic-threshold-alist
     Threshold for disabling semantic-parsing Define a threshold fpr
     buffer-size. Exceeding this threshold disables parsing current buffer by
     semantic.

     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 an integer which defines the threshold for the
          buffer-size for this major-mode.

     Example:

          ((default . 1000000)
            (c-mode . 200000))

     This example whould not parse c-mode buffers exceeding a buffer-size of
     200000. And buffers of all other modes would be only parsed if smaller
     than 1000000.

     A setting of `((c-mode . 200000))' would only restrict c-mode buffers to
     a size of 200000 but would parse all other buffer regardless their size.

 -- User Option: display-image-icons-for-semantic-tags
     Display nice and pretty icons for semantic-tags in the Methods-buffer. A
     non nil value 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: find-external-tag-functions
     Functions used for searching external tags clicked in the methods buffer.

     The methods buffer displays for oo-languages the parents of a type under
     a special bucket "Parents". Languages like C++, CLOS and Eieio allow to
     define the implementation of a method outside of the class definition
     and even in another file. In the methods-buffer of ECB such externaly
     defined methods are collected and displayed under a `virtual' faux
     type-tag named as the class-qualifier of the methods. This faux-tag is
     virtual because it does not extist in the parsed buffer.

     If a user clicks either onto such a faux-type-tag or onto a parent-tag
     then ECB tries to find the definition of the underlying type on a
     name-basis, displaying the containing file as buffer in the current
     edit-window and jumping to the start of the type-definition in this
     buffer.

     Finding such external types can be very complex and there are several
     roads to success. ECB uses per default methods based on the
     semantic-analyzer. But this option allows to define own find-functions
     and tell ECB to uses them.

     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 find-functions or nil.

     ECB first performs all find-functions defined for current `major-mode'
     (if any) anf then all find-functions defined for the special symbol
     'default (if any).

     ECB offers some predefined senseful finding-functions. Currently there
     are:
        * `ecb-search-type-tag-by-semantic-analyzer' (most powerful)

        * `ecb-search-type-tag-by-semanticdb'

        * `ecb-jde-show-class-source' (for major-mode `jde-mode' when coding
          in java)

     This function does not only the searching but displays the founded tag.
     See the documentation of these function for details how they work.

     But you can add any arbitrary function if the following conditions are
     fulfilled:

        * The function gets a semantic tag representing the external type
          which should be found. This is a positionless-tag (otherwise it
          would not be hard to go to it) and it's either a faux-tag (for
          which `ecb--semantic-faux-tag-p' is not nil; the function can use
          this check if necessary) or a simple tag containing only a name an
          a tag-class. The tag-class for both is 'type.

        * The return value of the function must be one of:
             - `nil': No tag is found

             - `t': A tag has been found and also be displayed in the
               edit-window (this prevents ECB from running further function
               of this option because the searched tag is already displayed.
               So a function should only return `t' if all is fine and no
               further actions are needed.

             - A positioned semantic tag (for which
               `ecb--semantic-tag-with-position-p' returns not `nil') which
               represents the found external type-tag.

     It's strongly recommended for the function not to display the found
     location for itself but to return a positioned semantic tag! But
     sometimes the displaying is integrated in a third-party find-function
     like `jde-show-class-source' which is used by
     `ecb-jde-show-class-source'. In these cases the function has to return t
     if the searched tag has been successfully displayed.

     Precondition for a find-function: Current buffer is the buffer the
     clicked faux- or parent tag belongs to Current point depends on the
     clicked tag:
        * In case of a faux-tag it's the start of the first child of the
          faux-tag. There must be at least one adopted child-tag because
          otherwise we would not have the faux-tag

        * In case of an external parent-tag its the the start of the external
          tag itself.

 -- 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'.

     If no dynamically evaluated menu-extensions should be added to the
     methods-buffer the function has to return nil. Therefore the
     default-value of this option is `ignore'.

     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: methods-show-node-info
     When to display which node-info in the methods-buffer. Define which node
     info should displayed after moving the mouse over a node (or after a
     shift click onto the node) in the methods-buffer.

     You can define "when" a node-info should be displayed: See
     `ecb-directories-show-node-info' for the possible choices.

     You can define what info should be displayed:
        - 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: 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!


File: ecb.info,  Node: ecb-history,  Next: ecb-analyse,  Prev: ecb-methods,  Up: Customizable options

7.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-make-buckets
     Bucketize the entries of the history-buffer.

     There are several options how the bucketizing should be done:
        * 'never:

          No bucketizing at all, ie. all entries of the history-buffer we be
          displayed flat.

        * 'directory:

          All entries with related filesources residing in the same directory
          will be contained in a bucket named with that directory.

        * 'directory-with-source-path:

          Same as 'directory but the best matching source-path of the
          directory-window (see `ecb-source-path') substituts the matching
          part of the directory.  For this a special face is used (see
          `ecb-history-bucket-node-dir-soure-path-face').

        * 'mode:

          All entries with related buffers have the same major-mode will be
          contained in a bucket named with that major-mode

        * 'extension:

          All entries with related filesources having the same extension will
          be contained in a bucket named with that extension

     If the value is a list of regular expressions then all entries where the
     buffername matches the same regular expression will be contained in one
     bucket. If the value is nil then this is interpreted as an empty list of
     regular expressions!

     The default value is 'directory.

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

     car is the filename of the source for which the popup-menu has been
     opened. cdr is the related buffer-name; but be careful, because the node
     can point to a dead buffer (see `ecb-kill-buffer-clears-history'). Use
     always `ecb-source-get-*' to extract whatever you need from the
     node-data. E.g. use `ecb-source-get-filename' to get the full filename
     of the source of the node and use `ecb-source-get-buffername' or
     `ecb-source-get-buffer' to get the buffername rsp. the buffer-object.

     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.

     If no dynamically evaluated menu-extensions should be added to the
     history-buffer the function has to return nil. Therefore the
     default-value of this option is `ignore'.

     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-show-node-info
     When to display which node-info in the history-buffer.  Define which
     node info should be displayed after moving the mouse over a node (or
     after a shift click onto the node) in the history-buffer.

     You can define "when" a node-info should be displayed: See
     `ecb-directories-show-node-info' for the possible choices.

     You can define "which" info should be displayed:
        * name: Only the full node-name is displayed.

        * path: The full-path of the node is displayed.

        * name-path: The full node-name and the full-path is displayed.

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

 -- 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'.

     If the history is bucketized (see `ecb-history-make-buckets') then this
     sorting applies to the sorting within each bucket.

 -- User Option: history-stick-indirect-buffers-to-basebuffer
     Stick all indirect-buffers as subnodes to their base-buffer.

     If nil then indirect-buffers are treated as non-indirect-buffers and
     sorted into the history-buffer-sequence according to the setting of
     `ecb-history-sort-method'.

     If not nil then indirect-buffers are always sticked to their
     base-buffer, ie.  the base-buffer is displayed as expandable node with
     all its indirect-buffers as children-nodes, so the history looks like:

        [-] <base-buffer BB>
         |  <indirect-buffer 1 of BB>
         `- <indirect-buffer 2 of BB>

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


File: ecb.info,  Node: ecb-analyse,  Next: ecb-symboldef,  Prev: ecb-history,  Up: Customizable options

7.3.7 Group ecb-analyse
-----------------------

 -- User Option: analyse-bucket-element-face
     Basic face for displaying elements of buckets in the ECB-analyse-buffer.
     This defines the basic face for the elements of category-buckets like
     Context, Prefix, Completions etc. in the ECB-analyse-buffer.

     Changes take first effect after finishing and reactivating ECB!

 -- User Option: analyse-bucket-node-face
     Basic face for displaying a bucket-node in the ECB-analyse-buffer.  This
     defines the basic face for the bucket-nodes like Context, Prefix,
     Completions etc. in the ECB-analyse-buffer.

     Changes take first effect after finishing and reactivating ECB!

 -- User Option: analyse-buffer-after-create-hook
     Local hook running after the creation of the analyse-buffer. Every
     function of this hook is called once without arguments direct after
     creating the analyse-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 key-bindings only for the analyse-buffer
     of ECB.

 -- User Option: analyse-buffer-name
     Name of the ECB analyse buffer. Because it is not a normal buffer for
     editing you should enclose the name with stars, e.g. "*ECB Analyse*".

     If it is necessary for you you can get emacs-lisp access to the
     buffer-object of the ECB-analyse-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: analyse-buffer-sync
     Synchronize the analyse buffer automatically with current edit buffer.

     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.

     Normally it's not necessary to exclude some major-modes because with
     not-semantic supported major-modes simply nothing happens. But maybe it
     can be helpful for certain situations...

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync'.

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

 -- User Option: analyse-buffer-sync-delay
     Time Emacs must be idle before the analyse-buffer is synchronized.
     Synchronizing is done with the current source displayed in the edit
     window. If nil then there is no delay, means synchronization takes place
     immediately.

     CAUTION: With analysing a value not too small is strongly recommended
     because it can be very annoying if more or less after each typing the
     current context is analysed. If set to nil then *each* keyboard hit
     refreshes the analyse-buffer which will make ECB quite unusable!

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync-delay'

 -- User Option: analyse-buffer-sync-hook
     ook run at the end of `ecb-analyse-buffer-sync'.  See documentation of
     `ecb-analyse-buffer-sync' for conditions when synchronization takes
     place and so in turn these hooks are evaluated.

     Preconditions for such a hook:

        * Current buffer is the buffer of the currently selected edit-window.

        * The analyse-buffer is displayed in a visible window of the
          ecb-frame (so no check for visibilty of the analyse-buffer in the
          ecb-frame is necessary in a hook function)

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

     Important note: If the option `ecb-analyse-buffer-sync' is not nil the
     function `ecb-analyse-buffer-sync' is running either every time Emacs is
     idle or even after every command (see `ecb-analyse-buffer-sync-delay').
     So if the anaylse-buffer is displayed in a window of the ecb-frame (see
     preconditions above) 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!

 -- User Option: analyse-collapsed-buckets
     Buckets collapsed when displaying the current semantic analysis. The
     semantic analyse-modul offers several categories of analysis which are
     called buckets here. These are for example:

     Context: The current context, which is the current function/method,
     variable, class etc. (what exactly depends on the programming language)
     point is in. This means not the current
     function/method/variable/class-name point stand on but the current
     surrounding context. Example: If point stays somewhere within a
     defun-definition in emacs-lisp or within a java-method then this defun
     rsp. method is the context. In object oriented languages this can be the
     full hierachy, i.e. not only the current method, but the current method,
     the class of this method, the superclass of this class and so on!

     Arguments: The arguments of the context if the context is a
     function/method.

     Local Variables: All accessible and bound local variables visible at
     current point.

     Prefix: The currently parsed prefix, which is mostly the current
     identifier point stands on.

     Assignee: See the semantic user-manual

     Function: Current function-name point stands on.

     Argument #: When point is located within a function-call then this is
     the number of the argument point stands on.

     Completions: All possible completions for current prefix (see above).
     This is probably the most helpful bucket.

     If one of these categories/buckets are not needed per default then add
     the bucket-name (s.a.) to this option and ECB will per default collapse
     this bucket. So most needed buckets are better visible in the
     analyse-buffer.

 -- User Option: analyse-face
     Face used for highlighting current entry in the analyse 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: analyse-fontified-buckets
     Buckets whose elements should be fontified as in the methods-buffer.  If
     the name of a category/bucket is contained in this option then all
     elements of this bucket will be displayed as in the methods-buffer - at
     least if an element is a semantic-tag. This means if
     `ecb-font-lock-tags' is not nil these elements will be fontified and
     also displayed with an appropriate icon if possible. The default value
     does this only for the Context-bucket because for most of the other
     buckets this makes not really much sense.

     For available buckets see `ecb-analyse-collapsed-buckets'.

     For the faces used to display a bucket-node itself or bucket-elements
     not fontified see the options `ecb-analyse-bucket-node-face' rsp.
     `ecb-analyse-bucket-element-face'.

 -- User Option: analyse-gen-tag-info-fn
     Which info should be displayed for a tag of the analyse-buffer. If nil
     then the default information about a tag will be displayed. If a
     function then this function gets as argument the tag for which
     tag-information should be displayed. This function has to return a
     string which will be then display as tag-info. This string has to be
     fully formatted (e.g. must already include line-breaks if the tag-info
     should be displayed in several lines).

     See `ecb-analyse-show-tag-info-fn' how the tag-info is displayed.

 -- User Option: analyse-general-face
     Basic face for the ECB analyse 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: analyse-show-node-info
     When to display which node-info in the history-buffer. Define which node
     info should displayed after moving the mouse over a node (or after a
     shift click onto the node) in the history-buffer.

     You can define "when" a node-info should be displayed: See
     `ecb-directories-show-node-info' for the possible choices.

     You can define what info should be displayed:

        - name: The full name of the node

        - full-info: All infos available to a node.

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

 -- User Option: analyse-show-tag-info-fn
     How to display the tag-info for a tag of the analyse-buffer. The value
     of this option is a function which will be called with the info-string
     generated for the current tag of the analyse-buffer. This function must
     do all things necessary for displaying this info. When this function is
     called the window stored in `ecb-last-edit-window-with-point' is the
     selected window!

     ECB offers two builtin ways: Display the info in the echo-area (via the
     function `message') or in a temp-buffer in the edit-area (via the
     function `ecb-analyse-show-tag-info-in-temp-buffer'). Default is
     echo-area-display.

     See also `ecb-analyse-gen-tag-info-fn'.


File: ecb.info,  Node: ecb-symboldef,  Next: ecb-layout,  Prev: ecb-analyse,  Up: Customizable options

7.3.8 Group ecb-analyse
-----------------------

 -- User Option: symboldef-buffer-name
     Name of the ECB-symbol-definition buffer.  Because it is not a normal
     buffer for editing you should enclose the name with stars, e.g. "*ECB
     Symboldefinition*".

     If it is necessary for you you can get emacs-lisp access to the
     buffer-object of the ECB-symbol-definition-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: symboldef-buffer-sync
     Synchronize the symboldef buffer automatically with current edit buffer.

     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.

     If the special value `basic' is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync'.

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

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

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync-delay'.

 -- User Option: symboldef-buffer-sync-hook
     ook run at the end of the function `ecb-symboldef-buffer-sync'.  See
     documentation of `ecb-symboldef-buffer-sync' for conditions when
     synchronization takes place and so in turn these hooks are evaluated.

     Preconditions for such a hook:

        * Current buffer is the buffer of the currently selected edit-window.

        * The symboldef-buffer is displayed in a visible window of the
          ecb-frame (so no check for visibilty of the symboldef-buffer in the
          ecb-frame is necessary in a hook function)

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

     Important note: If the option `ecb-symboldef-buffer-sync' is not nil the
     function `ecb-symboldef-buffer-sync' is running either every time Emacs
     is idle or even after every command (see
     `ecb-symboldef-buffer-sync-delay'). So if the symboldef-buffer is
     displayed in a window of the ecb-frame (see preconditions above) 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!

 -- User Option: symboldef-find-functions
     Funtions to find the definition for current symbol under point.  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 car is a function intended to find the definition of a certain
          symbol for files of this major-mode. Such a function will be called
          with two arguments, the first is the symbol-name as string for
          which the definition should be displayed and the second the current
          edit-buffer as buffer-object, i.e. the current buffer of the
          current edit-window. The function will be called with the special
          ecb-symbol-definition-buffer as current buffer whereas this buffer
          is empty. The function has to insert everything necessary to
          display the symbol-definition and is also responsible to format the
          displayed text. The buffer-local variable `fill-column is already
          preset to the window-width of the special ecb-window minus 1. The
          function is responsible to set the buffer-local variable
          `truncate-lines' appropriate.  The function can either return nil
          or a string which will be integrated in the modeline-display of
          this ecb-window.

     There are two prefined functions `ecb-symboldef-find-lisp-doc' and
     `ecb-symboldef-find-definition' whereas the latter on is used a default
     find-function.

 -- User Option: symboldef-minimum-symbol-length
     Minimum length a symbol must have so its definition or doc is displayed.


File: ecb.info,  Node: ecb-layout,  Next: ecb-compilation,  Prev: ecb-symboldef,  Up: Customizable options

7.3.9 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-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 user-commands 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 the latter case there is an additional value
     `auto' which choose autom. the senseful fix-type depending on the
     current layout-type: For top-layouts the fix-type `height' and for all
     other layout-types the fix-type `width'.

     For a detailed description of the valid values see documentation 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. This option has no effect with XEmacs because it does not
     support the feature `window-size-fixed'.

     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 Emacs < 22 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) with Emacs < 22 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' 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 persistent 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-pop-up-frames
     Ignore setting of option `pop-up-frames'.  This means, that a value of
     not nil for `pop-up-frames' is ignored:
        * 'compile-window: only when persistent compile window is used - i.e.
          if `ecb-compile-window-height' is not nil - this is the default
          value.

        * 'always: always when ECB is active - that means no pop-up-frames
          when ECB is active

        * `nil': pop-up-frames is fully active when set

 -- 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 persistent 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, 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 function where it is
     senseful. If the symbol of an adviced function is contained in the value
     of this option, then the 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.

     Per default this is only enabled for `switch-to-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 very strongly recommended way) to set this option 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:
        * Use always `customize-option', never `setq'!

        * It is recommended to use fractions of frame-width and -height!.

        * It is also recommended to use buffer-name-symbols instead of plain
          buffer-names (e.g. ecb-history-buffer-name instead of " *ECB
          History*")

        * There must be an entry for each special ecb-buffer of that layout
          for which the sizes are stored.

        * The order of the sequence of the inserted window sizes doesn't
          matter because each size-pair is assigned to a buffer-name the
          sizes belong to.

 -- 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: maximize-next-after-maximized-select
     Maximizes the next logical tree-window after a maximized node-selection.
     Selecting a node in a maximized tree-window is handled very smart by ECB:

     If a tree-buffer-name is not contained in this option then selecting a
     node in this maximized tree-buffer automatically "minimizes" that
     tree-window (i.e. displays all windows of the current layout) so the
     user can perform the next logical step (e.g. the next logical step after
     selecting a directory in the directories-buffer is to select a
     source-file - therefore the sources-buffer of current layout has to be
     displayed - if the current layout contains one; the next logical step of
     selecting a source-file is probably to jump to a certain tag via the
     methods-buffer).

     If a tree-buffer-name is contained in this option then selecting a node
     in this tree-buffer automatically maximizes the next logical tree-window
     (e.g. directories -> sources, sources/history -> methods). But if the
     current maximized tree-buffer is also contained in the option
     `ecb-tree-do-not-leave-window-after-select' (see also the
     tree-buffer-command `ecb-toggle-do-not-leave-window-after-select' which
     is bound to `C-t' in each tree-buffer) then ECB does *not* maximize the
     next logical tree-window but point stays in the currently maximized
     tree-buffer so for example the user can select more than one node (e.g.
     more than one source-file from the sources-buffer.

     The tree-buffer-name can either be defined as plain string or with a
     symbol which contains the buffer-name as value. The latter one is
     recommended for the builtin ECB-tree-buffers because then simply the
     related option-symbol can be used (e.g.  `ecb-directories-buffer-name',
     `ecb-sources-buffer-name' or `ecb-history-buffer-name').

     In future versions this option will probably also allow to define the
     next logical tree-buffer for a tree-buffer - currently this is
     hard-coded as follows:
        - directories -next-logical-> sources

        - sources     -next-logical-> methods

        - history     -next-logical-> methods.

 -- User Option: maximize-next-after-maximized-select
     Maximizes the next logical tree-window after a maximized node-selection.
     Selecting a node in a maximized tree-window is handled very smart by ECB:

     If this option is nil then selecting a node in a maximized directories-
     sources- or history-tree-buffer automatically "minimizes" that
     tree-window (i.e. displays all windows of the current layout) so the
     user can perform the next logical step (e.g.  the next logical step
     after selecting a directory in the directories-buffer is to select a
     source-file - therefore the sources-buffer of current layout has to be
     displayed - if the current layout contains one; the next logical step of
     selecting a source-file is probably to jump to a certain tag via the
     methods-buffer).

     If this option is not nil then selecting a node in a maximized
     directories- sources- or history-tree-buffer automatically maximizes the
     next logical tree-window (directories -> sources, sources/history ->
     methods). But if the current maximized tree-buffer is contained in the
     option `ecb-tree-do-not-leave-window-after-select' (see also the
     tree-buffer-command `ecb-toggle-do-not-leave-window-after-select' which
     is bound to `C-t' in each tree-buffer) then ECB does *not* maximize the
     next logical tree-window but point stays in the currently maximized
     tree-buffer so for example the user can select more than one source-file
     from the sources-buffer.

 -- 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". 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.


File: ecb.info,  Node: ecb-compilation,  Next: ecb-create-layout,  Prev: ecb-layout,  Up: Customizable options

7.3.10 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
     (*note Using eshell::).

     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 (*note Using
     eshell::).

 -- 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 persistent 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 persistent 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 persistent compilation window then ECB displays all
     buffers for which `ecb-compilation-buffer-p' returns not nil in that
     persistent 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 persistent 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'.


File: ecb.info,  Node: ecb-create-layout,  Next: ecb-face-options,  Prev: ecb-compilation,  Up: Customizable options

7.3.11 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.


File: ecb.info,  Node: ecb-face-options,  Next: ecb-faces,  Prev: ecb-create-layout,  Up: Customizable options

7.3.12 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-bucket-node-dir-soure-path-face
     Basic face for displaying the source-path part in a directory bucket.
     This defines the face for the source-path part in a bucket-node of the
     history-buffer if `ecb-history-make-buckets' is set to
     'directory-with-source-path. For all other values of
     `ecb-history-make-buckets' this option takes no effect.

     Changes take first effect after finishing and reactivating ECB!

 -- User Option: history-bucket-node-face
     Basic face for displaying a bucket-node in the ECB-history-buffer.  This
     defines the basic face for the bucket-nodes used to bucketize the
     history-entries as defined with the option `ecb-history-make-buckets'.

     Changes take first effect after finishing and reactivating ECB!

 -- User Option: history-dead-buffer-face
     Face for history entries pointing to dead buffers.

     Changes take first effect after finishing and reactivating ECB!

 -- 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: history-indirect-buffer-face
     Face for indirect buffers in the history buffer.

     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: symboldef-prototype-face
     Which face should be used for the symbol prototype in the
     symboldef-buffer.

     The prototype can be the function prototype in case of a function or
     method or - in case of a variable - the type of the variable (in case of
     a typed language).

 -- User Option: symboldef-symbol-face
     Which face should be used for the symbol itself in the symboldef-buffer.

     There are two choices: Either a face or the special symbol
     'use-font-lock-face whereas the latter one means that ECB uses that face
     font-lock uses for fontifying the symbol (e.g.
     font-lock-function-name-face for a function symbol or
     font-lock-variable-name-face for a variable symbol).

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


File: ecb.info,  Node: ecb-faces,  Next: ecb-help,  Prev: ecb-face-options,  Up: Customizable options

7.3.13 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 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
     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 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 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-bucket-node-dir-soure-path-face:'
     Face used for displaying the source-path part in a directory-bucket.

     In GNU Emacs 21.X this face inherits from the face
     `ecb-history-bucket-node-face'.

     With XEmacs and GNU Emacs 20.X there is no inheritance-feature so if the
     buckets in the ECB-history-buffer should be displayed with the same basic
     attributes set by `ecb-history-bucket-node-face' this set of basic
     attributes have to be set in
     `ecb-history-bucket-node-dir-soure-path-face' too!

`ecb-history-bucket-node-face:'
     Face used for displaying a bucket-node in the ECB-history-buffer.

     In GNU Emacs 21.X this face inherits from the face
     `ecb-bucket-node-face'. With XEmacs and GNU Emacs 20.X there is no
     inheritance-feature so if the buckets in the ECB-history-buffer should be
     displayed with the same basic attributes set by `ecb-bucket-node-face'
     this set of basic attributes have to be set in
     `ecb-history-bucket-node-face' too!

`ecb-history-dead-buffer-face:'
     Face used for history entries pointing to dead buffers.

     In GNU Emacs 21.X this face inherits from the face
     `ecb-history-general-face'. With XEmacs and GNU Emacs 20.X there is no
     inheritance-feature so if the buckets in the ECB-history-buffer should be
     displayed with the same basic attributes set by
     `ecb-history-general-face' this set of basic attributes have to be set in
     `ecb-history-dead-buffer-face' too!

`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-history-indirect-buffer-face:'
     Face used for history entries pointing to dead buffers.

     In GNU Emacs 21.X this face inherits from the face
     `ecb-history-general-face'. With XEmacs and GNU Emacs 20.X there is no
     inheritance-feature so if the buckets in the ECB-history-buffer should be
     displayed with the same basic attributes set by
     `ecb-history-general-face' this set of basic attributes have to be set in
     `ecb-history-indirect-buffer-face' too!

`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-mode-line-win-nr-face'
     Define face for the window-number in the mode-line. See
     `ecb-mode-line-display-window-number'.

`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-symboldef-prototype-face'
     Define face used for the prototype of symbol in the symboldef-buffer.

`ecb-symboldef-symbol-face'
     Define a face used for the symbol itself in the symboldef-buffer

`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'.


Just call `customize-face <face-name>' to customize these faces for your
personal taste. Or customize the related option in the group *Note
ecb-face-options::.


File: ecb.info,  Node: ecb-help,  Next: ecb-eshell,  Prev: ecb-faces,  Up: Customizable options

7.3.14 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.


File: ecb.info,  Node: ecb-eshell,  Next: ecb-speedbar,  Prev: ecb-help,  Up: Customizable options

7.3.15 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-buffer-sync
     Synchronize eshell with the default-directory of current source-buffer.

     This option takes only effect if a permanant compile-window is used in
     the current layout.

     If 'always then the synchronization takes place always a buffer changes
     in the edit window and if after this the default-directory of the new
     edit-buffer is different from the default-directory of the current
     eshell-buffer. If value is nil then never a synchronization will take
     place. If a list of major-modes then only if the `major-mode' of the new
     buffer belongs NOT to this list.

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync'.

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

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync-delay'.

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


File: ecb.info,  Node: ecb-speedbar,  Next: ecb-non-semantic,  Prev: ecb-eshell,  Up: Customizable options

7.3.16 Group ecb-speedbar
-------------------------

 -- User Option: speedbar-before-activate-hook
     Hook running directly before ECB activates the integrated speedbar.

     For example this hook can be used to change the expansion-mode of the
     integrated speedbar via `speedbar-change-initial-expansion-list'.
     Example: (speedbar-change-initial-expansion-list "buffers").

 -- User Option: speedbar-buffer-sync
     Synchronize the speedbar-buffer of ECB automatically with current edit
     buffer.

     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.

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync'.

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

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

     If the special value 'basic is set then ECB uses the setting of the
     option `ecb-basic-buffer-sync-delay'.

 -- User Option: speedbar-buffer-sync-hook
     ook run at the end of `ecb-speedbar-buffer-sync'.  See documentation of
     `ecb-speedbar-buffer-sync' for conditions when synchronization takes
     place and so in turn these hooks are evaluated.

     Preconditions for such a hook:

        * Current buffer is the buffer of the currently selected edit-window.

        * The speedbar-buffer is displayed in a visible window of the
          ecb-frame (so no check for visibilty of the speedbar-buffer in the
          ecb-frame is necessary in a hook function)

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

     Important note: If the option `ecb-speedbar-buffer-sync' is not nil the
     function `ecb-speedbar-buffer-sync' is running either every time Emacs
     is idle or even after every command (see
     `ecb-speedbar-buffer-sync-delay'). So if the speedbar-buffer is
     displayed in a window of the ecb-frame (see preconditions above) 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!


File: ecb.info,  Node: ecb-non-semantic,  Next: ecb-winman,  Prev: ecb-speedbar,  Up: Customizable options

7.3.17 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.


File: ecb.info,  Node: ecb-winman,  Next: ecb-mode-line,  Prev: ecb-non-semantic,  Up: Customizable options

7.3.18 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!


File: ecb.info,  Node: ecb-mode-line,  Next: ecb-version-control,  Prev: ecb-winman,  Up: Customizable options

7.3.19 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')!


File: ecb.info,  Node: ecb-version-control,  Prev: ecb-mode-line,  Up: Customizable options

7.3.20 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: Support for CVS, RCS, SCCS, Subversion, Git, Bazaar,
     Monotone and Mercurial. To identify the VC-backend the functions
     `ecb-vc-dir-managed-by-CVS', `ecb-vc-dir-managed-by-RCS' rsp.
     `ecb-vc-dir-managed-by-SCCS' rsp. `ecb-vc-dir-managed-by-SVN' rsp.
     `ecb-vc--dir-managed-by-GIT' rsp. `ecb-vc-dir-managed-by-BZR' rsp.
     `ecb-vc-dir-managed-by-MTN' rsp. `ecb-vc-dir-managed-by-HG'are used.

     For all eight backends the function `ecb-vc-state' of the VC-package is
     used by default (which uses a heuristic and therefore faster but less
     accurate approach), but there is also `ecb-vc-recompute-state' available
     which is an alias for `vc-recompute-state' (which returns accurate
     state-values by calling the backend which can be slow especialy for
     remote root-repositories!)

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


File: ecb.info,  Node: Submitting problem report,  Next: Upgrading,  Prev: Customizing,  Up: Top

8 Submitting a problem report
*****************************

If you run into problems with ECB you should first take a look into

   - *Note FAQ:: or

   - *Note Conflicts and bugs:: or

   - *Note Common use-cases:: or

   - the appropriate section of this online-manual.

If your problem(s) still remain you can/should send a problem report to the
ECB mailing list <ecb-list@lists.sourceforge.net>. ECB offers you a command
which does all necessary for you to send a problem report. Just call
`ecb-submit-problem-report'! Please read the documentation of this command,
see *Note Interactive ECB commands::.

*IMPORTANT*: Cause of extra appearance of SPAM in the mailing-lists,
SourceForge has changed its policy: Now it is only possible to post to the
mailing-list for users who have subscribed this mailing-list. So please be
aware you will not be able to send comments, bug reports and improvement
suggestions before you have subscribed the ECB-mailing-list. See the section
"Mailing-list" at the ECB-website at `http://ecb.sourceforge.net' how to do
this.

If you think there are problems concerning parsing-results for certain
sources supported by semantic then you should call
`ecb-dump-semantic-toplevel' for the problematic source-buffer *BEFORE* you
call `ecb-submit-problem-report' because this "dump"-command generates for
the current-buffer a new buffer with name "*ecb-tag-dump*" which contains all
semantic-tags for this source. The contents of this "*ecb-tag-dump*" will
then autom. be added to the problem-report generated by
`ecb-submit-problem-report'!

This command creates a problem-report buffer for you. After that you get a
menu "Mail" (dependent on the mail-package used, the menu can have a
different name) with commands to send the problem report. But for this the
variable `mail-user-agent' must be configured right for your system. If you
canﾴt get working this mechanism you can simply copy the whole
problem-report buffer after filling it out and sending it with your standard
mail-client to <ecb-list@lists.sourceforge.net>!

Please read also the documentation of the option `ecb-debug-mode' and switch
on the debug mode of ECB (also available in the Help-menu of ECB!) before
submitting a problem-report!


File: ecb.info,  Node: Upgrading,  Next: Common use-cases,  Prev: Submitting problem report,  Up: Top

9 Upgrading and downloading packages
************************************

This chapter describes all aspects of upgrading to a newer version of ECB.

The first section describes how to download and install a new package from
the web, where "package" means either ECB itself or the required library CEDET

After installing a new ECB-version ECB checks if the values of the customized
ECB-options are still compatible. If not ECB does some smart things. This is
the topic of the second section.

* Menu:

* Downloading new versions::    How to download newer versions of packages
* Auto. option-upgrading::      ECB can auto. upgrade your options


File: ecb.info,  Node: Downloading new versions,  Next: Auto. option-upgrading,  Prev: Upgrading,  Up: Upgrading

9.1 Downloading new versions of ECB and/or CEDET
================================================

*Please note*: THE PACKAGE-DOWNLOAD-FEATURE OF ECB IS COMPLETELY DEACTIVATED
SINCE VERSION 2.33! Please got to the website of ECB and download and install
"by hand":

  1. Download ECB

     Go to `http://ecb.sourceforge.net' and download the latest release (or
     if you are brave and tough the latest CVS-snapshot) from the download
     section.

     Save the archive (either *.tar.gz or *.zip) in a suitable location of
     your disk.

  2. Extract the downloaded ECB-archive

     Extract the archive with a suitable extraction-tool. The archive will
     extract into a new directory `ecb-<version>' whereas <version> is either
     the version number of the downloaded release or "latest" in case of the
     CVS-snapshot. (example for a release: The archive extracts into a new
     subdirectory `ecb-2.33'.

     The newly created subdirectory contains all files of ECB in the needed
     subdirectory structure.

     *Note*: Do not change the subdirectory structure of the extracted
     archive - this will prevent ECB from working correctly!

  3. Install and setup ECB

     See *Note Installation::.

  4. Start ECB

     ECB will perform some requirements checks, especially for CEDET.
     *Remark*: By setting the option `ecb-version-check' to `nil' you can
     prevent ECB from checking correct versions of CEDET but it's strongly
     recommended not to do this!

  5. (Optional) Download and install a newer version of CEDET

     If the version-check in (4) fails then you have to install a newer
     version of CEDET which fulfill the version-number ECB reports to you
     after its version check.

     See the instruction of CEDET how to do this. You will find CEDET at
     `http://cedet.sourceforge.net'

     For setting up CEDET see *Note Setting up CEDET/semantic::.

     If you have installed a new CEDET-version you *MUST* re-byte-compile ECB
     unless you run ECB not byte-compiled!



File: ecb.info,  Node: Auto. option-upgrading,  Prev: Downloading new versions,  Up: Upgrading

9.2 Automatic upgrading of options
==================================

* Menu:

* User interface::              Options and commands you should know
* Background information::      Maybe some interesting informations


File: ecb.info,  Node: User interface,  Next: Background information,  Prev: Auto. option-upgrading,  Up: Auto. option-upgrading

9.2.1 User interface for option-upgrading
-----------------------------------------

There are two interactive commands (*note Interactive ECB commands::):

   - `ecb-upgrade-options': Does all necessary beginning with a
     incompatibility-check for all options, upgrading/resetting incompatible
     options and ending with the display of all upgraded or reset options.

   - `ecb-display-upgraded-options': Displays an information-buffer which
     options have been upgraded or reset. Offers two buttons where the user
     can decide if the upgraded options should also being saved by ECB for
     future settings or if the buffer should be killed.

If the option `ecb-auto-compatibility-check' has a non-nil value (which is
the default) then ECB does all this stuff automatically at startup. This is
very recommended!

If you are interested in some background information, read *Note Background
information::!


File: ecb.info,  Node: Background information,  Prev: User interface,  Up: Auto. option-upgrading

9.2.2 Background information
----------------------------

Big packages like ECB will be enhanced and developed continuously so
sometimes a new version must be released. Such packages offer in general a
lot of customizable options so probably some of these options change the type
or are renamed because the old type and/or name of the option makes no sense
in the new release.

Especially options which have changed the type of their value are now a
problem for the user which want to upgrade to the latest ECB-version: If the
user has saved a certain value for option X in its file `.emacs' but the type
of this saved value doesn't match the new defined type in the defcustom-form
after an ECB-upgrade then there can occur serious problems like ECB can not
be started anymore or even Emacs can not be started without errors.

Until now there was only one way to fix these problems: The user must
manually edit his file `.emacs' and remove all entries for options which have
now another type. After this and after restarting Emacs the new
default-values of the type-changed options in the new ECB-release are active
and the user can go on using Emacs and ECB. But this approach to fix the
incompatible-option-problem has two serious drawbacks:

  1. The user must manually edit the customize-section in his file `.emacs'.
     This should normally not be done and if then only by old-handed
     Emacs-users.

  2. The customized value of the option X in the old-release (with the old
     type) is lost because after removing the related entry from the file
     `.emacs' the new default-value is active, so the user must re-customize
     the option X.

OK, this is one half of the option-upgrade-problem but a new ECB-release can
also rename a option from name X to name Y because the new name Y makes much
more sense and/or is more mnemonic. If only the name has changed but not the
type this is not a serious problem like above but also annoying because the
customized value of the old-option X takes no effect in the new release but
instead the default-value of the new-option Y is now active.  But
nevertheless this problem has the drawback number 2 (see above).

The last category of upgrade-problems is a renamed option which has also
changed its type.

ECB has a solution for all these problems:

   * It checks all customized values of all ECB-options if they are still
     type-compatible. If not then it tries to upgrade the old-value to the
     new value-type and if this is not possible then it resets the option to
     the new default value and offers then to store it via customize in the
     .emacs-file (or in any file which is used for customized options).  But
     ECB does not touch any customization-file without asking the user!

   * It offers a special constant `ecb-upgradable-option-alist' which allows
     the ECB-maintainers to define special transformings for renamed options
     so even the value of an old-option X can be savely transformed to the
     new-option Y and the old setting is not lost.

All these checks and transformings are done at beginning of activating ECB -
if the option `ecb-auto-compatibility-check' is not nil. If ECB has
recognized incompatible or renamed options it does its upgrading/reseting-job
so all ECB-options have correct types so ECB can start correct. After ECB is
started it displays a list of all upgraded or reseted option with their old
and new values.


File: ecb.info,  Node: Common use-cases,  Next: Elisp programming,  Prev: Upgrading,  Up: Top

10 Handling of common use-cases
*******************************

This chapter lists some common (and also some non-common) use-cases of ECB and
gives a detailed description for each one. This contains also some tips and
tricks how to deal best with some situations.

* Menu:

* Changing faces::              Changing faces in the ECB tree-buffers
* Small screens::               Working with small screens
* Big screens::                 Working with big screens
* Simulating speedbar::         Simulating speedbar without an extra frame
* Integrating speedbar::        Integrating speedbar in the ECB-frame
* Large directories::           Working with large directories
* Remote directories::          Working with remote directories
* Version-control support::     Supporting Version control systems
* Using eshell::                Optimal using of eshell in ECB
* Grepping directories::        Grepping directories with ECB
* Working with JDEE::           Working best with ECB and JDEE
* Compile-window on demand::    Displaying the compile-window on demand
* Non-semantic sources::        Parsing and displaying non-semantic sources
* Hide-show::                   Using hide-show from the methods-buffer-menu
* Window-managers and ECB::     Support of several Emacs-window-managers
* Virtual folders in History::  Simulating something like virtual folders


File: ecb.info,  Node: Changing faces,  Next: Small screens,  Prev: Common use-cases,  Up: Common use-cases

10.1 Changing faces in the ECB tree-buffers
===========================================

There are two basic faces:

   * `ecb-default-general-face': Basic face for displaying an ECB-tree-buffer.

     Itﾴs recommended to define the font-family, the font-size, the basic
     color etc. with this face.

     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 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
     the basic face-settings can be easily changed just by customizing the
     face `ecb-default-general-face'.

   * `ecb-default-highlight-face': Basic face for highlighting the current
     node in an ECB-tree-buffer.

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

     With XEmacs 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 the basic face-settings
     can be easily changed just by customizing the face
     `ecb-default-highlight-face'.


With these faces you can change the basic attributes easily and fast for ALL
ECB-tree-buffers. But you are also able to display each ECB-tree-buffer with
different faces, see the different options for every tree-buffer mentioned
above.

*Please note* (only for XEmacs users): Cause of the lack of the
font-inheritance feature using ONE other font for the ECB-methods buffer can
NOT be achieved just by setting `ecb-methods-general-face' to
`ecb-default-general-face' and changing the font of this default face. In
addition you have to set the same font also for the face
`ecb-bucket-node-face' like in the following example:

   (defconst my-ecb-font
             "-outline-Courier-normal-normal-13-97-96-96-c-*-iso8859-1")
   (set-face-font 'ecb-default-general-face my-ecb-font)
   (set-face-font 'ecb-bucket-node-face my-ecb-font)

This code sets the new defined font `my-ecb-font' as font for all(1)
ECB-tree-buffers (incl. the methods buffer).

---------- Footnotes ----------

(1) Of course `ecb-directories-general-face', `ecb-sources-general-face',
`ecb-methods-general-face' and `ecb-history-general-face' must be set to
`ecb-default-general-face'!


File: ecb.info,  Node: Small screens,  Next: Big screens,  Prev: Changing faces,  Up: Common use-cases

10.2 Working with small screens
===============================

If your screen is very small so you need every square-centimeter for
displaying the buffer which you want to edit, ECB offers you a special
layouts, where only the ECB-methods buffer is displayed on top or on
left-side. Here comes what you should/can do to work best with ECB in such a
situation:

   * First customize your ECB:

       1. Customize `ecb-layout-name' to layout-name "top2" (on top) or
          "left9" (on left-side)

       2. Ensure that `ecb-compile-window-height' is nil.

       3. Optional: Adjust the `ecb-windows-height' rsp. `ecb-windows-width'.

       4. Save your changes.

   * To edit your buffers: Call `ecb-toggle-ecb-windows' (also available via
     the menu "ECB" and by `C-c . lw') or `ecb-hide-ecb-windows' to hide the
     ECB-method buffer so you get all the place of your screen for editing.

   * To browse and select functions: Call `ecb-toggle-ecb-windows' or
     `ecb-show-ecb-windows' to make the ECB-method buffer visible if not
     already. If you want select a method/variable with the keyboard instead
     with the mouse you should read the section *Note Using the keyboard:: in
     this online help!

The possibility of hiding temporally the ECB windows like described above is
also useful for all the other layouts.


File: ecb.info,  Node: Big screens,  Next: Simulating speedbar,  Prev: Small screens,  Up: Common use-cases

10.3 Working with big screens
=============================

ECB offers a layout type "left-right" with special ECB-tree-windows on the
left and right side of the edit-area. The layouts "leftright1" and
"leftright2"are examples for this layout type.  See *Note Creating a new
ECB-layout:: and *Note The layout-engine:: for details about how to create or
program more layouts of this type.

Such a layout is eventually the best choice for big screens because the
several ECB-tree-windows are bigger and can display more informations without
scrolling.

With such a layout it can could be senseful to reduce the value of the option
`ecb-windows-width' compared to layouts of type left or right. A value of
max. 0.25 should be enough.


File: ecb.info,  Node: Simulating speedbar,  Next: Integrating speedbar,  Prev: Big screens,  Up: Common use-cases

10.4 Simulating speedbar without an extra frame
===============================================

You can simulate a speedbar-like layout within ONE frame by doing the
following:

  1. Customize `ecb-layout-name' to layout name "left9", "left12", "left13"
     or "left14" dependent to what you like.

  2. Optional: Ensure that `ecb-compile-window-height' is nil.

  3. Optional: Adjust the `ecb-windows-width'.

  4. Optional: Customize `ecb-toggle-layout-sequence' and toggle very fast
     between several layouts by `ecb-toggle-layout'. See the doc-strings!

  5. Optional: Customize `ecb-show-sources-in-directories-buffer' to not nil
     if the chosen layout (see 1. and 4.) contains a directories-tree-buffer.

  6. Save your changes.

But not only simulating speedbar is possible but also full integrating it
into the ECB and the ECB-frame, *Note Integrating speedbar::.


File: ecb.info,  Node: Integrating speedbar,  Next: Large directories,  Prev: Simulating speedbar,  Up: Common use-cases

10.5 Integrating speedbar in the ECB-frame
==========================================

It is very easy to integrate speedbar into ECB. There are two different ways
to do this:

  1. You can either use speedbar in the directories-, sources- or
     methods-window of ECB instead of the built-in directory-, sources- or
     methods-browser of ECB. This can be done via the option
     `ecb-use-speedbar-instead-native-tree-buffer'.

  2. Or you can integrate an extra speedbar-window into a layout independent
     of the existence of a directory-, sources- or methods-window. For this
     you can either use the built-in layout "left-dir-plus-speedbar" or you
     have to create your own layout interactively with the command
     `ecb-create-new-layout'. This way is not described in more details
     because there is nothing more to describe - just create your layout.

In general integrating speedbar into the ECB-frame makes sense for people...

   * ...who like the speedbar way of handling directories and source-files
     but also like the ECB-way of displaying the buffer-contents (like
     methods and variables in a source-file). This people should use the
     option `ecb-use-speedbar-instead-native-tree-buffer' and set it to `dir'.

   * ...who like the speedbar way of browsing things like directories, files,
     file-contents etc. but who dislike the extra speedbar-frame.

Note: It is not necessary to integrate speedbar if you only want parsing
sources not supported by semantic. From version 1.94 on ECB supports native
parsing and displaying of such sources (*note Non-semantic sources::)!

Regardless the group you belong, with the speedbar-integration feature of ECB
you can combine both worlds, the speedbar- and the ECB-world:

  1. Choose a layout which either contains a directories- or a sources-window
     but not both of them(1).

     Because speedbar has also display-modes for buffers and info-nodes and
     some other useful things (which can be changed by the speedbar-command
     `speedbar-change-initial-expansion-list' we recommend layouts like
     "left15" or "leftright3" for using with speedbar.

  2. Set the option `ecb-use-speedbar-instead-native-tree-buffer' to not nil.
     After this the chosen window of ECB will contain a full featured speedbar
     (the only difference to standard speedbar is not residing in an extra
     frame).

Note: If you belong to the first group of people (s.a.) a similar effect and
usability is available by setting
`ecb-use-speedbar-instead-native-tree-buffer' to nil and setting
`ecb-show-sources-in-directories-buffer' to not nil, because this combination
displays also directories and sources in one window.

So with the option `ecb-use-speedbar-instead-native-tree-buffer' you have the
choice which way of displaying and handling "things" (directories, sources,
methods...) you want (the speedbar- or the ECB-way).

During speedbar is running within ECB (i.e.
`ecb-use-speedbar-instead-native-tree-buffer' is not nil) the
speedbar-command `speedbar' is disabled and the speedbar-command
`speedbar-get-focus' switches between the speedbar-window and the
edit-window(2).

*IMPORTANT*: ECB can only integrate speedbar-versions >= 0.14beta1! If you
use lower versions of speedbar `ecb-use-speedbar-instead-native-tree-buffer'
has no effect.

---------- Footnotes ----------

(1) Only one of them is needed if you use speedbar because speedbar displays
directories and sources in one window. But if you like wasting space then you
can also use a layout with both windows...

(2) The standard behavior is switching between the speedbar-frame and the
attached frame, but this make obviously no sense during running speedbar with
ECB.


File: ecb.info,  Node: Large directories,  Next: Remote directories,  Prev: Integrating speedbar,  Up: Common use-cases

10.6 Working with large directories
===================================

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 on the speed of the net-connection and the
machine), actualizing the sources- and/or directories- buffer of ECB (if
displayed in current layout!) can slow down dramatically. If this is a
problem the contents of certain directories and also the contents of the
sources-buffer can be cached which increases the speed a lot. See the option
`ecb-cache-directory-contents'.

IMPORTANT: The full speed-advantage of this cache-mechanism is only available
if `ecb-show-sources-in-directories-buffer' is `nil', i.e. sources of a
directory are displayed in the ECB-sources-window. The reason is that only
with a sources window the tree-buffer contents for the sources can be cached
(i.e. the buffer-content of the ECB-sources-window) whereas with sources
displayed in the directories buffer only the disk-contents of a directory are
cached - which increases speed too but not so much as with sources displayed
in the extra window ECB-sources.

The cache of a directory can be only refreshed by a POWER-click (with mouse
or keyboard) onto the related directory-node in the directories-buffer of ECB
(*note Using the mouse::).

See also the option `ecb-cache-directory-contents-not'. Here are some useful
settings for both of these options:

   * Cache all directories with more than 500 entries: Set
     `ecb-cache-directory-contents' to ((".*" . 500)) and set
     `ecb-cache-directory-contents-not' to nil.

   * Cache only all directories > 200 beginning with /usr/ Set
     `ecb-cache-directory-contents' to (("^/usr/.*" . 200)) and set
     `ecb-cache-directory-contents-not' to nil.

   * Cache all directories > 500 but NOT these beginning with /usr/: Set
     `ecb-cache-directory-contents' to ((".*" . 500)) and set
     `ecb-cache-directory-contents-not' to ("^/usr/.*").

Another way for getting a faster overlook for large directories with many
source-entries is to apply an online-filter to the sources-buffer. This can
be done via the command `ecb-sources-filter' or via the popup-menu of the
sources-buffer.


File: ecb.info,  Node: Remote directories,  Next: Version-control support,  Prev: Large directories,  Up: Common use-cases

10.7 Working with remote directories
====================================

The term "remote" means directories which are remote in the sense of
TRAMP(1), ANGE-FTP(2) or EFS(3). Each of these Emacs-addons is intended to
make editing directories and files on remote machines as transparent as
possible.

10.7.1 General remarks
----------------------

ECB supports such remote directoires out of the box and completely
transparently, i.e. you can add remote directories to the option
`ecb-source-path' without any restriction. ECB will handle these directories
transparently with the appropriate tool - either TRAMP, ANGE-FTP or EFS. So
when  working with such a remote directory is possible without ECB it will be
possible too with active ECB - at least as long you are "connected"!

*Caution*: Suppose you have added a remote dir (e.g.
"user@host.at.a.server:/dir/") to `ecb-source-path' and you start ECB when
you are offline, means there can be no connection established to the remote
computer (e.g. "host.at.a.server"). Each time ECB has to process a remote
path ECB pings via the ping-program the remote host (in the example above it
would ping the host "host.at.a.server") to test if it is accessible. If not
then this path will be ignored by ECB(4). Ensure that ECB calls your
ping-program (see `ecb-ping-program') with the right options (see
`ecb-ping-options'). To avoid to many pings to the same host ECB caches the
ping result so there should be no performance decrease. But to ensure still
correct accessible-results and to avoid using outdated cache-results ECB
discards the cached value of the accessible-state of a certain host after a
customizable time-interval (please read the documentation of
`ecb-host-accessible-check-valid-time'!).

10.7.2 Excluding remote directories from time-consuming tasks
-------------------------------------------------------------

ECB performs some tasks stealthily and interruptable by the user (see the
option `ecb-stealthy-tasks-delay' for additional explanations) because these
tasks are time-consuming and could otherwise ECB block. Especially for remote
directories these special tasks can cause annoying blocks of Emacs (*note
Stealthy background tasks::).

Therefore it is probably the best to switch on each of the stealthy tasks
with the `unless-remote' which is the default activation (*note Stealthy
background tasks::). So a certain stealthy task will be swtiched on for all
local directories (and also for all mounted drives in the LAN) but not for
real remote directories used via TRAMP, ANGE-FTP or EFS.

10.7.3 Caching the contents of remote directories
-------------------------------------------------

ECB caches per default the contents of remote directories to avoid annoying
delays. The cache is done via the option `ecb-cache-directory-contents' which
contains an entry which covers the syntax of remote directories. If you do
not want this caching (which is strongly recommened) you have to remove this
entry from this option.

---------- Footnotes ----------

(1) TRAMP stands for 'Transparent Remote (file) Access, Multiple Protocol'.
This package provides remote file editing, similar to ANGE-FTP.

(2) This package attempts to make accessing files and directories using FTP
from within Emacs as simple and transparent as possible.

(3) A system for transparent file-transfer between remote hosts using the FTP
protocol within Emacs

(4) This avoids long lasting and annoying blocking of ECB when a remote-path
is not accessible: Without a ping ECB would always try to open this directory
through the appropriate library (e.g. TRAMP) and it would depend on the
timeout-mechanism of this library (e.g. TRAMP has 60 seconds) how long ECB
would be blocked. First after this timeout ECB could start working! A fast
"pre"-ping avoids this problem!


File: ecb.info,  Node: Version-control support,  Next: Using eshell,  Prev: Remote directories,  Up: Common use-cases

10.8 Supporting Version control systems
=======================================

Beginning with version 2.30 ECB supports Version-control systems (in the
following named VC-systems). This means the special tree-buffers of ECB
display files managed by a VC-system with an appropriate image-icon(1) in
front of the filename.

The following four options allow full control over this feature (see also
*Note ecb-version-control:::

`ecb-vc-enable-support'
     Enable or disable this feature.

`ecb-vc-supported-backends'
     The most important option for this feature. Allows to specify how ECB
     should test if a directory is managed by a VC-system (how to identify
     the VC-backend of a directory) and - if yes - how it should check the
     VC-state of a certain file. The former ones are called
     "identify-backend-functions" and the latter ones "check-state-functions".

`ecb-vc-directory-exclude-regexps'
     Allows excluding certain directories (on a regexp-basis) from the
     VC-support even if they are managed by a VC-system.

`ecb-vc-state-mapping'
     Defines the mapping between the state-values returned by a
     check-state-function (a function set in `ecb-vc-supported-backends' and
     used for getting the VC-state of a file, e.g. `vc-state') and the
     allowed state-values ECB can understand.

Probably the default settings will fit your needs but to get sure you should
carefully read the documentation of these options!

The following subsection give you important informations about
identify-backend-functions, check-state-functions, about working with remote
repositories.

* Menu:

* Identifying backends::        How ECB identifies the VC-backend of a dir
* Checking the state::          How ECB checks the VC-state of a file
* Remote repositories::         What you should know about this
* Refreshing the VC-state::     How to refresh when state changed outside
* Adding new backends::         Necessary steps for adding new backends
* Known VC-problems::           Currently known problems of the VC-support

---------- Footnotes ----------

(1) Of course only when Emacs is capable to display images; otherwise a
suitable ascii-icon will be displayed.


File: ecb.info,  Node: Identifying backends,  Next: Checking the state,  Prev: Version-control support,  Up: Version-control support

10.8.1 How ECB identifies the VC-backend of a dir
-------------------------------------------------

ECB tries all functions added as identify-backend-funtions to the option
`ecb-vc-supported-backends' until one of them returns not `nil' but a symbol
which identifies the backend (e.g.  `CVS'). After this check ECB stores the
result of this check (i.e. either the identified backend or the fact that the
directory is not managed by a VC-system) for that directory in a special
cache, so the identify-backend-process will be performed only once per
directory. If for a directory a VC-backend could be identified ECB stores not
only the backend itself for that directory but also the associated
check-state-function defined in `ecb-vc-supported-backends' (*note Checking
the state::).

You can add arbitrary functions to this options as long as they get one
directory-argument and return either nil or a backend-symbol. Per default ECB
offers the following functions to identify the VC-backend CVS, RCS, SCCS, Git,
Monotone or Subversion(1):

`ecb-vc-dir-managed-by-CVS DIRECTORY'
     Return `CVS' if DIRECTORY is managed by CVS. nil if not.

`ecb-vc-dir-managed-by-RCS DIRECTORY'
     Return `RCS' if DIRECTORY is managed by RCS. nil if not.

`ecb-vc-dir-managed-by-SCCS DIRECTORY'
     Return `SCCS' if DIRECTORY is managed by SCCS. nil if not.

`ecb-vc-dir-managed-by-MTN DIRECTORY'
     return `MTN' if directory is managed by Monotone. nil if not.

`ecb-vc-dir-managed-by-BZR DIRECTORY'
     return `BZR' if directory is managed by Bazaar. nil if not.

`ecb-vc-dir-managed-by-GIT DIRECTORY'
     Return `GIT' if directory is managed by Git. nil if not.  Because with
     Git only the top-most directory of a source-tree has a subdir .git this
     function tries recursively upwards if there is a .git-subdir.

`ecb-vc-dir-managed-by-SVN DIRECTORY'
     Return `SVN' if DIRECTORY is managed by Subversion. nil if not.  Returns
     always nil if the library vc-svn.el can not be found.


If ECB should support another VC-backend than CVS, RCS, SCCS, Monotone, Git or
Subversion you have to write your own identify-backend-funtion for the used
VC-backend (e.g. Clearcase)!

---------- Footnotes ----------

(1) For this the most recent version of the VC-package (incl. the libraries
vc-git.el, vc-mono.el and vc-svn.el) is needed - as contained in Emacs >= 22
and XEmacs >= 21.4.22


File: ecb.info,  Node: Checking the state,  Next: Remote repositories,  Prev: Identifying backends,  Up: Version-control support

10.8.2 How ECB checks the VC-state of a file
--------------------------------------------

After ECB has identified the VC-backend of a directory it will display the
VC-state (e.g. up-to-date, edited, needs-mergs etc...) with a suitable
image-icon in the tree-windows of the ECB-file-browser. To get this state for
a certain file ECB uses that check-state-function stored in the cache for the
directory of that file (*note Identifying backends::).

You can add any arbitrary functions as check-state-function to
`ecb-vc-supported-backends' as long as they get one filename-argument and
return a state-symbol (e.g. `up-to-date'.  ECB can understand a certain set
of state-values which are then mapped to suitable image-icons which will in
turn be displayed in front of the filename in the file-browser. Because the
values a check-state-function return can differ from that state-values ECB
understands, ECB offers an option to define a appropriate state-mapping. The
name of this option is `ecb-vc-state-mapping'.  See the documentation of this
option to get a list of all state-value ECB understands.

Per default ECB uses the function `vc-state' of the VC-package(1) to check
the state for the backends CVS, RCS, SCCS, Subversion, Git and Monotone. So
the default-value of `ecb-vc-state-mapping' contains a mapping between these
values `ecb-vc-state' can return and that state-values ECB understands.

If ECB should support other VC-backends than CVS, RCS, SCCS, Monotone, Git and
Subversion (e.g. Clearcase) you should add that new backend to the VC-package
(see the initial comments of vc.el how to do this) then ECB will automatically
support that new backend. Alternatively it may be sufficient if you write your
own check-state-function for this backend and add the needed mapping to
`ecb-vc-state-mapping' if necessary.

10.8.2.1 Getting heuristic state-values or real ones for a backend
..................................................................

The interface of Emacs' VC-package offers two different ways to get the
VC-state of a file:

   * The real, fresh and expensive approach

     VC has a function `vc-recompute-state' which always performs a real
     backend command (e.g. "cvs status" for CVS) to get a fresh and real state
     for a file. As you can imagine this operation can be very expensive and
     long lasting depending on the location of the repository. But for CVS the
     CVS-backend of VC offers with the option `vc-cvs-stay-local' a way to
     tell Emacs to stay local even for the sake of getting a real state(2).

     ECB offers `ecb-vc-recompute-state' for this approach which is an alias
     for `vc-recompute-state'.

   * The heuristic approach:

     The function `vc-state' always returns a "heuristic" state which should
     be used when a fresh and real state is not necessary.  With `vc-state'
     the option `vc-cvs-stay-local' will never take effect.

     ECB offers `ecb-vc-state' for this approach - see below for the
     difference between `vc-state' and `ecb-vc-state'.

Example CVS:

VC/CVS actually does it this way (regardless if ECB is active or not): When
you visit a file, it always uses just the heuristic to get the state
(comparing file times), regardless of the setting of `vc-cvs-stay-local'.
This is because the "fresh-but-slow" state is determined by calling "cvs
status" on the file, and this was deemed unacceptably slow if done at
visiting time under any conditions.

The state is updated by calling `vc-recompute-state' prior to
`vc-next-action' (C-x v v) which either checks a file in or out.  IF
`vc-cvs-stay-local' is nil, then this does in fact call "cvs status" to get
the "fresh-but-slow-state", but if `vc-cvs-stay-local' is t, then it just
compares the file times again.

But under certain conditions (e.g. if called for files not already visited or
for files their VC-state has been changed from outside Emacs, e.g. by
checking in the file via command line) `vc-state' does not compute a new
heuristic state but returns a cached one (cached by the VC-package itself not
by ECB) which does not reflect the current VC-state. Example: if you have
edited a file within Emacs and then checked in from outside Emacs `vc-state'
returns a wrong state until you call `revert-buffer' for this file. Therefore
ECB offers the check-state-function `ecb-vc-state' which does the same as
`vc-state' but it clears the internal caches of the VC-package for that file
before calling `vc-state'.

The bottom line for you is this: If you use `ecb-vc-state' in
`ecb-vc-supported-backends' to get the version control state, then you get
the same policy that VC uses and you get always a "correct" heuristic state
(as correct as possible a heuristic state can be). There should no harm if
you use `ecb-vc-recompute-state' (which is an alias for `vc-recompute-state')
as a replacement function if you want to get fresh and real state-values, but
then (a) you must make sure to set `vc-cvs-stay-local' to nil, and (b)
fetching the state over the network under all conditions was deemed
unacceptably slow in VC.

---------- Footnotes ----------

(1) The VC-package of Emacs offers a standardised and uniform interface for
several backends; per default CVS, RCS, SCCS, Subversion, Git and Monotone
are supported by the VC-package.

(2) For other backends you have to check the VC-manual if there is equivalent
option


File: ecb.info,  Node: Remote repositories,  Next: Refreshing the VC-state,  Prev: Checking the state,  Up: Version-control support

10.8.3 Important informations about remote repositories
-------------------------------------------------------

At least CVS can be used in a mode called "Client/Server" which means the
root repository is located on a remote machine. We call a repository which
can not being mounted by the client-machine (which contains the working
directory) a "remote repository". In most cases getting the fresh and real
VC-state for such repositories will be unacceptable slow or often users will
work offline means with no connection available to the remote host. To avoid
problems like these ECB offers first an option
`ecb-vc-directory-exclude-regexps' to exclude such directories with a remote
repository from the VC-support of ECB and secondary the
identify-backend-funtion `ecb-vc-dir-managed-by-CVS' behaves smart with that
respect (*note Identifying backends::). See also
`ecb-vc-xemacs-exclude-remote-cvs-repository'!

10.8.3.1 Remote paths and the VC-support of ECB
...............................................

ECB supports working with remote directories like TRAMP- or EFS-directories
(*note Remote directories::). Do not confuse remote directories with remote
repositories. A local directory located on your disk and set in
`ecb-source-path' can have a remote repository if managed by a VC-system. A
remote directory means a path in the format of TRAMP, ANGE-FTP or EFS set in
`ecb-source-path'.  Its very likely that getting the VC-state of files
contained in such a remote directory would be extremly expensive and
therefore ECB would be blocked quite long even if the VC-check is performed
stealthy (*note Stealthy background tasks::).

To avoid problems with such remote directories ECB prevents per default such
directories from being processed by the VC-support of ECB. But if a user is
dying to having the VC-state being displayed in the tree-buffers ECB offers
two ways to switch on the VC-support - see the option
`ecb-vc-enable-support': This option is set per default to the value
`unless-remote' which means remote paths will not be processed but it can be
set to `t' which means process all directories regardless if remote or not.
It's strongly recommended to use `unless-remote'!


File: ecb.info,  Node: Refreshing the VC-state,  Next: Adding new backends,  Prev: Remote repositories,  Up: Version-control support

10.8.4 How to refresh ECB-state-display when changed outside
------------------------------------------------------------

If all actions concerning version controlling of a file are performed within
Emacs with commands offeres by VC then the displayed state for such a file in
the tree-buffers of ECB will be always correct - in that sense that ECB will
always display that state which the check-state-function for the file will
return. At least with GNU Emacs for the backends CVS, RCS, SCCS and
Subversion this will be true. With XEmacs only for CVS. For other backends
see *Note Adding new backends::.

But if the VC-state of a file will be changed outside of Emacs (unfortunately
PCL-CVS must be called "outside" too because PCL-CVS doesn't use the
functions of the VC-package of Emacs for checking-in or -out) then ECB can
not automatically recognize this and therefore it can not aurtomatically
update the displayed state-image-icon. You have to tell ECB for which files
in the tree-buffers the VC-state should be recomputed. This can be done via
the popup-menus of the ECB-tree-buffers - The following popup-commands are
offered in the submenu "Version Control":

ECB-directories-buffer (if sources are displayed within):
     "Recompute state for file" and "Recompute state for dir" whereas the
     latter one recomputes the VC-state for all files of that directory the
     file belongs.

ECB-sources-buffer
     "Recompute state for file" and "Recompute state for dir" whereas the
     latter one recomputes the VC-state for all files currently displayed in
     the sources-buffer.

ECB-history-buffer
     "Recompute state for file" and "Recompute state for whole history"
     whereas the latter one recomputes the VC-state for all file-entries
     currently displayed in the history-buffer.

*Caution*: The state will only recomputed right under all situations if you
use either `ecb-vc-state' or `vc-recompute-state' as check-state-function in
`ecb-vc-supported-backends' (*note Checking the state::).

Of course all these commands update the VC-state in all visible tree-buffers
the file is currently displayed (e.g. often a file is displayed in the
sources- and the history-buffer)!

For general informations about the usage of popup-menus in ECB see *Note
Using the mouse:: (subsection "The right mouse button").

In addition to these popup-commands using the POWER- rsp. Shift-click (*note
Using the mouse::) onto a directory in the directory-window of ECB refreshes
the VC-state-values of all files contained in this directory too.


File: ecb.info,  Node: Adding new backends,  Next: Known VC-problems,  Prev: Refreshing the VC-state,  Up: Version-control support

10.8.5 Necessary steps and informations for adding new backends
---------------------------------------------------------------

There are mainly three necessary steps for adding a new(1) backend BE which
should be supported by ECB:

  1. Adding an identify-backend-function to `ecb-vc-supported-backends' ECB
     needs a function how to identify the new backend BE for a certain
     directory. If there exists already a library (other then VC) supporting
     this backend then this library propably contains already such a function
     which can be used or can be used at least with a small elisp-wrapper. If
     no elisp-library for backend BE exists then you have probably write the
     full identify-backend-function for your self. This function has to be
     added to `ecb-vc-supported-backends'.

  2. Adding an check-state-function to `ecb-vc-supported-backends' Associated
     to the new identify-backend-function mentioned in step 1 a new
     check-state-function is needed which can be used by ECB to get the
     VC-state for a file. See *Note Checking the state:: for a description
     about the needed interface of such a function. In combinatio with the
     identify-backend-function from step 1 this function has to be added to
     `ecb-vc-supported-backends'.

  3. Enabling automatic state-update after checkin/out

     This step is not essential if you do not need the displayed VC-state
     automatically updated after a checkin/out of a file via the commands
     available for backend BE (e.g. clearcase.el offers for the backend
     Clearcase elisp-commands to checkin and checkout a file which then
     should also update the displayed state in the ECB-tree-buffers. All you
     need is a way to tell these commands that they should clear the
     ECB-VC-cache for the file and then restart the ECB-VC-check-mechanism.
     This should be done after these commands have finished their original
     job.

     ECB enables this per default for all backends supported by the
     VC-package with the following code. Maybe this is a good starting point.

        (defvar ecb-checkedin-file nil
          "Stored the filename of the most recent checked-in file. Is only set by the
        after-advice of `vc-checkin' and `ecb-vc-checkin-hook' \(resets it to nil).
        Evaluated only by `ecb-vc-checkin-hook'.

        This is the communication-channel between `vc-checkin' and
        `ecb-vc-checkin-hook' so this hook-function gets the filename of the
        checked-in file.")

        (defadvice vc-checkin (after ecb)
          "Simply stores the filename of the checked-in file in `ecb-checkedin-file'
        so it is available in the `vc-checkin-hook'."
          (setq ecb-checkedin-file (ecb-fix-filename (ad-get-arg 0))))

        (defun ecb-vc-checkin-hook ()
          "Ensures that the ECB-cache is reset and the entry for the most recent
        checkedin file is cleared. Uses `ecb-checkedin-file' as last checked-in file."
          (when ecb-checkedin-file
            (ecb-vc-cache-remove ecb-checkedin-file)
            (ecb-vc-reset-vc-stealthy-checks)
            (setq ecb-checkedin-file nil)))


---------- Footnotes ----------

(1) i.e.  not already supported by the VC-package because all these backends
are automatically supported by ECB too!


File: ecb.info,  Node: Known VC-problems,  Prev: Adding new backends,  Up: Version-control support

10.8.6 Currently known problems with the VC-support
---------------------------------------------------

There are no reported problems concerning the Version Control support of ECB.


File: ecb.info,  Node: Using eshell,  Next: Grepping directories,  Prev: Version-control support,  Up: Common use-cases

10.9 Optimal using of eshell in ECB
===================================

ECB offers a very smart integration of the "eshell" if you are using a
compile window (*note Temp- and compile-buffers::)(1)

Here is a short summary of provided features:

   * Ability to jump to the eshell buffer within the compilation window by
     simply call `eshell' (bound to `C-c . e'). If the eshell isn't running
     it will be started.

   * Expands the compilation window when you run commands. So for example it
     allows you to view the eshell in minimized mode and then when you run
     "ls" the window automatically expands (but always depending on the
     output of the command you run).

   * Synchronizes the current directory of the eshell with the current buffer
     in the current active edit-window of ECB.

   * Provides smart window layout of the eshell buffer. This makes sure that
     the eshell is taking up the exact amount of space and that nothing is
     hidden.

Here comes a detailed explanation of these features and how to use it (all
these features are only available if you use a persistent compile-window,
i.e. if `ecb-compile-window-height' is not nil):

You do not have to learn a new command for the eshell-start - just call
`eshell' (for convenience also bound to `C-c . e') and the eshell will
displayed in the compile-window of ECB (if eshell is not already alive then
it will be started automatically).

ECB tries to display the contents of the eshell-buffer as best as possible,
means ECB can autom. enlarge and shrink the compile-window so the contents of
the eshell are fitting the window. See option
`ecb-eshell-enlarge-when-eshell' and
`ecb-eshell-fit-window-to-command-output'. Normally this is done autom. but
you can also you the standard compile-window enlarging-command of ECB:
`ecb-toggle-compile-window-height'.

ECB tries also to recenter the eshell-buffer as best as possible.  Normally
this is done autom. but you can do it on demand with the command
`ecb-eshell-recenter'.

If option `ecb-eshell-buffer-sync' is true then ECB always synchronizes the
command prompt of eshell with the directory of current source-buffer of the
current active edit-window.

With the option `ecb-eshell-auto-activate' you can start eshell autom. in the
compile-window when ECB is started but of course if a compile-window exists.

---------- Footnotes ----------

(1) Of course you can use eshell also if there is no compile-window. Then it
is just displayed in the edit-area and there is no special integration.


File: ecb.info,  Node: Grepping directories,  Next: Working with JDEE,  Prev: Using eshell,  Up: Common use-cases

10.10 Grepping directories with ECB
===================================

ECB offers in the popup-menus in the directories- and sources-tree-buffer
commands for easy (recursive) grepping the current directory under point
(directory-buffer) rsp. the current-directory (sources-buffer). In every case
just the function of the options `ecb-grep-function' rsp.
`ecb-grep-find-function' is called and the `default-directory' is tempor. set
to the chosen directory so the grep will performed in this directory
regardless of the `default-directory' of current buffer in the edit-window.

Other smart things beyond that are not done by ECB, see also
`ecb-grep-function'!

So, how to exclude some subdirectories or files from the grep?

Basically this has to be done with the "-prune" option of the find-utility:
If the standard-grep facility of Emacs is used then this is not easy but with
the command `igrep.el' there is a convenient way to exclude things like CVS-
or RCS-directories from the find-call: See the variable
`igrep-find-prune-clause' of the library `igrep.el'.


File: ecb.info,  Node: Working with JDEE,  Next: Compile-window on demand,  Prev: Grepping directories,  Up: Common use-cases

10.11 Working best with ECB and JDEE
====================================

ECB is completely language independent, i.e. it works with any language
supported by semantic (e.g. C, C++, Java, Elisp etc.).

But there are some special integrations for the great
Java-Development-Environment JDEE:

   * Displaying contents of class under point

     With the command `ecb-jde-display-class-at-point' you can display the
     contents of the class which contains the definition of the "thing" at
     point (which can be a method, variable etc.).

   * Creating new source-files

     The popup-menus in the directories- and the sources-buffer offer a
     command "Create Source" which allows easy creating new java-sources by
     calling the command `jde-gen-class-buffer'.

   * Adding user-extensions to the popup-menus

     The options `ecb-directories-menu-user-extension' and
     `ecb-sources-menu-user-extension'(1) allow adding often used
     JDEE-commands to the popup-menus of the directories- or sources-buffer.
     One example is to add building the project of current directory. Here is
     a function which could be added to `ecb-directories-menu-user-extension':

        (defun ecb-dir-popup-jde-build (node)
          "Build project in directory."
          (let ((project-file
        	 (expand-file-name jde-ant-buildfile (tree-node-get-data node))))
            (jde-ant-build project-file "build")))

     Of course you can add entries to the option
     `ecb-methods-menu-user-extension' and `ecb-methods-menu-user-extension'
     too.


---------- Footnotes ----------

(1) If you need a dynamic way of menu-extension then you should have a look
at the options `ecb-directories-menu-user-extension-function' and
`ecb-sources-menu-user-extension-function'.


File: ecb.info,  Node: Compile-window on demand,  Next: Non-semantic sources,  Prev: Working with JDEE,  Up: Common use-cases

10.12 Displaying the compile-window on demand
=============================================

If you like displaying all output of compile/grep/etc. an all temp-buffers
like *Help*-buffers in an extra compile-window (*note Temp- and
compile-buffers::) but you dislike wasting the space of this compile-window
if you are just editing then you can get a compile-window "on demand". Just
do the following:

  1. Customize `ecb-compile-window-height' to not nil and save it for future
     sessions. This gives you an extra compile-window at the bottom.

  2. Add the following to your .emacs:

        (add-hook 'ecb-activate-hook
                  (lambda ()
                    (let ((compwin-buffer (ecb-get-compile-window-buffer)))
                    (if (not (and compwin-buffer
                                  (ecb-compilation-buffer-p compwin-buffer)))
                        (ecb-toggle-compile-window -1)))))

     This hides the extra compile-window directly after the start of ECB
     because there is no need for a compile-window at this moment. But the
     hiding will not be done if there is a compile-window and if a
     "compile-buffer" in the sense of `ecb-compilation-buffer-p' is displayed
     in this compile-window. Without this additional check the compile-window
     would always be hidden after the ECB-start even when ECB is reactivated
     after a deactivation by the window-manager-support of ECB (*note
     Window-managers and ECB::); but in these cases we want to preserve the
     state before deactivation as good as possible (see also option
     `ecb-split-edit-window-after-start').


This is all you have to do. Now if you run `compile' (or `grep' or other
compile-modes) or display temp-buffers like *Help*-buffers then ECB autom.
displays the compile-window at the bottom and display the output there.

If you have finished with using the compile- or temp-output (e.g.  fixing
errors) then you can throw away the compile-window just by
`ecb-toggle-compile-window' - ECB will reactivate it autom.  before next
compilation or help-buffer-display.!


File: ecb.info,  Node: Non-semantic sources,  Next: Hide-show,  Prev: Compile-window on demand,  Up: Common use-cases

10.13 Parsing and displaying non-semantic sources
=================================================

ECB is mostly designed to display parsing information for files supported by
semantic. But beginning with version 1.94 it also supports other parsing
engines like imenu and etags, so also files not supported by semantic but by
imenu/etags can be displayed in the Method-buffer of ECB. See *Note
Definition of semantic- and non-semantic-sources:: for a description of
"semantic-sources" and "non-semantic-sources".

If support of non-semantic-sources is enabled then ECB will display the
contents of all sources which can be displayed by speedbar too.  This comes
from the fact that ECB uses speedbar-logic to parse sources with imenu or
etags.

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.

This section describes all important aspects about parsing and displaying
file-contents of file-types not supported by semantic but by imenu and/or
etags.

10.13.1 Enabling parsing and displaying of non-semantic-sources
---------------------------------------------------------------

Enabling is simply done with the option `ecb-process-non-semantic-files'.

ECB offers an option `ecb-non-semantic-parsing-function' to specify on a
major-mode basis which parsing-method should be used: imenu or etags.
Normally there should be no need to change this option but read the
documentation of this option (*note ecb-non-semantic::) for further details.

IMPORTANT:

   * If imenu-parsing should be used then the option
     `speedbar-use-imenu-flag' must be set to not `nil'!

   * If some non-semantic-sources are not parsed (i.e. there is an empty
     Methods-buffer) and you think that they should then maybe they are
     neither supported by imenu nor by etags or you have to check the options
     `ecb-non-semantic-parsing-function' and
     `speedbar-dynamic-tags-function-list' and - especially for etags -
     `speedbar-fetch-etags-parse-list', `speedbar-fetch-etags-arguments' and
     `speedbar-fetch-etags-command'.

   * Even with support for semantic-, imenu- and etags-parsing there will
     remain some file-types rsp. `major-modes' which are not parse-able,
     neither by semantic, imenu nor etags. This is no problem because these
     files simply have an empty Methods-buffer. 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 the option `ecb-non-semantic-exclude-modes' and then it
     will be excluded from being tried to parsed and this (annoying) message
     will not occur.

10.13.2 Automatic rescanning/reparsing of non-semantic-sources
--------------------------------------------------------------

In contrast to semantic (see `global-semantic-idle-scheduler-mode') there is
no built-in mechanism for autom. reparsing non-semantic-sources and then
updating the contents of the Methods-buffer.

For non-semantic-sources you have always at least to call
`ecb-rebuild-methods-buffer' (bound to `C-c . r') or saving the source-file
(if `ecb-auto-update-methods-after-save' is true) to update the
Method-buffer(1).

Depending on the parsing-mechanism the following options have to be switched
on so ECB can rebuild the methods-buffer for non-semantic-sources:

   * imenu:

     The imenu-option `imenu-auto-rescan' must be enabled and
     `imenu-auto-rescan-maxout' has to be set big enough to auto-parse big
     files too! But this results not directly in an autom. updated
     Method-buffer. This is first done after calling the command
     `ecb-rebuild-methods-buffer' or saving the source-file (if
     `ecb-auto-update-methods-after-save' is true).

   * etags:

     Only if `ecb-auto-save-before-etags-methods-rebuild' is switched on the
     command `ecb-rebuild-methods-buffer' rebuilds the method-buffer with
     current source-contents. See description of this option for an
     explanation.

Tip: If you want to program your own real. automatic rescan/reparse/rebuild
mechanism for non-semantic-sources you can do:

Adding to `after-change-functions' a function F which either runs itself
`ecb-rebuild-methods-buffer-for-non-semantic' or which adds only another
function FF to an idle-timer and the function FF runs
`ecb-rebuild-methods-buffer-for-non-semantic'. The latter approach has the
advantage that the reparse/rebuild is not performed immediately after every
change but first after Emacs is idle for a senseful interval (e.g. 4 seconds)
after last change. Of course the function FF has to cancel its own idle-timer
at the end, so the next idle-timer is first started again after the next
change (i.e. by function F which is still contained in
`after-change-functions'.

10.13.3 Customizing the display of the tags
-------------------------------------------

For non-semantic-sources ECB uses does no special organizing of tags in
groups and sub-tags but it completely uses the tag-hierarchy the imenu- and
etags-parsers of speedbar return. So the displayed tag hierarchy can only be
customized with some options speedbar offers for this:

`speedbar-tag-hierarchy-method', `speedbar-tag-group-name-minimum-length',
`speedbar-tag-split-minimum-length' and
`speedbar-tag-regroup-maximum-length'. See the speedbar documentation for
details about these options.

With the option `ecb-method-non-semantic-face' you can define the face used
for displaying the tags in the Method-buffer for non-semantic-sources.

`ecb-non-semantic-methods-initial-expand' can be useful too.

---------- Footnotes ----------

(1) Maybe future versions of ECB (> 1.94) will offer an autom. mechanism for
this.


File: ecb.info,  Node: Hide-show,  Next: Window-managers and ECB,  Prev: Non-semantic sources,  Up: Common use-cases

10.14 Using hide-show from the methods-buffer-menu
==================================================

The popup-menu of the Methods-buffer offer two entries for either hiding or
showing the block which is related to the selected tag (that tag for which
the popup-menu was opened):

   * "Jump to tag and hide block": Jumps to the tag and calls `hs-hide-block'
     from the hideshow-library which is shipped with (X)Emacs. After that the
     block is hidden, i.e. only the header-line of that tag (method, variable
     etc.) is visible, the rest is hidden behind the "...".

   * "Jump to tag and show block": Jumps to the tag and calls
     `hs-show-block'. This shows the related hidden block if the block was
     hidden via `hs-hide-block' or the menu-entry "Jump to tag and hide
     block" (s.a.).

For this feature the library `hideshow.el' is used which should normally
being included in the (X)Emacs-distribution. If this library is not loaded
into Emacs, ECB does this automatically before the first call to one of these
menu-entries.

IMPORTANT: If in some `major-mode' hiding and showing does not work as you
expect it to work then you must probably add an entry for this `major-mode'
to the hideshow-variable `hs-special-modes-alist'. See the documentation of
this variable for further details. One example of such a `major-mode' is
`jde-mode' of the Java Development Environment JDEE; just add an entry for it
like the already contained entries for `c++-mode' or `java-mode' and hiding
and showing will work for you with JDEE too.


File: ecb.info,  Node: Window-managers and ECB,  Next: Virtual folders in History,  Prev: Hide-show,  Up: Common use-cases

10.15 Support of several Emacs-window-managers
==============================================

There are several window-managers available which offer an easy interface to
jump between different window-configurations within the same frame. A window
configuration is the layout of windows and associated buffers within a frame.
There is always at least one configuration, the current configuration. You
can create new configurations and cycle through the layouts in either
direction.  Window configurations are often named or numbered, and you can
jump to and delete named rsp. numbered configurations.

Without special support by ECB these window-managers would not work in
combination with ECB!

ECB currently supports the following managers:

   * winring.el: Written by Barry A. Warsaw <bwarsaw@python.org>, available at
     `http://www.python.org/emacs/winring'

   * escreen.el: Written by Noah Friedman <friedman@splode.com>, available at
     `http://www.splode.com/~friedman/software/emacs-lisp/#ui'

*IMPORTANT*: With one of these window-managers installed and active you can
run applications like Gnus, VM or BBDB in the same frame as ECB! Just use
different window-configurations (winring.el) or escreens (escreen.el) for ECB
and the other applications. Especially with winring.el you can give every
configuration a descriptive name like "ECB" or "Gnus"; afterwards you can
jump to a window-configuration by name!

When you go back to the ECB-window-configuration (winring.el) or the
ECB-escreen (escreen.el) with any of the special window-manager-commands then
the state of ECB will be restored exactly as you have left it when going to
another window-configuration rsp.  escreen. This includes the whole splitting
state of the edit-area and the visibilty of the ecb-windows and of the
compile-window!

The rest of this section describes how to enable the special ECB-support for
these window-managers and how to use them.

10.15.1 Enabling of the support
-------------------------------

Every support must be enabled explicitly:
   * winring: Call `ecb-winman-winring-enable-support'. This *MUST* be done
     *BEFORE* the first call to any winring-command, so also before calling
     `winring-initialize'!

   * escreen: Call `ecb-winman-escreen-enable-support'. This *MUST* be done
     *BEFORE* the first call to any escreen-command, so also before calling
     `escreen-install'!

If a window-manager-support should be enabled autom. after Emacs-start just
put the following into your `.emacs':

   (ecb-winman-winring-enable-support)
   (winring-initialize)

   ;; or - if you like escreen more

   (ecb-winman-escreen-enable-support)
   (escreen-install)

10.15.2 Usage of a window-manager in combination with ECB
---------------------------------------------------------

After enabling the support of one of the supported window-managers just go on
as described in the commentary or introduction of the respective
library-file(s) of the window-manager. Here is a short description:

   * winring: First you have to define how to identify the
     ECB-window-configuration, i.e. the configuration with activated ECB.
     This done with the option `ecb-winman-winring-name'. There is always
     only one window-configurations with name `ecb-winman-winring-name'!

     Then run `winring-initialize'. If ECB is active then the resulting
     window-configuration is the ECB-window-configuration.  Otherwise you can
     create the ECB-window-configuration when you first time call
     `winring-new-configuration' with name equal to
     `ecb-winman-winring-name'. In general you can run all commands of the
     winring-library. If you jump to the ECB-window-configuration then ECB
     will be autom. activated and if you leave the ECB-window-configuration
     then ECB will autom. deactivated.

   * escreen: First you have to define how to identify the ECB-escreen i.e.
     that escreen with activated ECB. This done with the option
     `ecb-winman-escreen-number'. There is always only one escreen with
     number `ecb-winman-escreen-number'!

     Then run `escreen-install' (deactivates ECB if currently running). After
     that you can call `escreen-create-screen' and `escreen-goto-screen'(1).
     These commands autom. activate ECB if creating or selecting the escreen
     with number `ecb-escreen-number' (default = 1) and autom. deactivate ECB
     if leaving the ECB-escreen.

10.15.3 Disabling the support
-----------------------------

There is normally no need to do this but nevertheless it can be done by
`ecb-winman-escreen-disable-support' rsp.
`ecb-winman-winring-disable-support'.

---------- Footnotes ----------

(1) And of course all other `escreen-goto-*' commands!


File: ecb.info,  Node: Virtual folders in History,  Prev: Window-managers and ECB,  Up: Common use-cases

10.16 Something like virtual folders with the ECB-history
=========================================================

For example, there is a large project with a huge number of files, and there
are various tasks in this project (e.g. several different bug-fixing tasks).
So it could be convenient to group buffers according to various tasks, or with
other words: something like virtual folders for the buffers. It can be
fulfiled through using indirect buffers.

See the following example:

   task_1-aaa.pl
   task_1-bbb.c
   task_1-ccc.sh
   task_2-aaa.pl
   task_2-eee.c
   task_2-ccc.sh
   task_3-xxx.java
   task_3-ccc.sh

This means create indirect buffers(1) with a name-part which can be used for
grouping together buffers with same name-part (here e.g. task_1- ...
task_3-). In the example above you would create three indirect buffers for the
filebuffer ccc.sh because this source is needed in all three tasks, two
indirect buffers for aaa.pl because it is needed in the task-1 and task-2 and
so on for the rest of the buffers. Make all this indirect buffers with the
command `clone-indirect-buffer'(2), which creates real clones means the
indirect buffers have the same major-mode etc. as the base-buffer (see the
manual of Emas).

Now remember to the option `ecb-history-make-buckets' which allows a.o.  to
define a list of regular expressions to bucketize the buffers of the history.
Use this to make one bucket for each task. So in our example a value

   ("^task_1-.+" "^task_2-.+" "^task_3-.+")

for `ecb-history-make-buckets' would satiesfy our needs.

This option allows to define several criterias for building buckets in the
history-buffer all the history entries are sorted in (e.g. by major-mode,
directory, file-extension or regular expressions).

After that the history-window would display something like the following:

   [-] [^task_1-.+]
    |  task_1-aaa.pl
    |  task_1-bbb.c
    `- task_1-ccc.sh
   [-] [^task_2-.+]
    |  task_2-aaa.pl
    |  task_2-eee.c
    `- task_2-ccc.sh
   [-] [^task_3-.+]
    |  task_3-xxx.java
    `- task_3-ccc.sh

Hopefully this example could give an impression how the combination of usage
of indirect buffers and bucketizing the history-window can be used for using
one sources for different sake and grouping together what belongs together.

---------- Footnotes ----------

(1) Remember the most important feature of indirect buffers: Changes made in
one of them will immediately take effect in all others with the same
base-buffer

(2) Currently only available with GNU Emacs


File: ecb.info,  Node: Elisp programming,  Next: Conflicts and bugs,  Prev: Common use-cases,  Up: Top

11 Entry points for Elisp programmers
*************************************

This chapter describes how ECB can be used/programmed/driven by an
Elisp-program. This contains:

* Menu:

* List of variables::           Which variables an Elisp-program can use
* List of hooks::               All available hooks
* tree-buffer::                 Full description of the tree-buffer-library
* Adviced functions::           How to deal with the adviced functions
* The layout-engine::           Programming new layouts and special windows


File: ecb.info,  Node: List of variables,  Next: List of hooks,  Prev: Elisp programming,  Up: Elisp programming

11.1 Variables for Elisp-programs
=================================

Variables an Elisp-program can use beyond those ones mentioned in *Note The
layout-engine:::

   * `ecb-source-path-functions'

Look at the documentation of these variables to get a description.


File: ecb.info,  Node: List of hooks,  Next: tree-buffer,  Prev: List of variables,  Up: Elisp programming

11.2 Available hooks of ECB
===========================

The following hooks are available:

   * `ecb-activate-before-new-frame-created-hook'

   * `ecb-activate-before-layout-draw-hook'

   * `ecb-activate-hook'

   * `ecb-after-directory-change-hook'

   * `ecb-before-activate-hook'

   * `ecb-before-deactivate-hook'

   * `ecb-common-tree-buffer-after-create-hook'

   * `ecb-basic-buffer-sync-hook'

   * `ecb-analyse-buffer-sync-hook'

   * `ecb-symboldef-buffer-sync-hook'

   * `ecb-speedbar-buffer-sync-hook'

   * `ecb-eshell-buffer-sync-hook'

   * `ecb-deactivate-hook'

   * `ecb-directories-buffer-after-create-hook'

   * `ecb-hide-ecb-windows-after-hook'

   * `ecb-hide-ecb-windows-before-hook'

   * `ecb-history-buffer-after-create-hook'

   * `ecb-methods-buffer-after-create-hook'

   * `ecb-redraw-layout-after-hook'

   * `ecb-redraw-layout-before-hook'

   * `ecb-show-ecb-windows-after-hook'

   * `ecb-show-ecb-windows-before-hook'

   * `ecb-sources-buffer-after-create-hook'

Look at the documentation of these hooks to get a detailed description.


File: ecb.info,  Node: tree-buffer,  Next: Adviced functions,  Prev: List of hooks,  Up: Elisp programming

11.3 The library tree-buffer.el
===============================

The library tree-buffer.el is an ECB-independent library written completely
in emacs lisp and can be used also by other applications than ECB. But the
main purpose of tree-buffer.el is to offer a small but powerful API to create
new tree-buffers for ECB, add new tree-nodes to a tree-buffer and thus use
such a tree-buffer to display arbitrary information structured by a tree.

This chapter is for emacs-lisp-programmers and describes how to create a new
tree-buffer, how to add new tree-nodes to a tree-buffer (includes removing
and updating already existing tree-nodes) and how to use the offered
tree-buffer- and tree-node-APIs.

* Menu:

* Introduction::                General description of tree-buffers
* A new tree-buffer::           How to create a new tree-buffer
* A new tree-node::             How to add new tree-nodes to a tree-buffer
* Updating a tree-buffer::      How to update a tree-buffer after changes
* Tree-buffer keybindings::     Default and customizable keybindings
* The tree-buffer-API::         All functions for tree-buffers and -nodes
* Do not with tree-buffer::     Things which are strictly forbidden
* Tree-buffer How to::          Dealing with special situations


File: ecb.info,  Node: Introduction,  Next: A new tree-buffer,  Prev: tree-buffer,  Up: tree-buffer

11.3.1 General description of tree-buffers
------------------------------------------

This subchapter is a general introduction in the main concepts of a
tree-buffer.

11.3.1.1 What is a tree-buffer?
...............................

A "tree-buffer" is meant to display certain informations (e.g. a
directory-tree) in a tree-structure consisting of "tree-nodes".  Every line
in a tree-buffer displays exactly one tree-node. Each node has exactly one
parent-node and can have any arbitrary number of "children"-nodes. If a
tree-node has no children then it is called a "leaf". A tree-node contains
several "slots" wheras the most important ones are the "name",
"displayed-name" and "data". See *Note A new tree-node:: for a detailed
explanation.

The difference between a natural tree like a fir and a tree-buffer is that
the root(-node) of a tree-buffer is not visible but only its children. In the
example below the nodes parent-node-1 and parent-node-2 are the children of
the invisible root-node. Each tree-buffer has exactly one root-node which is
created automatically by `tree-buffer-create'.

If a tree-node contains at least one child it is displayed with a special
expand/collapse-symbol (see the example below). This symbol allows expanding
(rsp. collapsing) the tree-node wheras expanding means to display the
children-nodes and collapsing means to hide the childrens of a tree-node.

Here is an example of a tree-buffer:

   <root-node>  ------------------------[root-node (invisible)]
       [+] <parent-node-1>  -------.
       [-] <parent-node-2>  -------|
           [-] <expanded>  --------|
               <leaf-node-1>  -----|
               <leaf-node-2>  -----|-----[tree-nodes]
               <leaf-node-3>  -----|
               <leaf-node-4>  -----|
           [+] <collapsed>  -------ﾴ
            |
            `-----------------[expand/collapse-symbol]

In most cases an action is triggered when clicking with the mouse onto a
tree-node(1) (e.g. clicking onto "leaf-node-1" or "parent-node-1" in the
example above). Which action is triggered by which key depends on what you
specify at creation-time of the tree-buffer - see *Note A new tree-buffer::
for details.

The creation-interface of a tree-buffer allows defining special popup-menus
when clicking with the right mouse-button (of course also possible via
keyboard, see *Note Tree-buffer keybindings::) onto a tree-node (e.g. some
senseful actions possible for directory-nodes like grepping this directory or
performing version-control actions for this directory or something else).

11.3.1.2 General recipe for a tree-buffer
.........................................

The following sequence of tasks is the general recipe for a tree-buffer
beginning from creation and ending with the display.

  1. Create the tree-buffer Creating a new tree-buffer has to be done with
     `tree-buffer-create' for non ECB-tree-buffers and with the macro
     `defecb-tree-buffer-creator' when the tree-buffer should be used as an
     ECB-tree-buffer, so it is an ECB-window. See *Note A new tree-buffer::
     for all details.

  2. Add tree-nodes to the tree-buffer Adding nodes to the new tree-buffer
     (means make the new tree-buffer the current buffer and call
     `tree-node-new' for a new tree-node (note that a root-node for this
     tree-buffer has been autom. created by `tree-buffer-create'!). The first
     tree-node you add to a tree-buffer must have always the root-node
     (avaliable via `tree-buffer-get-root') as parent-node. The next nodes
     can have either one of the fromerly added nodes or the root-node too. All
     tree-nodes haveing the root-node as parent will be displayed at the
     toplevel of the tree-buffer. See *Note A new tree-node:: for all details.

  3. Display the tree-buffer with current nodes and state When you are
     finished building up the tree-node-structure call `tree-buffer-update'
     to display the current tree-structure (again after making the
     tree-buffer the current-buffer). See *Note Updating a tree-buffer:: for
     all details.

*IMPORTANT*: First a call of `tree-buffer-update' updates the *display* of a
tree-buffer, means shows all the tree-nodes in an emacs-buffer! Neither
creating a tree-buffer nor adding tree-nodes display anything; this just
builds the internal tree-structure.

*IMPORTANT*: See *Note Programming special windows:: for details about
programming ECB-windows (special windows) regardless if they were build as
tree or not. There you can find a.o. how to automatically synchronizing a
special window with the current edit-buffer.

---------- Footnotes ----------

(1) Of course using the keyboard is also possible, see *Note Tree-buffer
keybindings::.


File: ecb.info,  Node: A new tree-buffer,  Next: A new tree-node,  Prev: Introduction,  Up: tree-buffer

11.3.2 How to create a new tree-buffer
--------------------------------------

The creator-function for a new tree-buffer depends on the fact if the new
tree-buffer should be used as an ECB-window or not. For a new ECB-window the
macro `defecb-tree-buffer-creator' has to be used, otherwise the function
`tree-buffer-create'. In the end both methods use `tree-buffer-create'
because the BODY-argument of `defecb-tree-buffer-creator' must contain a call
to this function!.

This section describes all arguments of `tree-buffer-create'.

Except the first argument NAME all arguments are key-arguments of the form
:arg-name arg-value, so for example a call looks like

   (tree-buffer-create <buffer-name> :frame <frame-object> ...).

These key-arguments (all except the first argument `NAME') can be arranged in
any arbitrary order but all of them are not-optional! The key-arg-name is
always a : followed by the lowercase version of the mentioned argument below
(e.g. `FRAME' -> :frame, `MOUSE-ACTION-TRIGGER' -> :mouse-action-trigger).

Here is a description of the arguments of `tree-buffer-create' - also
available as docstring for this function (via `C-h f'). The description below
contains also some examples for complex-arguments!

``NAME''
     Buffername of the new tree-buffer.

`FRAME'
     Frame in which the tree-buffer is displayed and valid. All key-bindings
     and interactive functions of the tree-buffer work only if called in
     FRAME otherwise nothing is done!

`MOUSE-ACTION-TRIGGER'
     When a mouse-action is triggered. Allowed values: `button-release' and
     `button-press'.

`IS-CLICK-VALID-FN'
     `tree-buffer-create' rebinds `mouse-1', `mouse-2', `RET' (and `TAB') and
     also in combination with shift and control (not with `TAB').
     IS-CLICK-VALID-FN is called first if a node or an expand-symbol is
     clicked. This function is called with five arguments:

        - mouse-button: The clicked mouse-button or RET or TAB (0 = RET or
          TAB, 1 = mouse-1, 2 = mouse 2)

        - shift-pressed: Non nil if the SHIFT-key was pressed during
          mouse-click or RET.

        - control-pressed: Non nil if the CONTROL-key was pressed during
          mouse-click or RET.

        - meta-pressed: Non nil if the META-key was pressed during
          mouse-click or RET.

        - tree-buffer-name: The buffer-name of the tree-buffer where the node
          has been clicked.

     The function must return not nil iff exactly this click/hit is accepted.
     If the function returns nil then really nothing is done by the
     tree-buffer after this click/hit!

     Here is an example (call `C-h f' to see what it does) for this
     callback-function:

        (defun ecb-interpret-mouse-click (mouse-button
                                          shift-pressed
                                          control-pressed
                                          meta-pressed
                                          tree-buffer-name)
          (if (eq mouse-button 0)
              (list (if control-pressed 2 1) shift-pressed meta-pressed
                    'keyboard)
            (if (and (not (eq mouse-button 1)) (not (eq mouse-button 2)))
        	nil
              (case ecb-primary-secondary-mouse-buttons
                (mouse-1--mouse-2
                 (if control-pressed
                     nil
                   (list mouse-button shift-pressed meta-pressed 'mouse)))
                (mouse-1--C-mouse-1
                 (if (not (eq mouse-button 1))
                     nil
                   (list (if control-pressed 2 1) shift-pressed meta-pressed
                         'mouse)))
                (mouse-2--C-mouse-2
                 (if (not (eq mouse-button 2))
                     nil
                   (list (if control-pressed 2 1) shift-pressed meta-pressed
                         'mouse)))
                (otherwise nil)))))

     This example would be passed as parameter as follows:

        (tree-buffer-create "myname"
                            :is-click-valid-fn 'ecb-interpret-mouse-click
                            ...)

`NODE-SELECTED-FN'
     Function to call if a node has been selected. This function is called
     with the following parameters:

        - node: The selected node

        - mouse-button (0 = RET, 1 = mouse-1, 2 = mouse 2)

        - shift-pressed

        - control-pressed

        - meta-pressed

        - tree-buffer-name

     For the last four arguments see the description above. This function has
     to ensure that the expandable- and expanded-state of the selected node
     is correct after returning.

     Here is an example (call `C-h f' to see what it does) for this
     callback-function:

        (defun ecb-tree-buffer-node-select-callback (node
        					     mouse-button
        					     shift-pressed
        					     control-pressed
                                                     meta-pressed
        					     tree-buffer-name)
          (let* ((ecb-button-list (ecb-interpret-mouse-click mouse-button
        						     shift-pressed
        						     control-pressed
                                                             meta-pressed
        						     tree-buffer-name))
        	 (ecb-button (nth 0 ecb-button-list))
        	 (shift-mode (nth 1 ecb-button-list))
                 (meta-mode (nth 2 ecb-button-list))
                 (keyboard-p (equal (nth 3 ecb-button-list) 'keyboard))
                 (maximized-p (ecb-buffer-is-maximized-p tree-buffer-name)))
            ;; now we dispatch to the right action
            (when ecb-button-list
              (cond ((ecb-string= tree-buffer-name ecb-directories-buffer-name)
        	     (ecb-directory-clicked node ecb-button nil shift-mode
                                            meta-mode))
        	    ((ecb-string= tree-buffer-name ecb-sources-buffer-name)
        	     (ecb-source-clicked node ecb-button nil shift-mode
                                         meta-mode))
        	    ((ecb-string= tree-buffer-name ecb-history-buffer-name)
        	     (ecb-history-clicked node ecb-button nil shift-mode
                                          meta-mode))
        	    ((ecb-string= tree-buffer-name ecb-methods-buffer-name)
        	     (ecb-method-clicked node ecb-button nil shift-mode
                                         meta-mode))
        	    ((ecb-string= tree-buffer-name ecb-analyse-buffer-name)
        	     (ecb-analyse-node-clicked node ecb-button nil shift-mode
                                               meta-mode))
        	    (t nil)))))

     This example would be passed as parameter as follows:

        (tree-buffer-create "myname"
                            :node-selected-fn 'ecb-tree-buffer-node-select-callback
                            ...)

     *IMPORTANT*: This callback must not modify the slot EXPANDED of the
     passed node because this is done automatically by the
     tree-buffer-library!

`NODE-EXPANDED-FN'
     Function to call if a node is expandable, point stays onto the
     expand-symbol and node is not already expanded. This function is called
     with the following parameters:

        - node: The selected node

        - mouse-button (0 = TAB, 1 = mouse-1, 2 = mouse 2)

        - shift-pressed

        - control-pressed

        - meta-pressed

        - tree-buffer-name

     This function should add all children nodes to this node if not already
     done (if possible). This function has to ensure that the expandable- and
     expanded state of the selected node is correct after returning!

     *IMPORTANT*: This callback must not modify the slot EXPANDED of the
     passed node because this is done automatically by the
     tree-buffer-library!

`NODE-COLLAPSED-FN'
     Function to call if a node is expandable, point stays onto the
     expand-symbol and node is already expanded. This function is called with
     the following parameters:

        - node: The selected node

        - mouse-button (0 = TAB, 1 = mouse-1, 2 = mouse 2)

        - shift-pressed

        - control-pressed

        - meta-pressed

        - tree-buffer-name

     This function is only a callback to inform the owner/user of this
     tree-buffer that this node has been collapsed. This function must not
     modify the expandable- or expanded state of the selected node!

     Often a sensefull value for this parameter is the function `ignore'.

     *IMPORTANT*: This callback must not modify the slot EXPANDED of the
     passed node because this is done automatically by the
     tree-buffer-library!

`NODE-MOUSE-OVER-FN'
     Function to call when the mouse is moved over a node. This function is
     called with three arguments: NODE, WINDOW, NO-PRINT, each of them
     related to the current tree-buffer. If NO-PRINT is nil then the function
     must print the text itself in any manner. This function must always
     return the text which either is printed by the function itself or by the
     caller (if NO-PRINT is not nil). The current buffer for this function is
     the tree-buffer itself. With XEmacs this function is only called if the
     tree-buffer track-mouse mechanism is activated (see the function
     `tree-buffer-activate-follow-mouse'). With GNU Emacs >= 21 this function
     is called by the `help-echo' property added to each node.

     Here is an example (call `C-h f' to see what it does) for this
     callback-function:

        (defun ecb-mouse-over-analyse-node (node &optional window no-message
                                                 click-force)
          (let ((str (when (or click-force
                               (ecb-show-minibuffer-info
                                node window
                                (car ecb-analyse-show-node-info)))
                       (if (equal (cdr ecb-analyse-show-node-info)
                                  'full-info)
                           (ecb-analyse-gen-tag-info
                            (car (tree-node->data node)))
                         (tree-node->name node)))))
            (prog1 str
              (unless no-message
                (ecb-nolog-message str)))))

`MOUSE-HIGHLIGHT-FN'
     If nil then in this tree-buffer no node is highlighted when the mouse
     moves over it. If t then each node is highlighted when the mouse moves
     over it. If a function then it is called with the node as argument and
     if it returns not nil then the node will be highlighted when the mouse
     moves over it - otherwise no highlighting takes place.

`NODE-DATA-EQUAL-FN'
     Function used by the tree-buffer to test if the data of two tree-nodes
     are equal. The function is called with two args: The DATA-slots of the
     two tree-nodes (see *Note A new tree-node:: for details about the
     data-slots).

     Here is an example (call `C-h f' to see what it does) for this
     callback-function:

        (defun ecb-analyse-compare-node-data (left right)
          "Return not nil when LEFT and RIGHT are identical node-datas."
          (and (equal (nth 2 left) (nth 2 right))
               (ecb-compare-methods-buffer-node-data (car left)
                                                     (car right))))

     Often a suitable value for this parameter is `equal'.

`MAYBE-EMPTY-NODE-TYPES'
     Nil or a list of node-types (a node-type is an integer which must be set
     with `tree-node-new'). Nodes with one of these types are treated as
     empty if they are not expandable (i.e. they have no children) and will
     be displayed with the empty-symbol ([x]); for other nodes see next
     argument.

`LEAF-NODE-TYPES'
     Nil or a list of node-types (see above). Nodes with one of these types
     are treated as leafs and will be displayed with the leaf-symbol (*).

     Summary for MAYBE-EMPTY-NODE-TYPES and LEAF-NODE-TYPES:

        * Expandable nodes will always be displayed either with the open- or
          with the close-symbol.

        * Not-expandable nodes with a node-type contained in
          MAYBE-EMPTY-NODE-TYPES will be displayed with the empty-symbol.

        * Not-expandable nodes with a node-type contained in LEAF-NODE-TYPES
          will be displayed with the leaf-symbol.

        * All other nodes will be displayed with no symbol just with correct
          indentation.

`MENU-CREATOR'
     Nil or function which has to return nil or a list of conses, each cons
     for a known node-type of this tree-buffer (the node-type of a node is an
     integer). Example: ((0 . menu-for-type-0) (1 . menu-for-type-1)).  The
     cdr of a cons must be a menu in the same format
     `tree-buffer-create-menu' expects as argument - see the documentation of
     this function for details. This function gets two arguments: The name of
     the tree-buffer and the node for which a popup-menu should be opened.

     Here is an example for such a menu-creator-callback:

        (defconst ecb-analyse-nodedata-tag-with-pos 0)
        (defconst ecb-analyse-nodedata-tag-without-pos 1)
        (defconst ecb-analyse-nodedata-no-tag 2)

        (defconst ecb-analyse-nodetype-bucket 0)
        (defconst ecb-analyse-nodetype-context 1)
        (defconst ecb-analyse-nodetype-arguments 2)
        (defconst ecb-analyse-nodetype-completions 3)
        (defconst ecb-analyse-nodetype-localvars 4)
        (defconst ecb-analyse-nodetype-prefix 5)
        (defconst ecb-analyse-nodetype-assignee 6)
        (defconst ecb-analyse-nodetype-function 7)
        (defconst ecb-analyse-nodetype-function-arg 8)

        (defun ecb-analyse-create-menu (node)
          "Return a popup-menu suitable for NODE."
          (let* ((data (tree-node->data node))
                 (tag-p (not (equal (nth 1 data) ecb-analyse-nodedata-no-tag)))
                 (tag-with-pos-p (equal (nth 1 data)
                                        ecb-analyse-nodedata-tag-with-pos))
                 (nodetype (nth 2 data)))
            (delq nil (list (if (equal nodetype ecb-analyse-nodetype-completions)
                                '(ecb-analyse-complete "Complete"))
                            (if tag-p
                                '(ecb-analyse-show-tag-info "Show tag info"))
                            (if tag-with-pos-p
                                '(ecb-analyse-jump-to-tag "Jump to tag"))))))

        (defun ecb-analyse-menu-creator (tree-buffer-name node)
          "Creates the popup-menus for the analyse-buffer."
          (let ((nodetype (tree-node->type node)))
            (unless (equal nodetype ecb-analyse-nodetype-bucket)
              (mapcar (function (lambda (type)
                                  (cons type (ecb-analyse-create-menu node))))
                      `(,ecb-analyse-nodetype-context
                        ,ecb-analyse-nodetype-arguments
                        ,ecb-analyse-nodetype-completions
                        ,ecb-analyse-nodetype-localvars
                        ,ecb-analyse-nodetype-prefix
                        ,ecb-analyse-nodetype-assignee
                        ,ecb-analyse-nodetype-function
                        ,ecb-analyse-nodetype-function-arg)))))

     This example would be passed as parameter as follows:

        (tree-buffer-create "myname"
                            :menu-creator 'ecb-analyse-menu-creator
                            ...)

`MENU-TITLES'
     Nil or a list conses, each cons for a node-type. See MENU-CREATOR. The
     cdr of a cons must be either a string or a function which will be called
     with current node under point and must return a string which is
     displayed as the menu-title.

`MODELINE-MENU-CREATOR'
     Nil or a function which has to return nil or a menu in the same format
     `tree-buffer-create-menu' expects as argument - see the documentation of
     this function for details. This function gets one argument: The name of
     the tree-buffer. If the function returns a menu then this menu will be
     displayed when the user clicks with mouse-button 3 at the modeline of
     the tree-buffer. The menu-title will be "Tree-buffer modeline-menu".

`STICKY-PARENT-P'
     If not nil then with GNU Emacs >= 21 the tree-buffer displays in its
     header-line the unvisible parent-node if there is any. sticky-parent-fn
     is used to get this parent node.

`STICKY-INDENT-STRING'
     String used for indendation of the sticky node in the header-line so it
     matches the tree-display.

`STICKY-PARENT-FN'
     Function used to get that parent node which should be sticky. This
     function gets as argument a node and should either return nil (if there
     is not suitable parent node) or a node. This node will be displayed as
     sticky in the header-line of the tree-buffer. If nil is returned and
     sticky-parent-p is not nil then just the node under the header-line is
     displayed. If this argument is nil and sticky-parent-p is not nil then
     always the next unvisible parent node will be displayed in the
     header-line.

`TRUNC-LINES'
     Should lines in this tree buffer be truncated (not nil).

`READ-ONLY'
     Should the treebuffer be read-only (not nil).

`TREE-INDENT'
     Spaces subnodes should be indented. Ignored if TREE-STYLE is `image'
     (see below).

`INCR-SEARCH-P'
     Should the incremental search be enabled in the tree-buffer. Three
     choices: `prefix', `substring', `nil'. See the command
     `tree-buffer-incremental-node-search'.

`INCR-SEARCH-ADDITIONAL-PATTERN'
     Every search-pattern is prefixed with a regexp to jump over not
     important stuff of a displayed node-name at incr. search.. This is per
     default: beginning spaces and guide characters (|`-) and all
     expand/collapse-buttons [+], [x], rsp. [-]!

     If this argument is not nil then it must be a cons-cell where car is a
     string which should be a regexp-pattern which is added to the
     basic-prefix pattern (see above) and both of them prefix the
     incr-search-pattern. The cdr is the number of subexpressions in this
     additoonal pattern.

`ARROW-NAVIGATION'
     If not nil then a smart navigation with arrow keys is offered:

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

        - Up- and down-key: Point jumps to the first character of the
          previous (up) rsp. next node (down). "First" character means either
          the first character of the expand-symbol (in case
          EXPAND-SYMBOL-BEFORE-P is not nil) or of the displayed node-name.
          Or with other words: The first non-indentation and non-guide-line
          (see TREE-STYLE) character of a node.

`HOR-SCROLL-STEP'
     Number of columns a hor. scroll in the tree-buffer should scroll. If not
     nil then `M-mouse-1' and `M-mouse-2' scroll left and right and also
     `M-<left-arrow>' and `M-<right-arrow>'. Ignored with XEmacs.

`DEFAULT-IMAGES-DIR'
     Full path 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'.

`ADDITIONAL-IMAGES-DIR'
     Additional image-dir which should be searched first for images needed
     for current tree-buffer. If the image can not be found in this directory
     then DEFAULT-IMAGES-DIR is searched. If the image can't even found here
     the related ascii-symbol is used.

`IMAGE-FILE-PREFIX'
     Common prefix for all image-files for this tree-buffer, e.g. "ecb-".

`TREE-STYLE'
     There are three different styles available: Image-style (value `image'):
     Very nice and modern because image-icons are used to display the
     tree-buffer. For this style the arguments TREE-INDENT and
     EXPAND-SYMBOL-BEFORE-P have no effect.

     Ascii-style with guide-lines (value `ascii-guides') and ascii-style
     without guidelines (value `ascii-no-guides'. See *Note Tree-buffer
     styles:: for details about the tree-styles.

     Both ascii-styles are affected by the args TREE-INDENT and
     EXPAND-SYMBOL-BEFORE-P.

`ASCII-GUIDE-FACE'
     If TREE-STYLE is `ascii-guides' then this defines the face the guides
     should be displayed with.

`TYPE-FACER:'
     Nil or a list of one or more conses, each cons for a node-type (a
     node-type is an integer which must be set with `tree-node-new').  The
     cdr of a cons can be:

        - a face-symbol

        - a function-symbol which gets two arguments (see
          `tree-buffer-insert-text'). This function can do anything, but
          normally it should face a tree-node.

        - the symbol t. Then the tree-buffer assumes that the node-text is
          already faced and therefore it does not face the node, means it does
          nothing then inserting the node-text, if the tree-buffer is updated.

`EXPAND-SYMBOL-BEFORE-P'
     If not nil then the expand-symbol is displayed before the node-text.
     Ignored when TREE-STYLE is `image' and Emacs can display images.

`HIGHLIGHT-NODE-FACE'
     Face used for highlighting current selected node in this tree-buffer.

`GENERAL-FACE'
     General face in which the whole tree-buffer should be displayed.

`AFTER-CREATE-HOOK:'
     A function or a list of functions (with no arguments) called directly
     after creating the tree-buffer and defining it's local keymap. For
     example such a function can add additional key-bindings for this
     tree-buffer local keymap (use `local-set-key' for this).

     Here is an example for such a hook:

        (defun ecb-common-after-tree-buffer-create-actions ()
          "Things which should be performed after creating a tree-buffer.
        The tree-buffer is the current buffer."
          (local-set-key (kbd "C-t")
                         'ecb-toggle-do-not-leave-window-after-select)
          (if ecb-running-xemacs
              (define-key modeline-map
                '(button2up)
                'ecb-toggle-maximize-ecb-window-with-mouse)
            (local-set-key [mode-line mouse-2]
                           'ecb-toggle-maximize-ecb-window-with-mouse)))

`AFTER-UPDATE-HOOK:'
     A function or a list of functions (with no arguments) called each time
     after the tree-buffer has been updated via `tree-buffer-update'.


Here is an example how to create a tree-buffer (if you want a tree-buffer not
for ECB then just strip off the `defecb-tree-buffer-creator' and just call
`tree-buffer-create'):

   (defecb-tree-buffer-creator ecb-create-analyse-tree-buffer
       ecb-analyse-buffer-name
     "Create the tree-buffer for analyse-display."
     (tree-buffer-create
      ecb-analyse-buffer-name
      :frame ecb-frame
      :mouse-action-trigger ecb-tree-mouse-action-trigger
      :is-click-valid-fn 'ecb-interpret-mouse-click
      :node-selected-fn 'ecb-tree-buffer-node-select-callback
      :node-expanded-fn 'ecb-tree-buffer-node-expand-callback
      :node-collapsed-fn 'ecb-tree-buffer-node-collapsed-callback
      :node-mouse-over-fn 'ecb-mouse-over-analyse-node
      :mouse-highlight-fn 'ecb-analyse-node-mouse-highlighted-p
      :node-data-equal-fn 'ecb-analyse-compare-node-data
      :maybe-empty-node-types nil
      :leaf-node-types nil
      :menu-creator 'ecb-analyse-menu-creator
      :menu-titles (ecb-analyse-gen-menu-title-creator)
      :modeline-menu-creator 'ecb-common-tree-buffer-modeline-menu-creator
      :trunc-lines (ecb-member-of-symbol/value-list
                    ecb-analyse-buffer-name
                    ecb-tree-truncate-lines)
      :read-only t
      :tree-indent ecb-tree-indent
      :incr-search-p t
      :incr-search-additional-pattern nil
      :arrow-navigation ecb-tree-navigation-by-arrow
      :hor-scroll-step ecb-tree-easy-hor-scroll
      :default-images-dir (car ecb-tree-image-icons-directories)
      :additional-images-dir (ecb-member-of-symbol/value-list
                              ecb-analyse-buffer-name
                              (cdr ecb-tree-image-icons-directories)
                              'car 'cdr)
      :image-file-prefix "ecb-"
      :tree-style ecb-tree-buffer-style
      :ascii-guide-face ecb-tree-guide-line-face
      :type-facer nil
      :expand-symbol-before-p ecb-tree-expand-symbol-before
      :highlight-node-face ecb-analyse-face
      :general-face ecb-analyse-general-face
      :after-create-hook (append
                          (list (lambda ()
                                  (ecb-common-after-create-actions)))
                          ecb-common-tree-buffer-after-create-hook
                          ecb-analyse-buffer-after-create-hook)
      :after-update-hook nil))


File: ecb.info,  Node: A new tree-node,  Next: Updating a tree-buffer,  Prev: A new tree-buffer,  Up: tree-buffer

11.3.3 How to create a new tree-node
------------------------------------

When a new tree-buffer has been created, then the most senseful
programming-task is adding some tree-nodes to it.

11.3.3.1 Content of a tree-node
...............................

A tree-node is an object which stores in special "slots" several data
necessary to link the node with other nodes, to display the node and to hold
some associated node-data (e.g. a tag created by the semantic-library).

A tree-node can have the following slots:

`NAME'
     The name of the node. Regardless how the node is displayed; see
     SHRINK-NAME and DISPLAYED-NAME.

`TYPE'
     The type of the node; must currently be an interger! The type is used to
     classify the nodes, so for example all nodes of a certain type can
     display the same popup-menu - see `tree-buffer-create' or *Note A new
     tree-buffer:: which parts of a tree-buffer are distinguished by
     node-types.

`DATA'
     The data of the node; This can be any arbitrary emacs-lisp-object.  This
     slots holds that data asscociated with the node and represented by the
     node in the tree-buffer. Example: Assume a tree-buffer displaying a
     directory-tree where each node just displays as its name the name of
     (sub)directories, but not the full path. The full path is stored in the
     DATA-slot of a node so when clicking onto this node the asscociated
     directory can be open for example in a dired-buffer.

`EXPANDABLE'
     If not nil then the node is expandable means it has children.

`EXPANDED'
     If not nil then the node is currently expanded, means its children are
     visible in the tree-buffers as subnodes of the node.

`PARENT'
     The parent tree-node. This is the link to the father (rsp. mother ;-) of
     the node. It must be a object of type tree-node!

`CHILDREN'
     List of children tree-nodes. They must be all objects of type tree-node!

`SHRINK-NAME'
     Decides if the NAME can be shortened when displayed in a narrow tree
     buffer window. The following values are valid:

        - `beginning': The NAME is truncated at the beginning so the end is
          always visible.

        - `end': The NAME is truncated at the end. If the tree-node is
          EXPANDABLE the name is truncated so that the expand symbol is
          visible.

        - `nil': The NAME is never truncated. In this case DISPLAYED-NAME is
          equal to NAME.

`INDENTSTR'
     Containes the full indentation-string for the node. So a single node can
     easily be redrawn.

`DISPLAYED-NAME'
     Contains the current displayed name of the node. The displayed name can
     be different from the NAME according to the value of SHRINK-NAME.


11.3.3.2 Creating a new tree-node and adding it to the tree
...........................................................

A new tree-node has to be created with the function `tree-node-new'. This
"constructor" accepts the following parameter: NAME, TYPE, DATA,
NOT-EXPANDABLE, PARENT and SHRINK-NAME.

For all parameters except NOT-EXPANDABLE the description is available in the
slot-description in the section above. If NOT-EXPANDABLE is set to not nil
then the slot EXPANDABLE will be set to `nil'; otherwise to `t'.

`tree-node-new' returns a new tree-node.

The new node can either being added implicitely to the tree via the optional
PARENT-parameter when calling `tree-buffer-new' or explicitely by first
creating the new node without setting the parent-node but later setting the
parent-node via the according accessor (see next section below). Children
should only being added with `tree-node-add-children' - see next section.

11.3.3.3 Accessing the slots of a tree-node
...........................................

The section above shows which slots a tree-node have.

A slot with name XXX is getable with the following piece of code:

   (tree-node->xxx <a tree node>)

Here is an example how to get the value of the slot DATA:

   (tree-node->data <a tree node>)

A slot with name XXX is setable with the following piece of code:

   (setf (tree-node->xxx <a tree node>) <new value>)

Again an example with slot DATA which sets this slot to the string
"~/a_subdir_of_HOME":

   (setf (tree-node->data <a tree node>) "~/a_subdir_of_HOME")

*IMPORTANT*: Adding new children to a node should always being done with the
function `tree-node-add-children' because this functions encapsulates all the
necessary stuff needed to add children to a node (mainly adding the children
itself and setting the node itself as parent for every children).

See *Note The tree-buffer-API:: for the rest of the API available for
tree-nodes.


File: ecb.info,  Node: Updating a tree-buffer,  Next: Tree-buffer keybindings,  Prev: A new tree-node,  Up: tree-buffer

11.3.4 How to update a tree-buffer-display after changes
--------------------------------------------------------

When finished with adding tree-nodes to the tree-structure you mostly want to
display the current tree and its state in the buffer/window so a user can see
the current tree and can use it.

Threre are two ways to update a tree-buffer for display:

  1. Updating the whole tree-buffer:

     This is the most used way to update the tree-buffer display. It's quite
     simple, just call `tree-buffer-update'. In most cases you want to call
     it without arguments.

     If you want to display a certain expanded node and as much as possible
     subnodes of this node then pass this node-object as first argument to
     `tree-buffer-update'.

     If you do not have the need to display a completely new tree-structure
     but you want only to display a previously cached display-state then pass
     this cached-state as second argument to `tree-buffer-update'. See the
     documentation of this function and also *Note Tree-buffer How to:: for a
     detailled description how to do this.

  2. Updating only a single node of the tree-buffer:

     Sometimes it can be useful to update only exactly one special node, e.g.
     when your application codes some node-state in the displayed node-name
     (e.g. ECB displays the version-control state of a file as part of the
     related node-name) then it is necessary to update only this node if the
     state has changed.

     This can be done with the function `tree-buffer-update-node'. For this
     function the mentioning in this section can be misleading because this
     function can not only update the node-display but in general the slots
     NAME, SHRINK-NAME, TYPE, DATA and EXPANDABLE. Do `C-h f' to see the
     documentation of this function for all details!



File: ecb.info,  Node: Tree-buffer keybindings,  Next: The tree-buffer-API,  Prev: Updating a tree-buffer,  Up: tree-buffer

11.3.5 Default and customizable keybindings of a tree-buffer
------------------------------------------------------------

When creating a tree-buffer with `tree-buffer-create' the following keys will
automatically being bound:

`delete'
`backspace'
`home'
`end'
`a' (and each other key bound to `self-insert-command')
     All of these keys are bound to the command
     `tree-buffer-incremental-node-search' if the argument INCR-SEARCH-P of
     `tree-buffer-create' was set to not nil.  See the documentation of
     `tree-buffer-incremental-node-search' for all details.

`RET'
`C-RET'
`S-RET'
`M-RET'
`C-S-RET'
`mouse-1'
`C-mouse-1'
`S-mouse-1'
`M-mouse-1'
`mouse-2'
`C-mouse-2'
`S-mouse-2'
`M-mouse-2'
     All these keys are bound to an action-dispatcher which works as follows:

     If the callback-function in slot IS-CLICK-VALID-FN of the tree-buffer
     (*note A new tree-buffer::) returns nil then nothing is done.

     If either `RET' has been hitted or point is as the node-name (i.e.  the
     user has clicked with the mouse-1/2 at the node-name) then the
     callback-function in slot NODE-SELECTED-FN is called with the needed
     arguments (*note A new tree-buffer::).

     If point is at the expand/collape-button then depending on the
     expansion-state of the node either the callback in slot NODE-EXPANDED-FN
     or NODE-COLLAPSED-FN is called (for parameters see again *Note A new
     tree-buffer::).

     *IMPORTANT*: None of these callbacks must modify the slot EXPANDED of
     the passed node because this is done automatically by the
     action-dispatcher!

     At the end the dispatcher updates the tree-buffer-display with optimized
     display of the clicked/selected node - see *Note Updating a
     tree-buffer::. This means `tree-buffer-update' is called with that node
     as argument.

`TAB'
     Depending on the expansion-state of the node either the callback in slot
     NODE-EXPANDED-FN or NODE-COLLAPSED-FN is called (for parameters see
     again *Note A new tree-buffer::).

     *IMPORTANT*: None of these callbacks must modify the slot EXPANDED of
     the passed node because this is done automatically by the
     action-dispatcher!

     At the end the the tree-buffer-display is updated with optimized display
     of the clicked/selected node - see *Note Updating a tree-buffer::. This
     means `tree-buffer-update' is called with that node as argument.

`mouse-3'
     Activates the popup-menu for the current tree-buffer for current
     node-type (if defined). See *Note A new tree-buffer:: at argument
     MENU-CREATOR and MENU-TITLES. These callbacks are called for getting the
     menu and the menu-title.

`modeline-mouse-3'
     Activates the popup-menu for the modeline of the current tree-buffer (if
     defined). See *Note A new tree-buffer:: at argument
     MODELINE-MENU-CREATOR. This callback is called for getting the
     modeline-menu.

`M-m'
     This key is bound to the command `tree-buffer-show-node-menu-keyboard':
     Activates the popup-menu of current tree-buffer for current node-type
     via keyboard. If called with a prefix-arg then the library `tmm.el' is
     used for displaying the popup-menu - ignored with XEmacs.

`<up>'
`<down>'
`<left>'
`<right>'
     These keys are bound to the command `tree-buffer-arrow-pressed' which
     implements the smart arrow-key-navigation described in *Note A new
     tree-buffer:: at argument ARROW-NAVIGATION.


In addition to these automatically bound keys you can add further keybindings
to the local-keymap of the tree-buffer with the parameter AFTER-CREATE-HOOK
of `tree-buffer-create'. See *Note A new tree-buffer:: for an example which
binds `C-t' in this hook.


File: ecb.info,  Node: The tree-buffer-API,  Next: Do not with tree-buffer,  Prev: Tree-buffer keybindings,  Up: tree-buffer

11.3.6 All functions available for tree-buffers and tree-nodes
--------------------------------------------------------------

This chapter lists the complete API available for tree-buffers and tree-nodes.

*IMPORTANT*: These are the only functions and macros of tree-buffer.el you
are allowed to use for programming with tree-buffers and tree-nodes. If you
use other - not here listed - functions, macros or variables of
tree-buffer.el then you run the risk of unwanted side-effects or
program-behaviors!

11.3.6.1 The API for a tree-buffer:
...................................

See the documentation of these functions (e.g. via `C-h f') to get the
details how to use it.

   * `tree-buffer-add-image-icon-maybe'

   * `tree-buffer-find-image'

   * `tree-buffer-create'(1)

   * `tree-buffer-defpopup-command'

   * `tree-buffer-destroy'(2)

   * `tree-buffer-empty-p'

   * `tree-buffer-expand-node'

   * `tree-buffer-get-node-at-point'

   * `tree-buffer-node-data-equal-p'

   * `tree-buffer-recenter'

   * `tree-buffer-highlight-node-by-data/name'

   * `tree-buffer-find-displayed-node-by-data/name'

   * `tree-buffer-remove-highlight'

   * `tree-buffer-remove-node'

   * `tree-buffer-clear-tree'

   * `tree-buffer-displayed-nodes-copy'

   * `tree-buffer-search-displayed-node-list'

   * `tree-buffer-number-of-displayed-nodes'

   * `tree-buffer-get-data-store'

   * `tree-buffer-set-data-store'

   * `tree-buffer-get-root'

   * `tree-buffer-set-root'

   * `tree-buffer-update'

   * `tree-buffer-update-node'

11.3.6.2 The API for a tree-node
................................

See the documentation of these functions (e.g. via `C-h f') to get the
details how to use it.

   * `tree-node-add-children'

   * `tree-node-linelength'

   * `tree-node-map-subtree'

   * `tree-node-new'

   * `tree-node-new-root'

   * `tree-node-remove-child'

   * `tree-node-remove-child-by-data/name'

   * `tree-node-find-child-by-data/name'

   * `tree-node-find-child-by-name'

   * `tree-node-search-subtree-by-data'

   * `tree-node-search-subtree-by-id'

   * `tree-node-sort-children'

   * `tree-node-toggle-expanded'

In addition to these functions the tree-node API contains all accessors for a
tree-node which are described in *Note A new tree-node::.

---------- Footnotes ----------

(1) If the tree-buffer should be used by ECB then you must use
`defecb-tree-buffer-creator' - see the documentation!

(2) Not needed when `defecb-tree-buffer-creator' has been used for creation.


File: ecb.info,  Node: Do not with tree-buffer,  Next: Tree-buffer How to,  Prev: The tree-buffer-API,  Up: tree-buffer

11.3.7 Things which are strictly forbidden
------------------------------------------

Variable `tree-buffers': Only for internal use! It contains all tree-buffers
of current Emacs-instance, means *all* tree-buffers of *all* applications
which uses currently tree-buffers. Every application must store its own
collection of tree-buffers in an own variable! For example: ECB stores its
tree-buffer set in `ecb-tree-buffers'!

Variable `tree-buffer-displayed-nodes': Only for internal use!  Contains all
the current visible nodes of current tree-buffer in top-to-bottom order. This
variable is buffer-local in each tree-buffer! Do not use it directly! When
you want to cache the current display, then see *Note Tree-buffer How to::
how to do this.

*IMPORTANT*: An application may only use the API tree-buffer.el provides but
no internal variables - see *Note The tree-buffer-API::!


File: ecb.info,  Node: Tree-buffer How to,  Prev: Do not with tree-buffer,  Up: tree-buffer

11.3.8 How to deal with certain programming-requirements
--------------------------------------------------------

This chapter describes in detail how to solve certain programming-challenges
with tree-buffers.

11.3.8.1 Caching the current tree-buffer display
................................................

Sometimes it can be useful or important to cache the current display of a
tree-buffer and display later exactly this cached display-state.  Here is how
to do this:

  1. Caching the display: You have to do two tasks: First store the current
     internal structure of the tree-buffer; you must do this with the function
     `tree-buffer-displayed-nodes-copy'. Then store the buffer-contents of
     that tree-buffer you want to cache; you can do this for example with
     `buffer-substring'. For both tasks you must make the tree-buffer the
     current-buffer.

  2. Displaying a previous tree-buffer-cache: Make the tree-buffer the
     current buffer, call `tree-buffer-update' and pass as second argument
     CONTENT the data you have stored in step 1. See the documentation of
     `tree-buffer-update' for details.

     Here is an example:

        (tree-buffer-update
          nil
          (cons (nth 2 cache-elem) ;; the stored buffer-string
                (nth 1 cache-elem) ;; the stored tree-structure
          )))


File: ecb.info,  Node: Adviced functions,  Next: The layout-engine,  Prev: tree-buffer,  Up: Elisp programming

11.4 How to deal with the adviced functions
===========================================

ECB needs a bunch of advices so ECB can work correctly. ECB has a powerful
advice-backbone which allows defining sets of adviced functions whereas a set
means, that all advices of a certain set are always enabled or disabled
together.

For this ECB contains four macros:

   - `defecb-advice-set'

   - `defecb-advice'

   - `ecb-with-original-adviced-function-set'

   - `ecb-with-ecb-advice' (for this one see below)

For a detailed explanation of each macro read the documentation with
`describe-function'!

An advice in ECB must not being defined by `defadvice' but only with
`defecb-advice' which in turn needs a previously defined advice-set defined
by `defecb-advice-set'.

So ECB has always full control of all advices. For example ECB automatically
disables all advices of all advice-sets at load-time of ECB and also at
deactivation time of ECB. So you can be sure that after deactivating ECB all
ecb-advices are deactivated/disabled too.

In addition to the four macros above ECB offers two further macros for
running code with disabled some ecb-advices:

   - `ecb-with-original-basic-functions'

   - `ecb-with-original-permanent-layout-functions'

The advice set `ecb-basic-adviced-functions' contains most of the
ecb-advices. See the contents of this variable to see which advices are
contained in this set. Use `ecb-with-original-basic-functions' when you want
evaluating elisp-code with disabled basic-advices.
`ecb-with-original-basic-functions' is only a shortcut for
`ecb-with-original-adviced-function-set' called for the
`ecb-basic-adviced-functions'-set.

Same for `ecb-with-original-permanent-layout-functions' which is a shortcut
for the advice-set `ecb-permanent-adviced-layout-functions'.

Last but not least ECB contains an advice-set `ecb-always-disabled-advices'.
These advices are always disabled.  This advice-set can not be enabled by
`ecb-enable-advices' but such an advice has to be activated 'on demand' by
the caller. Such an advice must be used with the macro `ecb-with-ecb-advice'
(see the docstring) and is also enabled within the BODY of the macro-call.

ECB contains some more advice-sets but don't bother about it.

*Please Note*: See the value of `ecb-adviced-function-sets' which advice-sets
are defined and see `ecb-adviced-functions' for an overview for all adviced
functions.


File: ecb.info,  Node: The layout-engine,  Prev: Adviced functions,  Up: Elisp programming

11.5 How to program new layouts and new special windows
=======================================================

There are two aspects concerning this topic:

  1. Programming a new layout which contains several special ECB-windows like
     directories, sources, methods, history or other special windows and
     arranging them in a new outline.

  2. Creating complete new special windows (e.g. a local-variable window for
     a graphical debugger like JDEbug of JDEE), adding them to a layout and
     synchronizing them with the current active edit-window.

The former one covers merely the layout-programming aspect which is explained
in the first subsection of this chapter whereas the latter one covers all
aspects of creating new special windows and what is necessary to synchronize
it with the current active edit-window of ECB. This is explained in the
second subsection which will refers to the first subsection.

* Menu:

* Programming a new layout::    How to program a new layout
* Programming special windows:: Aspects of programming special windows
* Possible layout-outlines::    The wide range of possible layouts
* The layout-engine API::       The complete layout-engine API

