[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Tips and tricks

This chapter contains some tips and tricks how to deal best with some situations.

8.1 Changing faces in the ECB tree-buffers  
8.2 Working with small screens  
8.3 Working with big screens  
8.4 Simulating speedbar without an extra frame  
8.5 Integrating speedbar in the ECB-frame  
8.6 Optimize scrolling in the edit-window  
8.7 Working with large directories  
8.8 Working with remote directories  
8.9 Supporting Version control systems  
8.10 Optimal using of eshell in ECB  
8.11 Grepping directories with ECB  
8.12 Working best with ECB and JDEE  
8.13 Displaying the compile-window on demand  
8.14 Parsing and displaying non-semantic sources  
8.15 Using hide-show from the methods-buffer-menu  
8.16 Support of several Emacs-window-managers  
8.17 Displaying the trees of the ECB-windows with different styles  Displaying the trees with different styles
8.18 Using semanticdb to jump to type-tags defined in other files  Using semanticdb for going to external nodes

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 Changing faces in the ECB tree-buffers

There are two basic faces:

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
(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(26) ECB-tree-buffers (incl. the methods buffer).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.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 4.8.5 Interactively creating new layouts and 9.5 How to program new layouts and new special windows 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.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, See section 8.5 Integrating speedbar in the ECB-frame.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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 (see section 8.14 Parsing and displaying 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(27).

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.6 Optimize scrolling in the edit-window

Emacs 20.X seems to slow down scrolling if there is a horizontal split in the frame and/or a lot of overlays in the buffer which is scrolled. This is independent of ECB! But because almost all layouts of ECB uses horizontal splits of the frame and because ECB is based on semantic which uses overlays intensively there can be poor scrolling performance in large buffers, especially with java-buffers in jde-mode.

This scrolling performance can be increased a lot if the options scroll-conservatively and scroll-step are set appropriately: The former one should have a value of 0 during ECB is active and the latter one a value of either 0 or > 1 (the exact value depends on the power of your machine).

As far as we know this is not a problem of Emacs 21.X or XEmacs. With these versions of Emacs there should be no scrolling problem even with scroll-step has value 1.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.7 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 (see section 4.1 Working with the mouse in the ECB-windows).

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.8 Working with remote directories

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.8.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(32). 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!).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.8.2 Excluding remote directories from time-consuming tasks

ECB performs some tasks stealthy 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 (see section 4.13 Stealthy background-tasks of ECB).

Therefore it is probably the best to switch on each of the stealthy tasks with the unless-remote which is the default activation (see section 4.13 Stealthy background-tasks of ECB). 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9 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(33) in front of the filename.

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

Enable or disable this feature.
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.
Allows excluding certain directories (on a regexp-basis) from the VC-support even if they are managed by a VC-system.
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.

8.9.1 How ECB identifies the VC-backend of a dir  
8.9.2 How ECB checks the VC-state of a file  
8.9.3 Important informations about remote repositories  What you should now about this
8.9.4 How to refresh ECB-state-display when changed outside  How to refresh when state changed outside
8.9.5 Necessary steps and informations for adding new backends  Necessary steps for adding new backends
8.9.6 Currently know problems with the VC-support  Currently known problems of the VC-support

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.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 (see section 8.9.2 How ECB checks the VC-state of a file).

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

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

This function tries to be as smart as possible: First it checks if DIRECTORY is managed by CVS by checking if there is a subdir CVS. If no then nil is returned. If yes then for GNU Emacs it takes into account the value of vc-cvs-stay-local: If t then just return CVS. Otherwise ECB checks the root repository if it is a remote repository. If not just CVS is returned. If a remote repository it checks if the value of vc-cvs-stay-local is a string and matches the host of that repository. If yes then just CVS is returned. If not then ECB checks if that host is currently accessible by performing a ping. If accessible CVS is returned otherwise nil. This has the advantage that ECB will not be blocked by trying to get the state from a remote repository while the host is not accessible (e.g. because the user works offline).

Special remark for XEmacs: XEmacs has a quite outdated VC-package which has no option vc-cvs-stay-local so the user can not work with remote CVS-repositories if working offline for example. So if there is no option vc-cvs-stay-local then ECB performs always the repository check mentioned above.

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-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 other VC-backends than CVS, RCS, SCCS or Subversion you have to write your own identify-backend-funtion for the used VC-backend (e.g. Clearcase)!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] Special remarks for XEmacs

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.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 (see section 8.9.1 How ECB identifies the VC-backend of a dir).

You can add any arbitrary functions as check-state-function to ecb-vc-supported-backends as long they get one filename-argument and return a state-symbol (e.g. up-to-date. ECB can understand a certain set of state-values wghich 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 - when running under GNU Emacs - the function vc-state of the VC-package(35) to check the state for the backends CVS, RCS, SCCS and Subversion. 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 and Subversion (e.g. Clearcase) you should add a that new backend to the VC-package (see the initial comments of vc.el how to do this) then ECB will automatically support this new backend. Alternatively it can be enough if you write your own check-state-function for this backend and add the needed mapping to ecb-vc-state-mapping if necessary.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] Getting heuristic state-values or real ones for CVS

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

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.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 (see section 8.9.1 How ECB identifies the VC-backend of a dir). See also ecb-vc-xemacs-exclude-remote-cvs-repository!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] Remote paths and the VC-support of ECB

ECB supports working with remote directories like TRAMP- or EFS-directories (see section 8.8 Working with 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 (see section 4.13 Stealthy background-tasks of ECB).

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!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.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 8.9.5 Necessary steps and informations for 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.
"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.
"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 (see section 8.9.2 How ECB checks the VC-state of a file).

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 4.1 Working with the mouse in the ECB-windows (subsection "The right mouse button").

In addition to these popup-commands using the POWER- rsp. Shift-click (see section 4.1 Working with the mouse in the ECB-windows) onto a directory in the directory-window of ECB refreshes the VC-state-values of all files contained in this directory too.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.5 Necessary steps and informations for adding new backends

There are mainly three necessary steps for adding a new(36) 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 8.9.2 How ECB checks the VC-state of a file 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)
        (setq ecb-checkedin-file nil)))

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.9.6 Currently know problems with the VC-support

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] Remote repositories and XEmacs

Currently there are mostly problems related to XEmacs - cause of its outdated VC-package which allows no heuristic state-computation but always runs "cvs status" to get the VC-state for a file (done by vc-cvs-status). This can be horrible slow for remote CVS-root-repositories. Now ECB performs the VC-check stealthy and only in idle-time of Emacs but even so XEmacs can be blocked espcially if the cygwin-build of XEmacs is used: This XEmacs-version is substantially slower concering file-operations and has sometimes a very slow and delayed response-behavior for mouse- and keyboard interrupts - so even ECB let the user interrupt by using input-pending-p before getting the VC-state of a file XEmacs sometimes does not react to such user-interrupts and seems to be blocked.

Current solution: ECB offers the option ecb-vc-xemacs-exclude-remote-cvs-repository which excludes remote repositories from being checked. This option is per default t for XEmacs. Whenever XEmacs syncs up its VC-package with the Emacs one this option will automatically take no effect.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.10 Optimal using of eshell in ECB

ECB offers a very smart integration of the "eshell" if you are using a compile window (see section 4.4 Temp- and compile-buffers display in ECB)(37)

Here is a short summary of provided features:

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

You have not 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-synchronize 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.13 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 (see section 4.4 Temp- and compile-buffers display in ECB) 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 direct 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 (see section 8.16 Support of several Emacs-window-managers); 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.!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.14.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 (see section 5.3.16 Group ecb-non-semantic) for further details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.14.2 Automatic rescanning/reparsing of non-semantic-sources

In contrast to semantic (see global-semantic-auto-parse-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(39).

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.16.1 Enabling of the support

Every support must be enabled explicitly:

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


;; or - if you like escreen more


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.17 Displaying the trees of the ECB-windows with different styles

ECB offers three different styles for the tree-buffers in the ECB-windows. Two of the styles are ascii-based and one style uses images for drawing the tree-structure.

8.17.1 Basic knowledge about the styles  
8.17.2 How to customize the ascii-styles  
8.17.3 Which images are used for the tree  
8.17.4 Special images for the Methods-buffer  Images for the tags in the Methods-buffer

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.17.1 Basic knowledge about the styles

There are nine image-names which define the control- and guide-symbols to draw the tree. Here is the list of the allowed image-names and the related corresponding ascii-symbols:

A tree will be build-up with these elements like follows:

[-] node-with-subnodes      (open)
 |-[+] not-empty-subnode1   (guide+handle+close)
 |-[x] empty-subnode        (guide+handle+empty)
 `-[-] not-empty-subnode2   (end-guide+handle+open)
    |-* leaf-1              (no-guide+no-handle+guide+handle+leaf)
    `-* leaf-2              (no-guide+no-handle+end-guide+handle+leaf)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.17.2 How to customize the ascii-styles

The ECB-option ecb-tree-buffer-style offers two different styles completely drawn with ascii-controls and -guides.

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

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

The tree-layout of both ascii-styles can be affected with the options ecb-tree-indent and ecb-tree-expand-symbol-before (the examples above have set 4 for the former and true for the latter one). For the guide-style the face and color of the guide- and handle-symbols can be customized with the option ecb-tree-guide-line-face (default is the equal-named face).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.17.3 Which images are used for the tree

Depending on the value of ecb-tree-buffer-style and the image-support of (X)Emacs, the tree-buffer try to use images instead of strings to draw a nice-looking tree.

If images can and should be used then the option ecb-tree-image-icons-directories tells ECB where to search for suitable image-icons for each of the nine image-names (see above). An image is used for displaying a control with name "XXX" if one of the directories of ecb-tree-image-icons-directories contains an image-file with basename "ecb-XXX" and an extension which is supported by (X)Emacs. Currently supported extensions are ".xpm", ".png", ".gif", ".jpeg", ."jpg" and ".xbm".

Example: To display the control with name "open" with a suitable image then one of the directories of ecb-tree-image-icons-directories must contain a file with name "ecb-open.xpm" or "ecb-open.png" etc. See the description of this option to get all important details how and in which sequence ECB searches the directories of ecb-tree-image-icons-directories.

ECB comes with predefined default-images usable for every tree-buffer and special images for the Directories- and the Methods-tree-buffer. They are defined in several different heights - so for the most senseful font-heights of a tree-buffer a fitting image-size should be available. The shipped 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 evaluating (locate-data-directory "ecb"). If you do not want to change the images then you normally have nothing to do because the default value of ecb-tree-image-icons-directories points already to the correct image-directories.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] A special note for XEmacs

At least XEmacs 21.14 (but probably previous versions too) has a bug in its display-engine which prevents adjacent images to be displayed correctly. The effect is, that in a row of two or more adjacent images (e.g. end-guide+handle+open - see the tree-example above) always all images are masked by the last one, means only the last one is visible. If at least one normal character (e.g. a space) is placed between two images then the images are displayed correctly. Therefore ECB has implemented the following work-around to get best possible results with XEmacs: open-, close-, empty-, leaf-, guide-, end-guide- and no-guide-images are displayed with images and the handle- and the no-handle-images are displayed with the corresponding ascii-symbols (which is "-" rsp. " "). The face (the color) of the handle-symbol is customizable via the option ecb-tree-guide-line-face.

This bug is already reported to the XEmacs-team. If your XEmacs has fixed this bug then add the following to your `.emacs'-file (or whereever your emacs-setup is located):

(setq tree-buffer-enable-xemacs-image-bug-hack nil)

Then ECB uses images without any special work-around with XEmacs too. Just try it - if the tree-buffers look ugly then the XEmacs-bug is probably not fixed correctly.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.17.4 Special images for the Methods-buffer

ECB can display all the semantic-tags in the Method-buffer with special icons for methods, variables and classes - each of them with a different icon dependend of the protection of the tag. This feature can be disabled/enabled via the option ecb-display-image-icons-for-semantic-tags. All the special images are located in that directory where the option ecb-tree-image-icons-directories point to for methods.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.18 Using semanticdb to jump to type-tags defined in other files

In OO-languages like CLOS, eieio and C++ there can be type-tags in the method-buffer which are somehow virtual because there is no definition in the current source-file. But such a virtual type collects all its outside defined members like methods in C++ which are defined in the `*.cc' file whereas the class-definition is defined in the associated header-file. ECB uses semanticdb to open the definition-file of such a tag and to jump to the definition of this tag. Same for parent-tags in the methods-buffer. This feature can only work correctly if semanticdb is well configured!

Here is a C++-example:

This class is defined in a file `ParentClass.h':

class ParentClass
  int p;

This class is defined in a file `ClassWithExternals.h'

#include "ParentClass.h"

class ClassWithExternals : public ParentClass
  int i;


Both the constructor and the desctructor of the class "ClassWithExternals" are defined in a file `ClassWithExternals.cc':

#include "test.h"

ClassWithExternals::ClassWithExternals(int i,
                                       boolean b,
                                       char c)


ECB displays the contents of `ClassWithExternals.cc' in its methods-buffer like follows:

[-] [Includes]
 `- test.h
[-] ClassWithExternals
 |  +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals
 `- +~ClassWithExternals ():void

Both the constructor and the desctructor of the class "ClassWithExternals" are grouped under their class-type. ECB now uses semanticdb to jump to the definition of class "ClassWithExternals" when you click onto the type-node "ClassWithExternals" in the methods-buffer.

The contents of `ClassWithExternals.h' are displayed like follows:

[-] [Includes]
 `- ParentClass.h
[-] ClassWithExternals:class
 |  [-] [Parents]
 |   `- ParentClass
 |  [-] [Variables]
 |   `- -i:int
 |  +ClassWithExternals ():ClassWithExternals
 |  +~ClassWithExternals ():void
 `- [+] [Misc]

ECB uses semanticdb to jump to the definition of the class "ParentClass" when you click onto the node "ParentClass".

To enable this feature global-semanticdb-minor-mode must be enabled and semanticdb must be correctly configured. This means mainly that the option semanticdb-project-roots must be setup well. See the manual of semanticdb for further informations about this.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on October, 2 2007 using texi2html