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: Top,  Next: Install and first steps,  Prev: (dir),  Up: (dir)

This is the user manual for ECB version 2.40.

ECB stands for "Emacs Code Browser". While (X)Emacs already has good
*editing* support for many modes, its *browsing* support is somewhat lacking.
That's where ECB comes in: it displays a number of informational windows that
allow for easy source code navigation and overview.

The informational windows can contain:

   * A directory tree,

   * a list of source files in the current directory (with full support and
     display of the VC-state),

   * a list of functions/classes/methods/... in the current file, (ECB uses
     the CEDET-Semantic, or Imenu, or etags, for getting this list so all
     languages supported by any of these tools are automatically supported by
     ECB too)

   * a history of recently visited files (groupable by several criterias),

   * helpful informations and possible completions according to the current
     context which is computed by the semantic-analyzer for some sort of
     intellisense,

   * the Speedbar and

   * output from compilation (the "*compilation*" window) and other modes
     like help, grep etc. or whatever a user defines to be displayed in this
     window.

As an added bonus, ECB makes sure to keep these informational windows
visible, even when you use `C-x 1' and similar commands.

It goes without saying that you can configure the layout, ie which
informational windows should be displayed where. ECB comes with a number of
ready-made window layouts to choose from.

*Please note*: Experienced ECB users find a complete alphabetical list of all
commands and user-options in *Note Interactive ECB commands:: and *Note
Customizable options::.

The latest version of ECB can always be found at the URL
`http://ecb.sourceforge.net'.

To send bug reports, or participate in discussions about ECB, use the mailing
list <ecb-list@lists.sourceforge.net> via the URL
`http://lists.sourceforge.net/lists/listinfo/ecb-list'.

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

* Menu:

* Install and first steps::     Installing ECB and first steps
* Overview::                    Compact introducing of basic concepts
* Manual usage::                How to use this manual
* ECB-windows::                 Description of all ECB-windows of ECB
* Activation and Deactivation:: How to start and end ECB
* Usage of ECB::                How to use ECB
* Customizing::                 How to customize ECB
* Submitting problem report::   What to do when problems occur
* Upgrading::                   Upgrading and downloading packages
* Common use-cases::             Useful hints and tips
* Elisp programming::           Entry points for Elisp programmers
* Conflicts and bugs::          Known Conflicts with other packages and bugs
* FAQ::                         Frequently asked questions
* Command Index::               Index for interactive commands
* Option Index::                Index for user options
* Concept Index::               Index for concepts and terms

 --- The Detailed Node Listing ---

Installation and first steps of ECB

* Installation::                Installation of ECB
* Setting up Emacs::            How to set up Emacs for file parsing with ECB
* First steps::                 First steps after activating ECB first time

Installation of ECB

* Requirements::                Requirements for ECB
* ECB as XEmacs-package::       Installation of ECB as a XEmacs-package
* Standard ECB-Installation::   Standard installation of ECB for (X)Emacs
* Makefile customization::      Customizing build using Makefile.conf

How to set up Emacs for file parsing with ECB

* General hints::               General hints for a correct setup
* Setting up CEDET/semantic::   How to setup semantic correctly
* Non-semantic files::          Setup for file types not supported by semantic

All ECB-windows of ECB

* Basic ECB-windows::           Description of the basic ECB-windows
* Add-on ECB-windows::          Description of additional ECB-windows

The basic ECB-windows of ECB

* Tree-buffer basics::          General introduction into tree-buffers
* Tree-buffer styles::          Displaying the trees with different styles
* ECB Directories-window::      Contents of the ECB Directories-window
* ECB Sources-window::          Contents of the ECB Sources-window
* ECB Methods-window::          Contents of the ECB Methods-window
* ECB History-window::          Contents of the ECB History-window

Displaying the trees with different styles

* Style basics::                Basic knowledge about the styles
* Ascii-based styles::          How to customize the ascii-styles
* Tree-buffers with images::    Which images are used for the tree
* Images for Methods-buffer::   Images for the tags in the Methods-buffer

Add-on ECB-windows of ECB

* Semantic analyser::           Analyses and displays semantic context
* Symboldefinition::            Displays definition of current symbol

Activation and Deactivation

* Standard activation::         How to manually (de)activate ECB
* Automatic activation::        Automatically (de)activating ECB

Usage of ECB

* Using the mouse::             Working with the mouse
* Using the keyboard::          Working with the keyboard
* The edit-area::               How to use the edit-area
* Temp- and compile-buffers::   Displaying temp- and compilation-buffers
* The other window::            How the ``other window'' is determined
* The Methods window::          Using and customizing the Methods-window
* Filtering the tree-buffers::  Applying filters to the ECB-tree-buffers
* The ECB-layout::              Changing, customizing, redrawing, creating
* Hiding the ECB windows::      Hiding/Showing the ECB-windows
* Maximizing the ECB windows::  Maximizing the ECB-windows
* Back/forward navigation::     Back- and forward navigation like a browser
* ECB-window synchronizing::    Auto./manual synchronizing the ECB-windows
* Stealthy background tasks::   Stealthy background-tasks of ECB
* Interactive ECB commands::    All interactive user-commands of ECB

Working with the keyboard in the ECB-windows

* Navigation/Selection::        Keyboard navigation/selection in a tree-buffer
* Incremental search::          Find nodes as fast as possible
* Personal tree-keybindings::   Adding personal keybindings to a tree-buffer
* Using popup-menus::           Using the popup-menus from keyboard.

Using and customizing the ECB-Methods window

* Visiting tags::               Possible actions after visiting a tag
* Expanding::                   Explicit and automatic expanding
* Customizing the display::     How to customize the Methods-buffer display
* Updating Methods-window::     Updating Methods with contents of current buffer
* Updating for ind. buffers::   Updating Methods for indirect buffers
* Jumping to external tags::    Jumping to the definition of external types

Applying filters to the special ECB-tree-buffers

* Filtering Directories::       Applying filters to the Directories-buffer
* Filtering Sources::           Applying filters to the Sources--buffer
* Filtering History::           Applying filters to the History-buffer
* Filtering Methods::           Applying filters to the Methods-buffer

Changing, customizing, redrawing and creating layouts

* Changing the ECB-layout::     How to change and customize the layout
* Redrawing the ECB-layout::    How and when redrawing the layout
* Changing window sizes::       Changing sizes of the ECB-windows
* Fixing window sizes::         Fixing sizes of the ECB-windows
* Creating a new ECB-layout::   Interactively creating new layouts

Synchronization of the ECB-windows

* General synchronization aspects::       General synchronization aspects
* Synchronization of basic ECB-windows::  Synchronization of basic ECB-windows
* Add-on synchronization::                Synchronization of add-on ECB-windows

Customizing ECB

* General aspects::             General aspects for customizing ECB
* Most important options::      Which option you must know
* Customizable options::        All customizable options of ECB

General aspects for customizing ECB

* setq or customize::           Should i use setq or customize?
* Site-wide customizing::       Site-wide customizing of ECB

All customizable options of ECB

* ecb-general::                 General customizing ECB
* ecb-tree-buffer::             Customizing the general tree layout
* ecb-directories::             Customizing the ECB-directories-tree
* ecb-sources::                 Customizing the ECB-sources-window
* ecb-methods::                 Customizing the ECB-methods-window
* ecb-history::                 Customizing the ECB-history-window
* ecb-analyse::                 Customizing the ECB-analyse-window
* ecb-symboldef::               Customizing the ECB-symboldef-window
* ecb-layout::                  Customizing the ECB-layout
* ecb-compilation::             Customizing the compile-window
* ecb-create-layout::           Customizing options for creating layouts
* ecb-face-options::            Customizing options for faces
* ecb-faces::                   Customizing the faces
* ecb-help::                    Customizing the online help of ECB
* ecb-eshell::                  Customizing the eshell-integration
* ecb-speedbar::                Customizing the speedbar-integration
* ecb-non-semantic::            Customizing parsing non-semantic sources
* ecb-winman::                  Customizing window-manager support
* ecb-mode-line::               Customizing the tree-buffer-modelines
* ecb-version-control::         Customizing the version-control-support

Upgrading and downloading packages

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

Automatic upgrading of options

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

Handling of common use-cases

* 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

Supporting Version control systems

* 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

Entry points for Elisp programmers

* 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

The library tree-buffer.el

* 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

How to program new layouts and new special windows

* 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

Conflicts and bugs of ECB

* Conflicts::                   Conflicts with other packages
* Bugs::                        Known bugs


File: ecb.info,  Node: Install and first steps,  Next: Overview,  Prev: Top,  Up: Top

1 Installation and first steps of ECB
*************************************

This chapter describes how to install ECB and setup (X)Emacs correctly and
what are the first steps after activation of ECB.

* Menu:

* Installation::                Installation of ECB
* Setting up Emacs::            How to set up Emacs for file parsing with ECB
* First steps::                 First steps after activating ECB first time


File: ecb.info,  Node: Installation,  Next: Setting up Emacs,  Prev: Install and first steps,  Up: Install and first steps

1.1 Installation of ECB
=======================

This section describes how to install ECB.

* Menu:

* Requirements::                Requirements for ECB
* ECB as XEmacs-package::       Installation of ECB as a XEmacs-package
* Standard ECB-Installation::   Standard installation of ECB for (X)Emacs
* Makefile customization::      Customizing build using Makefile.conf


File: ecb.info,  Node: Requirements,  Next: ECB as XEmacs-package,  Prev: Installation,  Up: Installation

1.1.1 Requirements
------------------

This section describes the requirements of ECB. Just ensure that these
requirements of ECB are fulfilled.

The short story: With Emacs >= 23.2 there is nothing to do. With XEmacs or
Emacs < 23.2 you have to install the CEDET-suite.

The long story:

  1. Emacs-version: ECB works only with (X)Emacs >= 21! If you have an older
     one, please upgrade.

  2. CEDET-suite: If Emacs >= 23.2 is used then CEDET is already integrated
     into Emacs and there is nothing to do.

     For users of any XEmacs-version, any Emacs-version < 23.2 or the latest
     author CEDET version: Get it from `http://cedet.sourceforge.net', read
     the setup-instructions in `http://cedet.sourceforge.net/setup.shtml' and
     read also the shipped file `INSTALL'.

     *Please note*: If ECB detects an author version of CEDET (as available
     at `http://cedet.sourceforge.net') then ECB will ALWAYS try to use that
     one even if you use Emacs >= 23.2! This is for users who want to use
     latest Emacs >= 23.2 but still prefer using the latest author version of
     CEDET instead of the Emacs-integrated one.

     So if you want to use the Emacs-integrated CEDET-suite of Emacs >= 23.2
     you have to ensure that no author-version of CEDET is in the `load-path'!
     This means that the library cedet.el of the author-version MUST NOT be
     loaded into Emacs (as described in the file INSTALL of CEDET)! This is a
     valid check: (locate-library "semantic-ctxt") must return nil!

  3. Only for XEmacs-users: If you use XEmacs you must have installed the
     package c-support (contains hideshow.el). If you want to read the
     online-help of ECB in HTML-format you must have the library browse-url
     (part of the mail-lib XEmacs package) installed; this package is also
     needed for submitting problem-reports to the ECB-maintainers!

  4. Optional for Java-coding: ECB works very well with the JDEE package (
     `http://jdee.sourceforge.net') but JDEE is not required by ECB.


Do not install ECB before you have successfully installed the requirements!


File: ecb.info,  Node: ECB as XEmacs-package,  Next: Standard ECB-Installation,  Prev: Requirements,  Up: Installation

1.1.2 Installation of ECB as a XEmacs-package
---------------------------------------------

This section is only relevant for XEmacs-users!

In previous versions of ECB XEmacs-users could use the
package-management-system of XEmacs for first-time downloading/installing ECB
or for upgrading to a newer version of ECB.

Beginning with version 2.33 ECB does no longer support the old versions of
semantic, eieio and speedbar not part of the CEDET-suite. ECB >= 2.33 requires
fully installed CEDET-suite with version >= 1.0pre6. This one is not
available as XEmacs-package. Therefore ECB can also not be run as
XEmacs-package. If cedet will become a XEmacs-package then probably ECB will
come back as XEmacs-package. But in the meanwhile you have to install ECB "by
hand" as described in the next section (*note Standard ECB-Installation::).


File: ecb.info,  Node: Standard ECB-Installation,  Next: Makefile customization,  Prev: ECB as XEmacs-package,  Up: Installation

1.1.3 Standard installation of ECB for (X)Emacs
-----------------------------------------------

Follow exatly these steps to install ECB:

  1. Fulfill all requirements ECB needs (*note Requirements::)

     ECB performs two autom checks:

        - At load-time: It checks if cedet is at least installed so ECB can
          be loaded. If not it reports an error.

        - At start-time: It checks if the correct versions of cedet and
          semantic are installed and gives you proper feedback.

     So if you are not sure if you have installed the required packages at
     all or if you have installed the correct versions of these packages then
     do not worry about this, just go on with the following installation
     steps: If ECB is missing something it will give you proper feedback and
     support not later than at load-time or start-time!

  2. Download and unpack the ECB archive (probably you have already done this
     :-)

  3. Add the new ECB-directory to your `load-path' variable.

     You *MUST* add the ECB-install-directory to the `load-path' either by
     changing the `load-path' variable directly in your `.emacs' or
     `site-lisp/site-start.el' or by working with a file `subdirs.el'(1).

     So for example the needed entry for your `.emacs'-file could be:

        (add-to-list 'load-path
                     "/path/to/your/ecb/installation/directory")

     *ATTENTION*: ECB is NOT properly installed if it's directory is not
     added to `load-path' and for example just loaded by

        (load-file "/path/to/ecb/ecb.el")

     Do not do this! It will not work!

  4. Load ECB by adding code to your `.emacs':

     If you want to load the complete ECB at (X)Emacs-loadtime (Advantage:
     All ECB-options available after loading ECB. Disadvantage: Increasing
     loadtime(2)):

        (require 'ecb)

     If you want to load the ECB first after starting it by `ecb-activate'
     (Advantage: Fast loading(3).  Disadvantage: ECB- and semantic-options
     first available after starting ECB):

        (require 'ecb-autoloads)

     This loads all available autoloads of ECB, e.g. `ecb-activate',
     `ecb-minor-mode', `ecb-byte-compile' and `ecb-show-help'.

     Regardless which method you prefer: In both cases the used statement
     must be placed *after* the statement of step 3!

     Only for users of a manually installed author version of the CEDET-suite
     (not that one integrated into Emacs >= 23.2): Instructions for loading
     CEDET into Emacs must be placed somewhere before the statements needed
     for loading ECB (s.a.)!

  5. Restart (X)Emacs.

ECB is now ready for use and can be activated by calling `M-x ecb-activate'
or `ecb-minor-mode'. Now you can either starting using ECB or you can do
these optional installation steps:

  6. Reading the online help with `ecb-show-help'

     Maybe you are interested to read the online-help of ECB before first
     start.

  7. Bytecompiling ECB with `ecb-byte-compile'

     This byte compiles ECB. You can safely ignore all messages if there are
     any. (You can also bytecompile ECB from the command-line either by using
     the `Makefile' or by using the batch-file `make.bat'; just read the
     comments in that file you choose.)

     `Mekefile' can be customized using `Makefile.conf' (*note Makefile
     customization::).

  8. Installing the Info-help of ECB

     The ECB distribution contains a subdirectory `info-help' which contains
     the online-help of ECB in Info-format. You can install this online help
     so it's available in the Top-directory of Info. There are two ways to do
     this:

        - Use "install-info" (recommended):

            1. Copy the files of the subdirectory `info-help' into the
               info-directory of Emacs

            2. Install the file `info-help/ecb.info' with the command
               "install-info" (if available on your system) in the `dir'-file.

          The supplied `Makefile' offers a target `install-help' which does
          both of these steps. You have just to call `make install-help' with
          the correct EMACSINFOPATH set (see the comment in `Makefile'). Here
          is an example:

             make EMACSINFOPATH=/path/to/emacs/info install-help

        - Manual Installation:

          Copy the files of the subdirectory `info-help' into the
          info-directory of Emacs and modify the file `dir' manually.

     But it doesn't matter if you do not execute this step (8.) because the
     online help of ECB is always available though, see `ecb-show-help'
     (*note Interactive ECB commands::).


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

(1) This works at least for Emacs but XEmacs may have slightly different
mechanisms; see the XEmacs documentation

(2) Cause of full loading of ECB itself and also the packages semantic, eieio
and speedbar regardless if ECB is started.

(3) ECB, semantic, eieio and speedbar are first loaded after starting ECB or
with other words: ECB and semantic are not loaded if you do not use/need them


File: ecb.info,  Node: Makefile customization,  Prev: Standard ECB-Installation,  Up: Installation

1.1.4 Customizing build using Makefile.conf
-------------------------------------------

Platform specific vars and programs can be customized from a command-line or
by means of `Makefile.conf', for which `Makefile.conf.template' is a
template. It contains descriptions of all configuration options. Copy it to
`Makefile.conf' and override as needed.

If settings hasn't been changed, `Makefile' uses platform specific defaults.

There is a target, that prints configuration values: `make printconf'.

When you use CEDET built into Emacs and don't install help, then you don't
even need the `Makefile.conf'.

When you use CEDET from the repo and/or want to install info files, then set
appropriate variables in `Makefile.conf', for example:

   CEDET = ~/projects/cedet-bzr
   EMACSINFOPATH = ~/.emacs.d/info


File: ecb.info,  Node: Setting up Emacs,  Next: First steps,  Prev: Installation,  Up: Install and first steps

1.2 How to set up Emacs for file parsing with ECB
=================================================

*Please note*: Normally it should not necessary for you to bother with the
following stuff unless you have problems getting ECB working correctly for
you.

* Menu:

* General hints::               General hints for a correct setup
* Setting up CEDET/semantic::   How to setup semantic correctly
* Non-semantic files::          Setup for file types not supported by semantic


File: ecb.info,  Node: General hints,  Next: Setting up CEDET/semantic,  Prev: Setting up Emacs,  Up: Setting up Emacs

1.2.1 General hints for a correct setup
---------------------------------------

ECB is for browsing files and therefore you have to setup your
Emacs-configuration properly so the file-parsing engines like semantic, imenu
or etags can be activated automatically for parsing your Emacs-Lisp, C, C++ or
Java buffers(1). For this Emacs must activate the correct `major-mode' for
the source-files and Emacs can only do this if the option `auto-mode-alist'
is setup correctly. The correct major-modes and possible file-extensions(2)
are:

LANGUAGE         MAJOR-MODE                              EXTENSION(S)
Emacs Lisp       `emacs-lisp-mode'                       .el
C                `c-mode'                                .h, .c
C++              `c++-mode'                              .h, .hxx, .hh, .HH,
                                                         .cxx, .cpp, .cc, .CC
Java             `java-mode' or `jde-mode' (if you use   .java
                 JDEE)                                   

Example: If you want files with extension ".cpp" being c++-parsed by semantic
and ECB, your `auto-mode-alist' must contain an entry like:

   ("\\.cpp\\'" . c++-mode)

After this ECB will correctly parse your ".cpp"-sources and display all the
parsing information in the ECB-methods buffer.

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

(1) semantic supports some more "languages" like Phython, Makefiles and some
more. But these are the most important ones.

(2) Especially for C++ and C you can use any extension you want but these are
the most common ones!


File: ecb.info,  Node: Setting up CEDET/semantic,  Next: Non-semantic files,  Prev: General hints,  Up: Setting up Emacs

1.2.2 Setting up CEDET/semantic
-------------------------------

To ensure ECB and semantic are working correctly for all by semantic
supported languages you have to pay attention to the following aspects
concerning your Emacs-setup:

  1. Setting up CEDET/semantic itself

     This section implies that you either use Emacs >= 23.2 or that you have
     already successfully installed the CEDET-suite.

     For all semantic-supported file-types parsing files is done completely
     by semantic. ECB just displays the parsing results.

        * Users of Emacs >= 23.2: You just have to enable semantic by
          activating the semantic-mode. This can be done by adding code to
          your initialization-file (e.g. .emacs) like this:

             (semantic-mode 1)

          This should be placed BEFORE the statements which activate ECB.

          As an alternative you can use the `ecb-before-activate-hook' like
          follows:

             (add-hook 'ecb-before-activate-hook
                       (lambda () (semantic-mode 1)))

          This is a smarter way when you need semantic only if ECB is active.

        * Users of XEmacs or Emacs < 23.2: You should read carefully the file
          `INSTALL' shipped with the cedet-suite. In addition the
          CEDET-website offers a link to a "Gentle introduction to Cedet".
          It's worth to read it! You find it here:
          `http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html'
          If CEDET is not correctly installed then ECB can not setup semantic
          for its needs.


     *Minimum setup recommendation*: It is very useful to enable the
     `global-semantic-idle-scheduler-mode' and
     `global-semanticdb-minor-mode'. Read the manual of Emacs 23.2 or the
     manual of cedet/semantic how to do this. With CEDET-versions >= 1.0pre6
     this can be done by adding `semantic-load-enable-minimum-features' to
     your startup-file. Please read also the subsection "Jumping to the
     definition of external types" in *Note ECB Methods-window::.

  2. Checking your hooks (Only for XEmacs and Emacs < 23.2!)

     If you use Emacs > 23.2 you can ignore the following paragraphs.

     If you have already checked point (1.) and if you have still problems
     getting ECB/semantic working properly for your sources you should check
     the related major-mode hook. Every major-mode X has a hook with name
     "X-hook" which is evaluated after activating the major-mode (see above,
     2.), e.g. the hook for the major-mode `c++-mode' is `c++-mode-hook'.

     Semantic adds automatically during load-time a special "semantic-setup"
     to these major-mode hooks(1) in form of a "setup-function". Example: For
     c and c++ modes semantic adds `semantic-default-c-setup' to
     `c-mode-hook' and `c++-mode-hook'.

     If your own Emacs-setup (e.g. in `.emacs' or `site-lisp/site-start.el')
     overwrites such a major-mode-hook then semantic can not be activated for
     this major-mode and in consequence ECB can not work properly too!

     Check if your Emacs-setup uses somewhere `setq' for adding code to a
     major-mode-hook. *IMPORTANT*: Use `add-hook' instead of `setq'(2)!


If your source-files are "running" with correct `major-mode' and - in case of
XEmacs or Emacs < 23.2 - correct major-mode hooks ECB and semantic will do
what you expect them doing!

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

(1) Of course only for major-modes supported by semantic!

(2) `setq' replaces/overwrites the current value of a hook with the new value
whereas `add-hook' *adds* the new value to the old-value of the hook!


File: ecb.info,  Node: Non-semantic files,  Prev: Setting up CEDET/semantic,  Up: Setting up Emacs

1.2.3 Setup for file types not supported by semantic
----------------------------------------------------

From version 1.94 on ECB supports also parsing and displaying file-contents
for file-types not supported by semantic (i.e. there is no semantic-grammar
available for such file-types).

Such non-semantic file-types can often be parsed by imenu and/or etags. Both
of these parsing methods are now supported: ECB can display the results of
imenu and/or etags in its Method-buffer. ECB uses for this speedbar-logic.
Therefore the following speedbar options takes effect for this feature:

   - `speedbar-dynamic-tags-function-list'

   - `speedbar-tag-split-minimum-length'

   - `speedbar-tag-regroup-maximum-length'

   - `speedbar-tag-hierarchy-method'

Normally there should be no need for you to bother with these options,
because the default values are suitable for most situations! But if you are
not satisfied with the parsing/display results then you can change some of
these options.


File: ecb.info,  Node: First steps,  Prev: Setting up Emacs,  Up: Install and first steps

1.3 First steps after activating ECB first time
===============================================

This section of the ECB online-help is displayed automatically by ECB after
activating ECB first time and describes what are the first basic steps:

  1. Configure where ECB can find your sources:

     Call `M-x customize-option RET ecb-source-path RET'(1). This lets you
     customize the option `ecb-source-path' with the customize-feature of
     Emacs. This opens a customize-buffer where you can insert all the
     directories where ECB can find your source-files. Save your changes with
     the button "Save for future sessions" and then throw away this
     customize-buffer either by killing it with `M-x kill-buffer' or clicking
     at the button "Finish".

  2. Take a look at the most important options of ECB Call `M-x
     ecb-customize-most-important RET' and see a list of options which you
     should at least know that these options exist.

  3. Read the online-help of ECB:

     The online-help of ECB is available via

        - calling `M-x ecb-show-help',

        - pressing `C-c . h' or

        - using the menu "ECB".

     (The section you are currently reading is part of the online-help of ECB)

     The chapter "Common use-cases" is also very interesting!

  4. Start working with ECB.

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

(1) This means first hitting the keys `M' (Meta- or Alt-key) and `x'
simultaneously, inserting "customize-option" in the minibuffer, hitting
RETURN, inserting "ecb-source-path" in the minibuffer and finally hitting
RETURN again


File: ecb.info,  Node: Overview,  Next: Manual usage,  Prev: Install and first steps,  Up: Top

2 Overview
**********

ECB is a global minor-mode which offers a couple of "ECB-windows" for
browsing your sources comfortable with the mouse and the keyboard.

ECB offers some basic ECB-windows to browse your sources:
   - ECB-Directories for browsing directories

   - ECB-Sources for browsing source-files

   - ECB-Methods for browsing the contents of a source

   - ECB-History for a history for open or recently opened files

See *Note Basic ECB-windows:: for a detailled description what these basic
ECB-windows offer. See *Note ECB-windows:: for a general introduction in the
ECB-window-concept of ECB.

In addition ECB offers some add-on ECB-window for special purposes:
   - ECB-Analyse for some intellisense stuff like possible completions or
     local variables

   - ECB-Symboldef for displaying the documentation of current symbol under
     point

See *Note Add-on ECB-windows:: for a detailled description what these add-on
ECB-windows offer.

In addition to these "special" ECB-windows you have always an "edit-area"
where you can edit your source-files. The edit-area can be divided into
several "edit-windows" - as many as you need (*note The edit-area::). And at
the bottom of the ECB-frame a persistent "compilation-window" (also called
"compile-window") can be displayed (optional), where all the output of
Emacs-compilation (compile, grep etc.) and Emacs temp-buffers (help etc.) is
shown (*note Temp- and compile-buffers::).

The following "screenshot" illustrates the typical layout of the ECB-frame(1):

   ------------------------------------------------------------------
   |              |                                                 |
   |  Directories |                                                 |
   |              |                                                 |
   |--------------|                                                 |
   |              |                                                 |
   |  Sources     |                                                 |
   |              |                                                 |
   |--------------|                   Edit-area                     |
   |              |   (can be splitted in several edit-windows)     |
   |  Methods     |                                                 |
   |              |                                                 |
   |--------------|                                                 |
   |              |                                                 |
   |  History     |                                                 |
   |              |                                                 |
   ------------------------------------------------------------------
   |                                                                |
   |            Persistent Compilation-window (optional)            |
   |                                                                |
   ------------------------------------------------------------------

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

(1) This is only one example of the layouts ECB offers, see *Note Changing
the ECB-layout::


File: ecb.info,  Node: Manual usage,  Next: ECB-windows,  Prev: Overview,  Up: Top

3 How to use this manual
************************

*IMPORTANT*: You should have read the chapter *Note Overview:: before going
on reading the current chapter.

This chapter describes shortly the contents of the following chapters of this
manual so maybe you can find faster what you are searching for.

All ECB-windows of ECB (*note ECB-windows::)
     Gives an introduction into the concept of ECB-windows of ECB, what they
     are, which different types exist, how they look, how they can be used
     and last but not least what they do in detail, i.e. explains every
     ECB-window of ECB in detail.

Activation and Deactivation (*note Activation and Deactivation::)
     Describes how to activate and deactivate ECB and which different types
     of activation are possible.

Usage of ECB (*note Usage of ECB::)
     Describes in detail how to use ECB with mouse and keyboard, explains the
     concept of the edit-area and the persistent compile-window, describe how
     to change the window-layout and hide and show special windows, which
     stealthy background-tasks ECB performs and so on...

Customizing ECB (*note Customizing::)
     Gives an overview of the most important options of ECB and tell you
     something about do's and don'ts concerning customization of ECB. Lists
     all options of ECB and describe exactly the purpose of them.

Submitting a problem report (*note Submitting problem report::)
     Instructions what to do if you encounters problems with ECB.

Upgrading and downloading ECB (*note Upgrading::)
     Gives an introduction into the automatic option-upgrading-feature of ECB.

Common use-cases (*note Common use-cases::)
     How to deal with common (and also some special) situations and
     circumstances, so e.g. working with big and small screens, working with
     large directories, using the builtin version-control-support of ECB,
     parsing non-semantic-supported sources like perl, using hide-show,
     working best with eshell and JDEE and some window-managers of Emacs
     (like escreen or winring) and many more...

Entry points for Elisp programmers (*note Elisp programming::)
     All informations needed by programmers when using some ECB-concepts from
     within other elisp-libraries. This includes a full description how to
     use the ECB-independent library tree-buffer.el. Lists also all available
     hooks and describes with full working example how to program own layouts.

Conflicts and bugs of ECB (*note Conflicts and bugs::)
     Lists all currently known bugs and problems and gives well working
     work-arounds.

Frequently asked Questions (*note FAQ::)
     Take a look...

Command Index (*note Command Index::)
     List of all interactive commands of ECB

Option Index (*note Option Index::)
     List of all user-customizable options of ECB

Concept Index (*note Concept Index::)
     List of all concepts introduced by ECB



File: ecb.info,  Node: ECB-windows,  Next: Activation and Deactivation,  Prev: Manual usage,  Up: Top

4 All ECB-windows of ECB
************************

ECB displays a number of informational windows that allow for easy source
code navigation and overview. These informational windows are called
"ECB-windows". Each ECB-window is displayed in its own special window/buffer
which is dedicated and read-only.

There are some "basic" ECB-windows (e.g. for browsing directories and
sources) and some "add-on" ECB-windows for special purposes like displaying
the definition of the current symbol under point. This chapter describes all
ECB-windows of ECB in detail.

* Menu:

* Basic ECB-windows::           Description of the basic ECB-windows
* Add-on ECB-windows::          Description of additional ECB-windows


File: ecb.info,  Node: Basic ECB-windows,  Next: Add-on ECB-windows,  Prev: ECB-windows,  Up: ECB-windows

4.1 The basic ECB-windows of ECB
================================

ECB offers basic ECB-windows for browsing directory-structures, files of a
directory and contents of source-files (e.g. methods and variables). These
basic ECB-windows are build from a special class of ECB-windows, called
"tree-buffer". See *Note Tree-buffer basics:: for more details about the
functionality of tree-buffers. See *Note Tree-buffer styles:: to get an
impression about the look&feel of these tree-buffers.

In the following subsections these basic ECB-windows of ECB will be explained
in detail.

* Menu:

* Tree-buffer basics::          General introduction into tree-buffers
* Tree-buffer styles::          Displaying the trees with different styles
* ECB Directories-window::      Contents of the ECB Directories-window
* ECB Sources-window::          Contents of the ECB Sources-window
* ECB Methods-window::          Contents of the ECB Methods-window
* ECB History-window::          Contents of the ECB History-window


File: ecb.info,  Node: Tree-buffer basics,  Next: Tree-buffer styles,  Prev: Basic ECB-windows,  Up: Basic ECB-windows

4.1.1 General introduction into tree-buffers
--------------------------------------------

4.1.1.1 Content and structure of a tree-buffer
..............................................

ECB displays most of its informations (e.g. about directory-structures or
file-contents) in so called "tree-buffers" which means the display of such a
tree-buffer is structured in a tree consisting of "tree-nodes". Every line in
a tree-buffer displays exactly one tree-node. Each node can have any
arbitrary number of "children"-nodes. If a tree-node has no children then it
is called a "leaf".

Each tree-buffer of ECB is displayed in an own special ECB-window/buffer
which is read-only ie. not editable.

The difference between a natural tree like a fir and an ECB-tree 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.

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:

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

4.1.1.2 Possible actions for a tree-node
........................................

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 actions depends on the type of the tree-buffer. For
example clicking on a tree-node in the ECB-sources-buffer (which is the name
of a source-file) opens the relelated file in the edit-area of ECB (*note ECB
Sources-window::) whereas clicking onto a node in the ECB-methods-buffer
(which is the name of a tag in the current source-file displayed in the
edit-area) "jumps" to the location of this tag in the source-buffer in the
edit-area (*note ECB Methods-window::).

Almost every ECB-window of ECB offers a special popup-menu when clicking with
the right mouse-button (of course also possible via keyboard, see *Note Using
the keyboard::) 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).

See *Note ECB Directories-window::, *Note ECB Sources-window::, *Note ECB
Methods-window:: and *Note Add-on ECB-windows:: for a detailed description
which actions are triggered and which popup-menus are offered in all the
ECB-windows of ECB.

4.1.1.3 Sticky parent-node for tree-buffers
...........................................

In the header-line (only for GNU Emacs) of a tree-buffer always the
current-parent node of the first visible node is displayed (if there is a
parent node). So a user always has a good overview to which parent a node
belongs. This sticky node is exactly in the same manner clickable as all other
nodes (see above).

There is a option `ecb-tree-make-parent-node-sticky' which enabales/disables
this feature (default is enabled).

There is also an option `ecb-tree-stickynode-indent-string'. Normally there
is no need to bother with this option but if you encounter alignment-problems
with the sticky node in the headerline then take a look at this option,
because it allows to fix the problem.

This feature is only available for GNU Emacs >= 21.

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

(1) Of course using the keyboard is also possible, see *Note Using the
keyboard::.


File: ecb.info,  Node: Tree-buffer styles,  Next: ECB Directories-window,  Prev: Tree-buffer basics,  Up: Basic ECB-windows

4.1.2 Displaying the trees 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.

* Menu:

* Style basics::                Basic knowledge about the styles
* Ascii-based styles::          How to customize the ascii-styles
* Tree-buffers with images::    Which images are used for the tree
* Images for Methods-buffer::   Images for the tags in the Methods-buffer


File: ecb.info,  Node: Style basics,  Next: Ascii-based styles,  Prev: Tree-buffer styles,  Up: Tree-buffer styles

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

   - open ("[-]"): The control-symbol displayed for an opened tree-node which
     has several subnodes. Clicking onto this control closes the node.

   - close ("[+]"): The control-symbol displayed for a closed tree-node, i.e.
     an expandable node with subnodes but all subnodes are hidden. Clicking
     onto this control opened the node and displays its subnodes - if there
     are any. If it has no subnodes the empty-symbol will be displayed.

   - empty ("[x]"): The symbol displayed for an empty node. An empty node is a
     node which could have subnodes but has currently none.

   - leaf ("*"): The symbol displayed for a node which can not have any
     subnodes so it is a "leaf" in the tree.

   - guide (" |"): The symbol used for drawing vertical "guide-lines" for
     opened nodes.  See the example below.

   - no-guide ("  "): Sometimes invisible guide-lines are needed to draw the
     tree.

   - end-guide (" `"): The symbol used for the guide-line of the last subnode
     of an opened node.

   - handle ("-"): The symbol displayed before every subnode. Each handle is
     connected to a guide-line - either a normal guide or an end-guide.

   - no-handle (" "): An invisible handle.

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)


File: ecb.info,  Node: Ascii-based styles,  Next: Tree-buffers with images,  Prev: Style basics,  Up: Tree-buffer styles

4.1.2.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')(1):

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

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

(1) For a better look&feel of such a tree-buffer ECB displays only the last
subnode of an opened node with a handle!


File: ecb.info,  Node: Tree-buffers with images,  Next: Images for Methods-buffer,  Prev: Ascii-based styles,  Up: Tree-buffer styles

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

A special remark 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.


File: ecb.info,  Node: Images for Methods-buffer,  Prev: Tree-buffers with images,  Up: Tree-buffer styles

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


File: ecb.info,  Node: ECB Directories-window,  Next: ECB Sources-window,  Prev: Tree-buffer styles,  Up: Basic ECB-windows

4.1.3 ECB Directories-window
----------------------------

The ECB directories interactor is for browsing directories. The direct
children of the invisible root-node are called "source-path" and can be
defined with the option `ecb-source-path'. Each source-path is the
starting-node of the complete directory-structure below this path and can be
browsed with the directories-interactor.

When a sources ECB-window is contained in the current layout then per default
only directories and subdirectories are displayed in the directories
tree-buffer (the source-files are displayed in the sources tree-buffer - see
*Note ECB Sources-window::) but this can be changed with the option
`ecb-show-sources-in-directories-buffer'.

4.1.3.1 Usage of the directories ECB-window
...........................................

   * Select directories (and - if enabled - source files) in the
     "ECB-Directories" buffer by clicking a mouse button on the directory
     name or by hitting RETURN when the cursor is placed on the item line,
     see *Note Usage of ECB::.

     IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key
     while clicking with the primary mouse button (*note Using the mouse::)
     or RETURN (*note Using the keyboard::)) on a directory node in the this
     buffer then the directory-contents-cache for this directory will be
     refreshed and actualized.

   * Directory names with a "[+]" symbol after (or before) them can be
     expanded/collapsed by clicking on the symbol, pressing the TAB key
     (*note Using the keyboard::) when the cursor is placed on the package
     line or clicking a mouse button on the item, see *Note Using the mouse::.

   * Right clicking on an item will open a popup menu where different
     operations on the item under the mouse cursor can be performed. This
     popup-menu offers operations for version-control, dired, grep, some
     file-operations like creating a directory and commands to make a
     directory a source-path in the sense of `ecb-source-path'.

   * Pressing F2 will open the ECB customization group (*note Customizing::)
     in the edit window. F3 shows the online help in the edit-window.
     Pressing F4 in the ECB-directories buffer will offer adding a new
     source-path.

When source-files-nodes are displayed in the directories-buffer (see
`ecb-show-sources-in-directories-buffer') then for these nodes all
descriptions of section *Note ECB Sources-window:: are valid.

4.1.3.2 Activating/Displaying the directories ECB-window
........................................................

Either use one of the predefined layouts which contain the directories
ECB-window (*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create
a new ecb-layout via the command `ecb-create-new-layout' and add a buffer of
type "directories" into this new layout (*note Creating a new ECB-layout::).

4.1.3.3 Customizing the directories ECB-window
..............................................

See *Note ecb-directories:: for a list of all options currently available for
customizing this ECB-windows to your needs.


File: ecb.info,  Node: ECB Sources-window,  Next: ECB Methods-window,  Prev: ECB Directories-window,  Up: Basic ECB-windows

4.1.4 ECB Sources-window
------------------------

ECB offers a ECB-windows for displaying source-file-names of a certain
directory: The sources-window. It displays all source-file names of the
currently selected directory of the directories-ECB-window (*note ECB
Directories-window::).

The history-tree-buffer is a "flat" tree-buffers means all nodes are direct
children of the invisible root-node and can not be expanded.

4.1.4.1 Usage of the ECB-Sources-window
.......................................

   * Source files can be selected by clicking with the primary mouse button
     (*note Using the mouse::) or hitting RETURN (*note Using the keyboard::)
     on the source row in the "ECB-Sources"-window. The buffer of the selected
     source-file will be displayed in an edit-window - which one depends on
     the setting in `ecb-mouse-click-destination'.

     IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while
     clicking with the primary mouse button (*note Using the mouse::) or
     RETURN (*note Using the keyboard::)) on a source row in the
     ECB-Sources-windows then the source will not be displayed in an
     edit-window but it will be scanned in the background and all its
     contents (e.g. methods and variables) are listed in the "ECB
     Methods"-window (*note ECB Methods-window::. So you can get an overlook
     over the source without changing the buffer in the edit-window.

   * Clicking on the source file with the secondary mouse button or C-RETURN
     (*note Usage of ECB::) will open the source file in another edit window
     - which one depends on the setting in `ecb-mouse-click-destination'.

   * Right clicking on a source file (mouse-button 3) will open a popup menu
     where different operation on the item under the mouse cursor can be
     performed. This popup-menu offers operations for version-control, dired,
     grep, filtering the file-names and some file-operations like deleting
     the related file from disk.  In addition the ECB-Sources-window can be
     maximized via the popup-menu


4.1.4.2 Activating/Displaying the ECB-Sources-window
....................................................

Either use one of the predefined layouts which contain the sources ECB-window
(*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new
ecb-layout via the command `ecb-create-new-layout' and add a buffer of type
"sources" into this new layout (*note Creating a new ECB-layout::).

4.1.4.3 Customizing the ECB-Sources-window
..........................................

See *Note ecb-sources:: for a list of all options currently available for
customizing this ECB-window to your needs.


File: ecb.info,  Node: ECB Methods-window,  Next: ECB History-window,  Prev: ECB Sources-window,  Up: Basic ECB-windows

4.1.5 The ECB Methods-window
----------------------------

The "ECB-Methods" ECB-window contains all parsed and recognized tags of the
current source-buffer. It is called "Method-buffer" because ECB is mostly
designed for browsing sourcecode files and for programming-languages these
tags are often methods (and variables etc.) To simplify explanations we talk
in the following only about methods and variables - but in general the
method-buffer can contain any kind of tags (e.g. sections and subsections for
texinfo buffers).

Per default the content of the methods-ECB-window is automatically
synchronized and updated with current point of the current source-buffer in
the edit-area (*note ECB-window synchronizing::). This and other important
informations about usage of the powerful Methods-window of ECB can be found in
*Note The Methods window::.

4.1.5.1 Usage of the methods ECB-window
.......................................

   * When a node (e.g. method or variable) is selected with the primary mouse
     button (*note Using the mouse::) or RETURN (*note Using the keyboard::)
     the buffer in the edit-window (which one depends on the setting in
     `ecb-mouse-click-destination') will jump to the method/variable.

     IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key
     while clicking with the primary mouse button (*note Using the mouse::)
     or RETURN (*note Using the keyboard::)) on a node in this buffer then
     the edit-buffer will be narrowed to the selected tag (see also option
     `ecb-tag-visit-post-actions'). But this works only for sources parsed by
     semantic, not by imenu or etags!

   * Clicking on a node with the secondary mouse button or C-RETURN (*note
     Usage of ECB::) will jump to the method in another edit window - which
     one depends on the setting in `ecb-mouse-click-destination'.

   * Right clicking on a node will open a popup menu where different
     operation on the item under the mouse cursor can be performed. The
     popup-menu offers commands for filtering the displayed tree-nodes,
     hiding/narrowing the related tags in the source-buffer and
     expanding/collapsing one/all tree-nodes according to a certain
     expansion-level.


4.1.5.2 Activating/Displaying the methods ECB-window
....................................................

Either use one of the predefined layouts which contain the methods ECB-window
(*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new
ecb-layout via the command `ecb-create-new-layout' and add a buffer of type
"methods" into this new layout (*note Creating a new ECB-layout::).

4.1.5.3 Customizing the methods ECB-window
..........................................

See *Note ecb-methods:: for a list of all options currently available for
customizing this ECB-window to your needs.


File: ecb.info,  Node: ECB History-window,  Prev: ECB Methods-window,  Up: Basic ECB-windows

4.1.6 The ECB History-window
----------------------------

ECB offers a ECB-windows for displaying a history of currently open or
recently closed source-buffers, regardless of the directory the related file
belongs to.

Contrary to the ECB-sources-window the ECB-History-window can be flat but
needn't. Another difference to the ECB-sources window is that the History
displays not filenames but buffer-names for buffers which are either directly
related to a file or which are indirect-buffers with a base-buffer which is
related to a file. For a description of the indirect-buffer concept see the
Emacs manual (see command `clone-indirect-buffer' or `make-indirect-buffer'
for XEmacs).

*Please note*: The History of ECB is not meant to be a full replacement for
the Buffers-menu of (X)Emacs! It only displays buffers which are related to a
file (either directly or via indirect-buffer). All non-file-related buffers
(e.g. *Help*, *grep* etc.) will never be displayed in the ECB-History-window!

4.1.6.1 Usage of the ECB-History-window
.......................................

   * Buffers in the history can be selected by clicking with the primary
     mouse button (*note Using the mouse::) or hitting RETURN (*note Using
     the keyboard::) on the buffername-node in the "ECB-History"-window. The
     buffer of the selected buffer-name will be displayed in an edit-window -
     which one depends on the setting in `ecb-mouse-click-destination'.

     IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while
     clicking with the primary mouse button (*note Using the mouse::) or
     RETURN (*note Using the keyboard::)) on a node in the ECB-History-window
     then the related buffer will not be displayed in an edit-window but it
     will be scanned in the background and all its contents (e.g. methods and
     variables) are listed in the "ECB Methods"-window (*note ECB
     Methods-window::. So you can get an overlook over the buffer-contents
     without changing the buffer in the edit-window.

   * Clicking on a buffername-node with the secondary mouse button or
     C-RETURN (*note Usage of ECB::) will open the buffer in another edit
     window - which one depends on the setting in
     `ecb-mouse-click-destination'.

   * Right clicking on a buffername-node (mouse-button 3) will open a popup
     menu where different operation on the item under the mouse cursor can be
     performed.  This popup-menu offers operations for version-control,
     dired, grep, filtering the buffernames and some file-operations like
     deleting the related file from disk. In addition the ECB-History-window
     can be maximized or the bucketizing type (s.b. "Bucketizing the
     history") can be changed on the fly via popup-menu.


4.1.6.2 Activating/Displaying the ECB-History-window
....................................................

Either use one of the predefined layouts which contain the ECB-History-window
(*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new
ecb-layout via the command `ecb-create-new-layout' and add a buffer of type
"history" into this new layout (*note Creating a new ECB-layout::).

4.1.6.3 Dead buffers in the history
...................................

You can customize if ECB should remove the related buffername-node from the
history-window after killing a buffer. This is done with the option
`ecb-kill-buffer-clears-history'. See the documentation of this option for
the possible choices. If you decide that ECB should *not* remove the related
buffername-node then this is named a "dead" buffer in the history-window. It
is displayed with a special face (see `ecb-history-dead-buffer-face'),
default is a kind of grey.

You can use such a dead-buffer-node in the history as all other
buffername-nodes: ECB will reopen the related file in a buffer and perform the
action you have choosen (see above section "Usage of the ECB-History-window").

4.1.6.4 Indirect buffers in the history
.......................................

You can work with indirect buffers as well with direct buffers. See the
(X)Emacs manual for an introduction for indirect buffers (e.g. see the command
`clone-indirect-buffer' for GNU Emacs).

Indirect buffers are displayed with the face
`ecb-history-indirect-buffer-face', default is an italic outline.

There is an option `ecb-history-stick-indirect-buffers-to-basebuffer' which
allows to customize how ECB displays indirect buffers in the history-window:

If this option is `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'. Then the history contains something
like this:

   <base-buffer BB>
   <indirect-buffer 1 of BB>
   <indirect-buffer 2 of BB>
   <indirect-buffer 3 of BB>

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 contains something like:

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

Here the buffer with name "<base-buffer BB>" has three indirect-buffers which
are display as childrens of their base-buffer.

4.1.6.5 Bucketizing the history
...............................

ECB can display the history-contents "flat" or it can display buckets to
bucketize the contens according to certain criterias. This is done with the
option `ecb-history-make-buckets'. It allows bucketizing according to the
directory, the file-extension, the major-mode or a list of regular expression
- see the documentation of this option for details.

Here is an example for a history-window bucketized according to the major-mode
of the related buffers:

   [-] [c++-mode]
    |  headerfile-1.h
    |  headerfile-2.h
    |  codefile-1.cc
    `- codefile-2.cc
   [-] [emacs-lisp-mode]
    |  elisp-buffer-1.el
    |  elisp-buffer-1.el
    `- elisp-buffer-1.el
   [-] [makefile-mode]
    `- Makefile
   [-] [java-mode]
    |  java-buffer-1.java
    `- java-buffer-2.java

*Please note*: If `ecb-history-make-buckets' is nil then this is interpreted
as an empty list of regular-expressions and the history is display with
exactly one bucket. Use the value 'never if you want the? contents of the
history-window to be displayed "flat"!

You can change the bucketizing type on the fly via the popup-menu of the
history-window.

4.1.6.6 Customizing the ECB-History-window
..........................................

See *Note ecb-history:: for a list of all options currently available for
customizing this ECB-windows to your needs.


File: ecb.info,  Node: Add-on ECB-windows,  Prev: Basic ECB-windows,  Up: ECB-windows

4.2 Add-on ECB-windows of ECB
=============================

This chapter gives detailled informations about available add-on ECB-windows.
This includes basic desciptions what they do as well as how to use them.

* Menu:

* Semantic analyser::           Analyses and displays semantic context
* Symboldefinition::            Displays definition of current symbol


File: ecb.info,  Node: Semantic analyser,  Next: Symboldefinition,  Prev: Add-on ECB-windows,  Up: Add-on ECB-windows

4.2.1 Displaying the current semantic context via analyser
----------------------------------------------------------

The CEDET-suite contains the "semantic analyzer"(1) which is a library tool
that performs context analysis and can derive useful information.

Please see the related node in the info-manual of cedet/semantic for more
detailed informations about this tool and how to setup it for best performance
for your project needs.

The semantic-analyzer output can be used through a special ECB-window. This
interface lists details about the analysis, such as the current function,
local arguments and variables, details on the prefix (the symbol the cursor is
on), and a list of all possible completions (see
`semantic-analyze-possible-completions' for more details about completions
available via the semantic-analyser).

The analyser-ECB-window is of type tree-buffer. See *Note Tree-buffer
basics:: for basic informations how to use such a tree-buffer.

4.2.1.1 Usage of the analyser-ECB-window
........................................

   * When a node-name in the "Context"-bucket is selected with the primary
     mouse button (*note Using the mouse::) or RETURN (*note Using the
     keyboard::) the buffer in the edit-window (which one depends on the
     setting in `ecb-mouse-click-destination') will jump to the related
     entry. For strongly typed languages, this means you will jump to the
     definition of the variable, slot, or type definition.

   * Clicking on a node-name in the "Context"-bucket with the secondary mouse
     button or C-RETURN (*note Usage of ECB::) will jump to the related entry
     in another edit window - which one depends on the setting in
     `ecb-mouse-click-destination'.

   * If you click on a node-name in the "Completions"-bucket, then the text
     that was recently analyzed will be replaced with the name of the tag
     that was clicked on in the analyser-ECB-window.

   * Right clicking with the mouse (or with the keyboard, see *Note Using
     popup-menus::) onto a tree-node opens a popup-menu which allows to
     display additional (if available) informations to the current node.

4.2.1.2 Synchronizing the analyse-window
........................................

Per default the content of the analyser-ECB-window is automatically
synchronized and updated with current point of the current source-buffer in
the edit-area (see `ecb-analyse-buffer-sync' and most notably
`ecb-analyse-buffer-sync-delay') and *Note ECB-window synchronizing::).

In contrary to the sync-options of the basic ECB-windows(2) the default
synchronisation delay of the ECB-analyse-window is quite high: 2 seconds (see
`ecb-analyse-buffer-sync').

What is the reason for this: a small value like 0.25 as for the basic windows
would make the analyse-window quite unusable because then more or less after
each type (depends on how fast you are typing) the analyse window would be
synchronized with current point, which can be really annoying when there would
be hundreds of completions for the current point.

Imagine the following scenario: programming in emacs-lisp, typing
   (e
and then you make a short break, just a moment, but immediately ECB would call
the semantic-analyzer to analyse the current context for possible completions
(a.o.). You can imagine that there are even thousands of possible function
completions in emacs-lisp which beginns with "e". Getting all these and
displaying them in the analyse-window can take some time! Of course the whole
stuff is interruptable by any key-press so ECB will not be blocked but
nevertheless the will be a noticeable break in your typing.

Therefore it is strongly recommended to choose one of the following
possibilities:

   * Automatic synchronizing with long delay

     Set `ecb-analyse-buffer-sync-delay' to a value which is suitable for your
     programing and typing style, default is already to seconds.

   * Manually synchronizing on demand

       1. Switch off the automatic synchronizing for the ECB-analyse-window
          by setting the option `ecb-analyse-buffer-sync' to nil. Use always
          customize for this, never setq!

       2. Bind the command `ecb-analyse-buffer-sync' to a conveniant shortcut

       3. Synchronize the analyse-window exactly then when you need the
          context informations for current point (e.g. possible local
          variables or completions).

          But note that semantic already offers some intellisense commands
          which can help you on demand too! See the documentation of the
          semantic analyzer.


4.2.1.3 Interactive commands of the analyser-ECB-window
.......................................................

ECB offers the following commands for the analyser-ECB-window:

   - `ecb-analyse-buffer-sync'

   - `ecb-goto-window-analyse'

   - `ecb-maximize-window-analyse'

See *Note Interactive ECB commands:: for details about these commands.

4.2.1.4 Activating/Displaying the analyser-ECB-window
.....................................................

Either use one of the predefined layouts "left-analyse" or
"leftright-analyse" (e.g. via `C-c . l c') or create a new ecb-layout via the
command `ecb-create-new-layout' and add a buffer of type "other" and name
"analyse" into this new layout (*note Creating a new ECB-layout::).

4.2.1.5 Customizing the analyser ECB-window
...........................................

See *Note ecb-analyse:: for a list of all options currently available for
customizing this ECB-window to your needs.

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

(1) Note that ECB uses analyser (with s) whereas semantic uses analyzer (with
z).

(2) see *Note Basic ECB-windows:: and the options `ecb-basic-buffer-sync' and
`ecb-basic-buffer-sync-delay'.


File: ecb.info,  Node: Symboldefinition,  Prev: Semantic analyser,  Up: Add-on ECB-windows

4.2.2 Displaying the definition of the current symbol under point
-----------------------------------------------------------------


File: ecb.info,  Node: Activation and Deactivation,  Next: Usage of ECB,  Prev: ECB-windows,  Up: Top

5 Activation and Deactivation
*****************************

This chapter describes all aspects of activating and deactivating ECB.

* Menu:

* Standard activation::         How to manually (de)activate ECB
* Automatic activation::        Automatically (de)activating ECB

*IMPORTANT*: Regardless of the activation-type (standard or automatic) the
activation-process of ECB is always completely failure-save. This means any
error during any step of the activation-process forces a complete cleanup
(e.g. removing hooks, disabling advices etc.) of all settings ECB did (e.g.
adding hooks, activating advices etc.) until the failure. Therefore if
ECB-activation stops cause of a failure then you can be sure that your Emacs
has the same state as before the ECB-activation-start!


File: ecb.info,  Node: Standard activation,  Next: Automatic activation,  Prev: Activation and Deactivation,  Up: Activation and Deactivation

5.1 Standard activation and deactivation
========================================

Call `M-x ecb-activate' and `M-x ecb-deactivate' to activate or deactivate
ECB(1). If you want ECB started in a new frame see the option
`ecb-new-ecb-frame' (default is nil).  `ecb-activate' always raises and
selects the ECB-frame even if ECB is already started.

Because ECB is a global minor-mode it can also be (de)activated/toggled by
`M-x ecb-minor-mode'.

The following sequence of hooks is evaluated during activation of ECB:
  1. `ecb-before-activate-hook'

  2. <All actions for activation but no layout drawing>

  3. `ecb-activate-before-layout-draw-hook'

  4. `ecb-redraw-layout-before-hook'

  5. <Drawing the layout>

  6. `ecb-redraw-layout-after-hook'

  7. `ecb-activate-hook'

The following sequence of hooks is evaluated during deactivation of ECB:
  1. `ecb-before-deactivate-hook'

  2. <All actions for deactivation of ECB>

  3. `ecb-deactivate-hook'

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

(1) Activation is also possible via the menu "Tools -> Start Code Browser
(ECB)".


File: ecb.info,  Node: Automatic activation,  Prev: Standard activation,  Up: Activation and Deactivation

5.2 Automatic activation and deactivation
=========================================

There are two ways for auto. (de)activation ECB after Emacs-start and for
different window-configurations.

`ecb-auto-activate'
     This option is for auto. activating ECB after Emacs-startup. Set this to
     not nil and ECB will automatically be started after Emacs comes up.

`window-manager support'
     The window-manager support of ECB deactivates ECB when going to another
     window-configuration and reactivates ECB when coming back to the
     ECB-window-configuration. For all details about this see *Note
     Window-managers and ECB::.


File: ecb.info,  Node: Usage of ECB,  Next: Customizing,  Prev: Activation and Deactivation,  Up: Top

6 Usage of ECB
**************

This chapter describes in a detailed manner all aspects of using the Emacs
Code Browser.

* Menu:

* Using the mouse::             Working with the mouse
* Using the keyboard::          Working with the keyboard
* The edit-area::               How to use the edit-area
* Temp- and compile-buffers::   Displaying temp- and compilation-buffers
* The other window::            How the ``other window'' is determined
* The Methods window::          Using and customizing the Methods-window
* Filtering the tree-buffers::  Applying filters to the ECB-tree-buffers
* The ECB-layout::              Changing, customizing, redrawing, creating
* Hiding the ECB windows::      Hiding/Showing the ECB-windows
* Maximizing the ECB windows::  Maximizing the ECB-windows
* Back/forward navigation::     Back- and forward navigation like a browser
* ECB-window synchronizing::    Auto./manual synchronizing the ECB-windows
* Stealthy background tasks::   Stealthy background-tasks of ECB
* Interactive ECB commands::    All interactive user-commands of ECB


File: ecb.info,  Node: Using the mouse,  Next: Using the keyboard,  Prev: Usage of ECB,  Up: Usage of ECB

6.1 Working with the mouse in the ECB-windows
=============================================

Normally you get best usage if you use ECB with a mouse. ECB distinguishes
between a "primary" and a "secondary" mouse-button.

With the option `ecb-primary-secondary-mouse-buttons' the following
combinations of primary and secondary mouse-buttons are possible:

   - primary: mouse-2, secondary: C-mouse-2(1). This is the default.

   - primary: mouse-1, secondary: C-mouse-1

   - primary: mouse-1, secondary: mouse-2

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

6.1.1 The primary mouse-button
------------------------------

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

6.1.2 The POWER- or SHIFT-click
-------------------------------

A click with the primary mouse-button while the SHIFT-key is pressed is
called the POWER-click and does the following (depending on the ECB-buffer
where the POWER-click occurs):

   - ECB Directory: 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 an edit-window. This
     means it opens the clicked source only in the background and shows all
     its methods/variables in ECB-Methods; the buffer of the edit-window is
     not changed! This is very useful to get only an overlook for a certain
     source.

   - ECB Methods: Narrowing to the clicked method/variable/ect... (see
     `ecb-tag-visit-post-actions'). But this works only for sources parsed by
     semantic, not by imenu or etags!

Per default the complete node-name of an item in a tree-buffer is displayed in
the echo-area if the mouse moves over it, regardless if the related window is
the active one or not. You get the same effect always after a POWER-click. In
general: For each tree-buffer there is an option `ecb-*-show-node-info'
(replace "*" with directories, sources, methods, history or analyse, e.g.
`ecb-directories-show-node-info' is the option for the
ECB-directories-window.): you can specify in a detailed manner for the named
ECB tree-buffer when and which node-info should be displayed in the
minibuffer.

6.1.3 The secondary mouse-button
--------------------------------

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

6.1.4 The right mouse-button
----------------------------

In each ECB-buffer mouse-3 (= right button) opens a special context
popup-menu for the clicked item where you can choose several senseful actions.

With the options `ecb-directories-menu-user-extension',
`ecb-sources-menu-user-extension', `ecb-methods-menu-user-extension' and
`ecb-history-menu-user-extension' you can add statically new commands to the
popup-menus. See the docstring of `ecb-directories-menu-user-extension' for
more details.

With the options `ecb-directories-menu-user-extension-function',
`ecb-sources-menu-user-extension-function',
`ecb-methods-menu-user-extension-function' and
`ecb-history-menu-user-extension-function' you can add new commands to the
popup-menus in a dynamic manner. See the docstring of
`ecb-directories-menu-user-extension-function' for more details.

With the options `ecb-directories-menu-sorter', `ecb-sources-menu-sorter',
`ecb-methods-menu-sorter' and `ecb-history-menu-sorter' you can even
re-arrange all the entries of the popup-menus.

6.1.5 Horizontal scrolling with the mouse
-----------------------------------------

In each tree-buffer of ECB you can easily scroll left and right with the
mouse if the option `ecb-tree-easy-hor-scroll' is not `nil'.

The reason for this is: 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.

ECB offers three ways for smoothly hor. scrolling with GNU Emacs if
`ecb-tree-easy-hor-scroll' is a positive integer-value S:

   * 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 \(resp right)
     edge of the modeline you will scroll left \(resp. right) with
     scroll-step S.

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

This is NOT done for XEmacs cause of its horizontal scrollbars. If you want
scrolling left and right with the mouse in XEmacs then activate the
horizontal scrollbars.

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

(1) means mouse-2 while CTRL-key is pressed.


File: ecb.info,  Node: Using the keyboard,  Next: The edit-area,  Prev: Using the mouse,  Up: Usage of ECB

6.2 Working with the keyboard in the ECB-windows
================================================

ECB offers the `ecb-mode-map' which binds the most important functions of ECB
to keys so you can easily use ECB in every window(1) without a mouse.

IMPORTANT: Do not modify `ecb-mode-map' directly! The option `ecb-key-map'
defines all ECB keybindings, including a common prefix-key (This is by
default `C-c .'). If there are conflicts with other minor-modes or packages
you can define very easy another prefix. Please read carefully the
description of `ecb-key-map' (*note ecb-general::).!

The following sections describe special topics about using the keyboard in
the ECB-tree-buffers:

* Menu:

* Navigation/Selection::        Keyboard navigation/selection in a tree-buffer
* Incremental search::          Find nodes as fast as possible
* Personal tree-keybindings::   Adding personal keybindings to a tree-buffer
* Using popup-menus::           Using the popup-menus from keyboard.

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

(1) Regardless if a tree-window or an edit-window


File: ecb.info,  Node: Navigation/Selection,  Next: Incremental search,  Prev: Using the keyboard,  Up: Using the keyboard

6.2.1 Navigation and Selection in a tree-buffer
-----------------------------------------------

In the ECB-buffers RETURN and TAB are the most important keys:

   * RETURN does the same as the primary button and C-RETURN does the same as
     the secondary button. S-RETURN is the same as the SHIFT-click or
     POWER-click. The terms "primary", "secondary", "SHIFT-" and
     "POWER-click" are explained in *Note Using the mouse::. See also the
     option `ecb-tree-do-not-leave-window-after-select' and the function
     `ecb-toggle-do-not-leave-window-after-select' which is bound to `C-t' in
     each tree-buffer of ECB!

     For all RETURN (and S-RETURN and C-RETURN) hits the position of the
     point within the current node-line is irrelevant! This is for
     conveniance.

   * TAB always expands or collapses expandable nodes.

The RETURN and TAB keys can not be (re)defined with `ecb-key-map'!

If you set `ecb-tree-navigation-by-arrow' to not nil then the arrow keys work
in the ECB tree-window in the following smart way:

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

   * Right-arrow: If node is expandable but not expanded then it will be
     expanded. Otherwise (i.e. current node is either not expandable or
     already expanded) point jumps to the next following node (which is the
     first subnode in case of an already expanded node or simply the next
     node in the following line).

   * Up- and down-arrow: 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 `ecb-tree-expand-symbol-before'
     is not nil) or of the displayed node-name. Or with other words: The
     first non-indentation and non-guide-line (see `ecb-tree-buffer-style')
     character of a node (*note Tree-buffer styles::).


File: ecb.info,  Node: Incremental search,  Next: Personal tree-keybindings,  Prev: Navigation/Selection,  Up: Using the keyboard

6.2.2 Incremental search for a node in current tree-buffer
----------------------------------------------------------

Each display-able key (e.g. all keys normally bound to `self-insert-command')
is appended to the current search-pattern. The tree-buffer tries to jump to
the first node which matching the current search-pattern either as substring
or as prefix (see below). If no match is found then nothing is done. There
are some special keys:

   * `backspace' and `delete': Delete the last character from the
     search-pattern.

   * `home': Delete the complete search-pattern

   * `end': Expand either to a complete node if current search-pattern is
     already unique or expands to the greatest common substring or prefix of
     the nodes. If there are at least two nodes with the same greatest
     common-prefix than every hit of `end' jumps to the next node with this
     common prefix.

For better overlooking the current search-pattern is shown in the echo area.
After selecting a node with RET the search-pattern is cleared out. With
`ecb-tree-incremental-search' you can specify if the current search-pattern
must be a real prefix of the node (default) or if any substring is matched.

For faster and easier finding the right node in a ecb-window the incremental
search ignores the following non interesting stuff:

   - any leading spaces

   - expand/collapse-buttons: [+] rsp. [-]

   - protection-signs (+, -, #) in the method-window if uml-notation is used

   - variables types or return-types in front of variable- or method-names.

   - const specifier for variables

This means: Just type in the prefix (rsp. a substring) of a class-,
variable-, method-, directory- or filename and ECB will bring you as fast as
possible to the node you want. Incremental node-search uses the value of
`case-fold-search'.

Tip: The `ecb-minor-mode' offers you in the `ecb-mode-map' (customizable via
`ecb-key-map') some keys for selecting every window of the ecb-frame. This
makes window-selection a childﾴs play. For example you can jump into the
method-window by hitting `C-c . gm'.


File: ecb.info,  Node: Personal tree-keybindings,  Next: Using popup-menus,  Prev: Incremental search,  Up: Using the keyboard

6.2.3 Adding personal keybindings for the tree-buffers
------------------------------------------------------

There are five hooks which can be used for adding personal keybindings to the
ECB tree-buffers:

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

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

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

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

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

These hooks are called directly after tree-buffer creation so they can be
used to add personal local keybindings(1) either to all tree-buffers
(`ecb-common-tree-buffer-after-create-hook') or just to a certain
tree-buffer. Here is a list which keys MUST NOT be rebound:

   * `RET' and all combinations with `Shift' and `Ctrl': Used for selecting
     nodes in all tree-buffers.

   * `TAB': Used for expanding/collapsing nodes in all tree-buffers.

   * `C-t': Used for toggling "do not leave window after selection" in all
     tree-buffers, see command `ecb-toggle-do-not-leave-window-after-select'.

   * All self-inserting characters: Used for easy and fast navigation in all
     tree-buffers, *Note Incremental search::.

   * `F2', `F3', `F4': Used for customizing ECB, adding source-path in the
     directories buffer.

The following example binds `C-a' to some useful code in ALL tree-buffers and
`C-d' to even more useful code ONLY in the directories buffer:

   (add-hook 'ecb-common-tree-buffer-after-create-hook
             (lambda ()
                (local-set-key (kbd "C-a")
                               (lambda ()
                                  (interactive)
                                  (message "ECB is great!")))))

   (add-hook 'ecb-directories-buffer-after-create-hook
             (lambda ()
                (local-set-key (kbd "C-d")
                               (lambda ()
                                  (interactive)
                                  (message "ECB is wonderful!")))))

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

(1) To be more general: They can be used to run any arbitrary lisp code after
a tree-buffer creation!


File: ecb.info,  Node: Using popup-menus,  Prev: Personal tree-keybindings,  Up: Using the keyboard

6.2.4 Using the popup-menu of a tree-buffer from keyboard.
----------------------------------------------------------

A popup-menu of a tree-buffer can be activated from keyboard with the command
`tree-buffer-show-menu-keyboard' which is bound to `M-m' in every
tree-buffer. How the popup-menu is displayed depends if this command is
called with a prefix-argument or not:

If called without a prefix-arg then the popup-menu is displayed graphically
as if it would be activated via mouse (for GNU Emacs this works perfectly but
for XEmacs there is a bug which results in a wrong menu-position - but the
menu itself works also with XEmacs).

If called with a prefix-arg (`C-u M-m') then the popup-menu is displayed with
the tmm-mechanism (like the Emacs-[menu-bar] is displayed when `tmm-menubar'
is called). This tmm-display is only available for GNU Emacs.


File: ecb.info,  Node: The edit-area,  Next: Temp- and compile-buffers,  Prev: Using the keyboard,  Up: Usage of ECB

6.3 Working with the edit-window(s) of the edit-area
====================================================

ECB offers you all what you need to work with the edit-area as if the
edit-windows of the edit-area would be the only windows of the ECB-frame.

ECB advices the following user-commands so they work best with ECB:

   - `balance-windows'

   - `delete-other-windows'

   - `delete-window'

   - `delete-windows-on'

   - `display-buffer'

   - `shrink-window-if-larger-than-buffer'

   - `split-window'

   - `split-window-horizontally'

   - `split-window-vertically'

   - `switch-to-buffer'

   - `switch-to-buffer-other-window'

   - `other-window'

   - `other-window-for-scrolling'

The behavior of the adviced functions is (slightly simplified):

   * All these adviced functions behaves exactly like their corresponding
     original functions but they always act as if the edit-window(s) of ECB
     would be the only window(s) of the ECB-frame. So the edit-window(s) of
     ECB seems to be a normal Emacs-frame to the user. This means that you
     can split and delete edit-windows without any restriction - ECB ensures
     that neither the special ECB-windows nor the compile-window will be
     damaged.

   * If there is a persistent compile-window (*note Temp- and
     compile-buffers::) then all compilation-buffers in the sense of
     `ecb-compilation-buffer-p' will be displayed in the compile-window.

   * If called in another frame than the ECB-frame these functions behave
     exactly like the not adviced original versions!

*Please note*: All these advices are only enabled when ECB is enabled.

Another interesting option in the context of the edit-window and these
adviced functions is `ecb-layout-always-operate-in-edit-window'!

6.3.1 Documentation of the adviced window functions
---------------------------------------------------

This section describes for every adviced window function (s.a.) how it
differs from the original version. Only the differences are mentioned, so if
you want the full documentation of such a function call `describe-function'
or `C-h f'.

 -- Command: other-window ARG &optional ALL-FRAMES
     Around-advice `ecb': The ECB-version of `other-window'.  Works exactly
     like the original function with the following ECB-adjustment: The
     behavior depends on `ecb-other-window-behavior'.

 -- Command: delete-window &optional WINDOW
     Around-advice `ecb': The ECB-version of `delete-window'.  Works exactly
     like the original function with the following ECB-adjustment:

     If optional argument WINDOW is nil (i.e. probably called interactively):
     If called in a splitted edit-window then it works like as if all the
     edit-windows would be the only windows in the frame.  This means the
     current edit-window which contains the point will be destroyed and its
     place will be occupied from another one. If called in an unsplitted
     edit-window then nothing is done. If called in the compile-window of ECB
     then the compile-window will be hidden (like with
     `ecb-toggle-compile-window'). If called in an ecb-window of the current
     ECB-layout there are two alternatives:

        * If the function is contained in
          `ecb-layout-always-operate-in-edit-window' the right edit-window is
          selected (depends on the value of the option
          `ecb-mouse-click-destination') and does then itﾴs job.

        * Otherwise the behavior depends on the value of the option
          `ecb-advice-window-functions-signal-error'.

     If optional argument WINDOW is a living window (i.e. called from
     program): If WINDOW is an edit-window then this window is deleted, if
     WINDOW is the compile-window then it will be hidden and otherwise the
     behavior depends on `ecb-advice-window-functions-signal-error'.

 -- Command: delete-other-windows &optional WINDOW
     Around-advice `ecb': The ECB-version of `delete-other-windows'. Works
     exactly like the original function with the following ECB-adjustment:

     If optional argument WINDOW is nil (i.e. probably called interactively):
     If called in a splitted edit-window then it works like as if all the
     edit-windows would be the only windows in the frame.  This means all
     other edit-windows besides the current edit-window which contains the
     point will be destroyed and the current edit-window fills the whole
     edit-area. Neither the special ecb-windows nor the compile-window will
     be destroyed!

        * If called in an unsplitted edit-window then either the
          compile-window will be hidden (if there is one) otherwise nothing
          is done.

        * If called in one of the ecb-windows then the current one is
          maximized, i.e. the other ecb-windows (not the edit-windows!) are
          deleted.

        * If called in the compile window there are two alternatives:

             - If the function is contained in
               `ecb-layout-always-operate-in-edit-window' the right
               edit-window is selected (depends on the value of the option
               `ecb-mouse-click-destination') and then it does itﾴs job.

             - Otherwise the behavior depends on the value of the option
               `ecb-advice-window-functions-signal-error'.

     If optional argument WINDOW is a living window (i.e. called from
     program): If WINDOW is an edit-window then this window is maximized
     (i.e. the other edit-window is deleted) if there are more at least 2
     edit-windows otherwise the compile-window is deleted (if there is one).
     If WINDOW is an ecb-window then only the other ecb-windows are deleted
     and in all other cases the behavior depends on
     `ecb-advice-window-functions-signal-error'.

 -- Command: delete-windows-on BUFFER &optional FRAME
     Around-advice `ecb': The ECB-version of `delete-windows-on'.  Works
     exactly like the original function with the following ECB-adjustment:

     An error is reported if BUFFER is an ECB-tree-buffer. These windows are
     not allowed to be deleted.

 -- Command: split-window &optional WINDOW SIZE HORFLAG
     Around-advice `ecb': The ECB-version of `split-window'.  Works exactly
     like the original function with the following ECB-adjustment:

     If called for a not-edit-window in the `ecb-frame' it stops with an
     error if `split-window' is not contained in the option
     `ecb-layout-always-operate-in-edit-window'! Besides this (e.g.  called
     for a window in another frame than the `ecb-frame') it behaves like the
     original version.

 -- Command: split-window-horizontally
     Around-advice `ecb': The ECB-version of `split-window-horizontally'.
     Works exactly like the original function with the following
     ECB-adjustment:

     If called in any other window of the current ECB-layout it stops with an
     error if this `split-window-horizontally' is not contained in the option
     `ecb-layout-always-operate-in-edit-window'!

 -- Command: split-window-vertically
     Around-advice `ecb': The ECB-version of `split-window-vertically'. Works
     exactly like the original function with the following ECB-adjustment:

     If called in any other window of the current ECB-layout it stops with an
     error if this `split-window-vertically' is not contained in the option
     `ecb-layout-always-operate-in-edit-window'!

 -- Command: display-buffer BUFFER &optional NOT-THIS-WINDOW FRAME
     Around-advice `ecb': Makes this function compatible with ECB if called
     in or for the ecb-frame. It displays all buffers which are
     "compilation-buffers" in the sense of `ecb-compilation-buffer-p' in the
     compile-window of ECB. If the compile-window is temporally hidden then
     it will be displayed first.

     If there is no compile-window (`ecb-compile-window-height' is nil) then
     it splits the edit-window if unsplitted and displays BUFFER in another
     edit-window but only if `pop-up-windows' is not nil (otherwise the
     edit-window will not be splitted).

     All buffers which are not "compilation-buffers" in the sense of
     `ecb-compilation-buffer-p' will be displayed in one of the edit-area and
     `display-buffer' behaves as if the edit-windows would be the only
     windows in the frame.

     If BUFFER is contained in `special-display-buffer-names' or matches
     `special-display-regexps' then `special-display-function' will be called
     (if not nil). But this behavior depends on the value of the option
     `ecb-ignore-special-display'. The values of `same-window-buffer-names'
     and `same-window-regexps' are supported as well.

     See the option `ecb-ignore-display-buffer-function'!

     If called for other frames it works like the original version.

 -- Command: switch-to-buffer BUFFER &optional NORECORD
     Around-advice `ecb': The ECB-version of `switch-to-buffer'.  Works
     exactly like the original but with the following enhancements for ECB:

     "compilation-buffers" in the sense of `ecb-compilation-buffer-p' will be
     displayed always in the compile-window of ECB (if
     `ecb-compile-window-height' is not nil) - if the compile-window is
     temporally hidden then it will be displayed first. If you do not want
     this you have to modify the options `ecb-compilation-buffer-names',
     `ecb-compilation-major-modes' or `ecb-compilation-predicates'.

     If called for non "compilation-buffers" (s.a.) from outside the
     edit-area of ECB it behaves as if called from an edit-window if
     `switch-to-buffer' is contained in the option
     `ecb-layout-always-operate-in-edit-window'. Otherwise an error is
     reported.

 -- Command: switch-to-buffer-other-window BUFFER &optional FRAME
     Around-advice `ecb': The ECB-version of `switch-to-buffer-other-window'.
     Works exactly like the original but with some adaptions for ECB so this
     function works in a "natural" way:

     If called in any special ecb-window of the current ECB-layout then it
     goes always to an edit-window (which one depends on the setting in
     `ecb-mouse-click-destination') and then goes on as if called from this
     edit-window.

     If a compile-window is used (i.e. `ecb-compile-window-height' is not
     nil) then "compilation-buffers" in the sense of
     `ecb-compilation-buffer-p' are always displayed in the compile-window.
     If the compile-window is temporally hidden then it will be displayed
     first. If no compile-window is used it behaves like the original.

     If called from within the compile-window then "compilation-buffers" will
     be displayed still there and all other buffers are displayed in one of
     the edit-windows - if the destination-buffer is already displayed in one
     of the edit-windows then this one is used otherwise it behaves like the
     original.

     If called within an edit-window it behaves like the original function
     except for compilation-buffers (if a compile-window is used, see above).

 -- Function: other-window-for-scrolling
     Around-advice `ecb': This function determines the window which is
     scrolled if any of the "other-window-scrolling-functions" is called
     (e.g. `scroll-other-window'):

     If the option `ecb-scroll-other-window-scrolls-compile-window' is not
     nil (maybe set by `ecb-toggle-scroll-other-window-scrolls-compile') and a
     compile-window is visible then always the current buffer in the
     compile-window is scrolled!

     Otherwise it depends completely on the setting in
     `ecb-other-window-behavior'.

 -- Command: balance-windows
     Around-advice `ecb': When called in the `ecb-frame' then only the
     edit-windows are balanced.


File: ecb.info,  Node: Temp- and compile-buffers,  Next: The other window,  Prev: The edit-area,  Up: Usage of ECB

6.4 Temp- and compile-buffers display in ECB
============================================

If you call any help in Emacs, e.g. by calling `describe-function', or if you
do a completion in the minibuffer, then Emacs displays the result-buffer in
another window. This behavior you have also in ECB.

6.4.1 Standard Emacs behavior
-----------------------------

6.4.1.1 Gnu Emacs 21.x, 22.x and XEmacs 21.4:
.............................................

If the edit-area is already splitted into at least two edit-windows then the
temp-buffer is displayed in another edit-window otherwise the edit-area will
be splitted first vertically into two edit-windows, one above the other. The
variables `temp-buffer-max-height' and `temp-buffer-resize-mode' (for GNU
Emacs) and `temp-buffer-shrink-to-fit' (for XEmacs) work also correctly with
ECB.

Same for all completion-buffer and "compile"-like output-buffers (e.g. after
a `compile' or `grep') and the variable `compilation-window-height'(1).

6.4.1.2 Gnu Emacs 23.x
......................

Gnu Emacs 23 has a much smarter window-manager for displaying temporary
buffers (like help-buffers) and "compile"-buffers (like real compilation
outputs but also grep-outputs, completions etc.). Therefore ECB uses
completely the logic of Emacs 23 and does exactly what Emacs 23 would do
without activated ECB: This means mainly that the split-behavior depends on
the settings of the options `split-width-threshold' and
`split-height-threshold'.

*Please note*: If you are wondering why displaying temporary-buffers (like
help, compile, grep, completion etc.) shows different behavior compared to
deactivated ECB, then you probably have to adjust the values of the options
`split-width-threshold' and `split-height-threshold' to the sizes of the
edit-area of ECB (at least nearly).

This is default behavior of ECB. But there is also another way to display
such buffers: Using a persistent extra window at the bottom of the ECB-frame,
named the "compile-window":

6.4.2 Using a persistent compile window
---------------------------------------

With the option `ecb-compile-window-height' you can define if the ECB layout
should contain per default a compile-window at the bottom (just specify the
number of lines which should be used for the compile-window at the bottom of
the frame). If "yes" ECB displays all buffers for which the function
`ecb-compilation-buffer-p' returns not nil (e.g. all output of
compilation-mode (compile, grep etc.) or all temp-buffers like
*Help*-buffers) in this special window.

In general: With the options `ecb-compilation-buffer-names',
`ecb-compilation-major-modes' and `ecb-compilation-predicates' you can define
which buffers should be displayed in the compile-window of ECB (for example
if you call `switch-to-buffer' or `display-buffer' or if you run `compile' or
if you display *Help*-buffers). Per default these are all temp-buffers like
*Help*-buffers, all compile- and grep buffers, *Occur*-buffers etc. See the
default values of these options.

With the command `ecb-toggle-compile-window' (bound to `C-c .  \') you can
toggle the visibility of the compile-window (*note Interactive ECB
commands::).

There are some more useful options and commands related to the compile-window
of ECB (to see all options for the compile-window see the customization group
*Note ecb-compilation::):

   * With the option `ecb-compile-window-temporally-enlarge' you can allow
     Emacs to enlarge temporally the ECB-compile-window in some situations.
     Please read the comment of this option. See also the description of the
     command `ecb-toggle-compile-window-height'.

   * With the option `ecb-enlarged-compilation-window-max-height' you specify
     how `ecb-toggle-compile-window-height' should enlarge the compile-window.

   * With the command `ecb-cycle-through-compilation-buffers' (*note
     Interactive ECB commands::) you can cycle through all current open
     compilation-buffers (in the sense of `ecb-compilation-buffer-p') very
     fast.

ECB offers the same compile-window functionality regardless if the ECB-window
are hidden or not. The state of the compile-window will be preserved when
toggling the ecb-windows or when maximizing one ecb-windows! So you have the
advantage of one special window for all help-, grep or compile-output (see
above) also when the ecb-windows are hidden - a window which will not be
deleted if you call `delete-other-windows' (bound to `C-x 1') for one of the
edit-windows. In general: All features of the compile-window work with hidden
ecb-windows exactly as when the ecb-windows are visible.

6.4.3 What to do if there are problems with the compile-window
--------------------------------------------------------------

Normally displaying temp- and compilation-buffers (or more general:
displaying buffer for which `ecb-compilation-buffer-p' is not nil) should
work reliable. But if there are problems which you can not handle with the
options `ecb-compilation-buffer-names', `ecb-compilation-major-modes' or
`ecb-compilation-predicates' then please go on like follows:

  1. Set the option `ecb-layout-debug-mode' to not nil.

  2. Reproduce the wrong behavior exactly by repeating all the operations
     which lead to the problem. If possible then restart Emacs before
     reproducing the problem so you can begin from the beginning!

  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"

6.4.4 Handling special-display-buffers
--------------------------------------

Emacs offers three options for a special-display-handling of certain buffers:
`special-display-function', `special-display-buffer-names' and
`special-display-regexps' (see the Emacs manual for a description of these
options). ECB offers an option `ecb-ignore-special-display' for specification
in which situations ECB should take account for the values of these
special-display-options.

Default-behavior of ECB is to ignore these special-display-options when a
persistent compile-window is active (i.e.  `ecb-compile-window-height' is not
nil). But with `ecb-ignore-special-display' you can tell ECB, that either
always the special-display-options should be ignored as long as ECB is active
or that they should be never igored regardless if a persistent compile-window
is set or not. In the latter case using `display-buffer' or `pop-to-buffer'
takes always account for the values of these options - like the original
behavior of Emacs.

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

(1) It goes without saying that is is also true for `grep-window-height' and
all other "compile"-modes.


File: ecb.info,  Node: The other window,  Next: The Methods window,  Prev: Temp- and compile-buffers,  Up: Usage of ECB

6.5 How the "other window" is determined by ECB
===============================================

Normally all windows in an Emacs-frame are arranged in a cyclic order and
window-selecting-commands like `other-window' or window-scrolling-commands
like `scroll-other-window' choose simply the next(1) window after the current
window as "other window".

6.5.1 "Other window"-basics in ECB
----------------------------------

With a typical window-layout of ECB such a cyclic order of *all* windows in
the ECB-frame does not make sense because it would be not very intuitive and
against that what the user wants to "say" when calling `other-window' or
`scroll-other-window'.

Therefore ECB divides the whole set of windows of the ECB-frame in several
subsets:

   * The edit-windows of the edit-area

   * The special tree-windows for browsing-tasks

   * The compile-window at the bottom (if there is one)

   * The minibuffer-window of the ECB-frame (if active)

Each of these subsets will be treated as a cyclic ordered subset, i.e.  all
windows in each of these subsets are ordered as the function `walk-windows'
would visit the windows when the windows of a subset would be the only
windows of a frame(2).

6.5.2 Builtin "other window" behaviors of ECB
---------------------------------------------

ECB now offers to specify the behavior of commands like `other-window' or
`scroll-other-window' within the ECB-frame. This can be done with the option
`ecb-other-window-behavior'. This option offers several builtin behaviors:

   * All windows of the ECB-frame are considered

     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 the windows of the edit-area are considered

     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
     all windows are taken into account.

   * The edit-windows and the compile-window are considered

     Like above but the compile-window will be added to the subset of the
     edit-windows.

   * Behave as smart and intuitive as possible

     This is the default behavior of ECB. 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.

Regardless of the different behaviors 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.

6.5.3 User-defined "other window" behavior
------------------------------------------

In addition to the builtin "other window" behaviors ECB offers a user to
completely define for himself how ECB should choose another window for
scrolling it or selecting it. This can be done with the option
`ecb-other-window-behavior' too because this option can also have a
function-symbol as value:

Such a 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 than 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.

Here is an example for such a function:

   (defun ecb-get-other-window-smart (win-list
                                      edit-win-list
                                      ecb-win-list
                                      comp-win
                                      minibuf-win
                                      point-loc
                                      nth-window)
     "Implements the smart-setting of `ecb-other-window-behavior'."
     (if minibuf-win
         ;; if we have an active mini-buffer we delegate this to
         ;; `ecb-get-other-window-minibuf-active'
         (ecb-get-other-window-minibuf-active win-list
                                              edit-win-list
                                              ecb-win-list
                                              comp-win
                                              minibuf-win
                                              point-loc
                                              nth-window)
       ;; here we have no active minibuffer!
       (let ((nth-win (or nth-window 1)))
         (cond ((equal point-loc 'ecb)
                (ecb-next-listelem ecb-win-list (selected-window) nth-win))
               ((equal point-loc 'compile)
                (if (= nth-win 1)
                    (or (and ecb-last-edit-window-with-point
                             (window-live-p ecb-last-edit-window-with-point)
                             ecb-last-edit-window-with-point)
                        (car edit-win-list))
                  (ecb-next-listelem (append edit-win-list
                                             (list (selected-window)))
                                     (selected-window)
                                     nth-win)))
               (t ;; must be an edit-window
                (ecb-next-listelem (append edit-win-list
                                           (if (and comp-win
                                                    (= (length edit-win-list)
                                                       1))
                                               (list comp-win)))
                                   (selected-window)
                                   nth-win))))))

This example implements the builtin smart behavior described above.

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

(1) `other-window' allows to select ARG'th different window, i.e. the window
ARG steps away from current window in the cyclic order of the windows

(2) `other-window' uses the same window-ordering as `walk-windows'


File: ecb.info,  Node: The Methods window,  Next: Filtering the tree-buffers,  Prev: The other window,  Up: Usage of ECB

6.6 Using and customizing the ECB-Methods window
================================================

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. Therefore we have
to introduce some terminology:

   - "semantic-sources": These are file-types for which a semantic grammar is
     available, so the files are parse-able by semantic. These sources are
     supported best by ECB and most of the following options and descriptions
     are related to these file-types. Examples are programming-sources like
     C++, C, Java, Emacs-Lisp and Texinfo-file and some more.

   - "non-semantic-sources": For these files there is no semantic-grammar
     available so they can not be parsed by semantic. Examples are Perl-,
     LaTeX- and TeX-files. But for many of these files imenu and/or etags
     parsers exist. ECB supports now parsing and displaying these file-types
     too and it uses for this some speedbar-logic.

This chapter describes how to use and customize the Methods-buffer of ECB.

* Menu:

* Visiting tags::               Possible actions after visiting a tag
* Expanding::                   Explicit and automatic expanding
* Customizing the display::     How to customize the Methods-buffer display
* Updating Methods-window::     Updating Methods with contents of current buffer
* Updating for ind. buffers::   Updating Methods for indirect buffers
* Jumping to external tags::    Jumping to the definition of external types


File: ecb.info,  Node: Visiting tags,  Next: Expanding,  Prev: The Methods window,  Up: The Methods window

6.6.1 Possible actions after visiting a tag
-------------------------------------------

You visit a tag by clicking with either the primary oder secondary
mouse-button (or by hitting `RET' or `C-RET' if using the keyboard) onto a
node in the Methods-tree-buffer of ECB. This simply selects the "right"
edit-window (depends if clicked with the primary or secondary button, in how
many windows the edit-area is splitted and the value of
`ecb-mouse-click-destination') and puts the point onto the first line of the
clicked tag.

But you can define if after this "basic" tag-visit-action more additional
actions should be performed by ECB. You can either use some of the predefined
actions (e.g. highlighting the header-line of the tag) or define own actions.
You can set different actions for different major-modes. All this is done via
the option `ecb-tag-visit-post-actions'.

The following actions are currently predefined:
   - `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.

Per default ECB performs the actions `ecb-tag-visit-smart-tag-start' and
`ecb-tag-visit-highlight-tag-header' for all major-modes.


File: ecb.info,  Node: Expanding,  Next: Customizing the display,  Prev: Visiting tags,  Up: The Methods window

6.6.2 Explicit and automatic expanding of the ECB-methods-buffer
----------------------------------------------------------------

6.6.2.1 Explicit expanding all nodes to a certain expansion level
.................................................................

With the command `ecb-expand-methods-nodes' (bound to `C-c .  x') you can get
a fast overlook of the contents of the source-buffer, because this command
allows precisely expanding all tags with a certain indentation-level. So you
can either expand no tags (or with other words collapse all tags) or expand
all tags so see the contents of a buffer at one glance. Or you can expand
exactly that tags of a certain indentation level.

Which node-types are expanded (rsp. collapsed) by this command depends for
semantic-sources on the options `ecb-methods-nodes-expand-spec' and
`ecb-methods-nodes-collapse-spec'! For non-semantic-sources always all
node-types are expanded/collapsed, i.e. the two options above takes no effect
for these files.

6.6.2.2 Explicit expanding of the current node to a certain level
.................................................................

With the popup-menu of the methods-buffer an even more precise expansion is
possible because it allows not only expanding all tags (see above) but offers
in addition expanding only the current-node (for which the menu was
activated) to an exact level of expansion:

All menu-entries are label with an expansion-"level" whereas level specifies
precisely which level of nodes should be expanded. level means the
indentation-level of the NODE itself and its (recursive) subnodes relative to
the NODE itself.

So a level value X means that all (sub)nodes with an indentation-level <= X
relative to NODE are expanded and all other are collapsed.

Examples:

   - Expand this node to level 0: Expand only the NODE itself because it is
     the only node which has indentation 0 to itself. All deeper indented
     nodes will be collapsed.  This is also the important difference between
     using this menu compared to clicking onto the expand-symbol of the node:
     The latter one expands the NODE to that expansion-state it has before
     the last collapsing (so when deeper nodes has been expanded they will be
     expanded now to). The former one expands exactly(!) to level 0, means
     expand only the node itself and collapse all(!) its subnodes
     recursively(!).

   - Expand this node to level 1: Expand the NODE itself and all of its
     direct subnodes - because only the direct subnodes of NODE have
     indentation-level 1 relativ to NODE.  All deeper nodes will be collapsed.

   - Collapse this node completely: Collapses the current node recursively,
     means collapse not only the node itself but also its subnodes, the
     subnodes of the subnodes and so on! This is very differnt from clicking
     onto the collapse symbol because this action only collapses the node
     itself but preserves the expansion-state of all its subnodes!


Expanding the current node with the popup-menu ignores the settings in the
options `ecb-methods-nodes-expand-spec' and `ecb-methods-nodes-collapse-spec'!

6.6.2.3 Automatic expansion ot tags after buffer-parsing
........................................................

With the option `ecb-show-tags' you tell ECB how to display tags of a certain
tag-class (*note Customizing the display::). Among other things you can tell
ECB that a certain tag-class should be combined under an expanded or
collapsed bucket-node. But such a setting defines the expansion-state of such
a bucket-node only direct afterwards the buffer has been (re)parsed, which
can occur after opening a file, after autom. reparsing the buffer via
semantic or after manually rebuilding the methods-buffer of ECB.

The tag-class `type' (classes, interfaces, enumerations etc.) is divided into
several subtypes by semantic. The subtypes are strings which names exactly if
the tag with tag-class `type' is a class, an interface, an enumeration, a
typedef etc. With the option `ecb-type-tag-expansion' you can tell ECB if
these type-tags should be autom. expanded after (reparsing) a buffer (see
above) or if they should be displayed collapsed - so all its members (methods,
variables etc.) are hidden.

6.6.2.4 Automatic expanding the ECB-methods-buffer for current tag
..................................................................

If the option `ecb-highlight-tag-with-point' is switched on, then always that
node in the method-buffer is highlighted which belongs to the current
semantic-tag under point in the current active edit-window. But if this node
is invisible (probably because its parent node is collapsed) then no node is
highlighted if the auto.  expanding feature is switched off.

You can either switch on this feature with the option
`ecb-auto-expand-tag-tree' or even easier with the command
`ecb-toggle-auto-expand-tag-tree'.

There is another option `ecb-expand-methods-switch-off-auto-expand' which
makes both explicit and auto. expanding best working together. See the
documentation of this option to get the details.

The autom. expanding feature is only available for semantic-sources!

Previous versions of ECB have always fully expanded the whole tree in the
Methods-buffer if the current tag in the source-buffer was not visible in the
current tree - e.g. because the variables-bucket was collapsed or the
containing type of a tag (e.g. the class of a method) was collapsed. So in
most cases much more was expanded as needed to make the current tag visible.

The mechanism of ECB 2.22 and higher only expands the needed parts of the
tree-buffer to make the related node visible: First we try to highlight the
current tag with current expansion-state of the Methods-buffer. If the node
is not visible so the tag can not be highlighted then we go upstairs the
ladder of type-tags the current tag belongs to (e.g. we expand successive the
nodes of the whole class-hierachy of the current method-tag until the related
node becomes visible). If there is no containing type for the current tag
then the node of the tag is probably contained in a toplevel-bucket which is
currently collapsed; in this case we expand only this bucket-node and try
highlighting again. Only if this has still no success then we expand the full
tree-buffer and try to highlight the current tag.

There is another option `ecb-auto-expand-tag-tree-collapse-other': If this
option is set then auto. expanding the tag-tree collapses all not related
nodes.  This means that 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. This feature is switched off by default because
if always collapses the complete Methods-tree before the following
highlighting of the node for the current tag expands the needed parts of the
tree-buffer.


File: ecb.info,  Node: Customizing the display,  Next: Updating Methods-window,  Prev: Expanding,  Up: The Methods window

6.6.3 Customizing the display of the Methods-buffer
---------------------------------------------------

The ECB-Methods buffer is probably the most important browsing window offered
by ECB. It displays all parsing informations of the current source-buffer
(the buffer displayed in the current active edit-window).

Normally ECB gets all informations displayed in this Methods-buffer from the
semantic-library - at least for semantic-sources. This library parses auto.
the current source-buffer in the edit-window of ECB and returns all
information in form of "tags" to ECB which displays them in a browse-able
form in its Method-buffer. See *Note ECB Methods-window:: for information how
to use the Methods-buffer.

There are several options to customize which tags ECB should display in
general, if the tags should be collapsed or expanded, how to fontify them
(i.e. syntax-highlighting) and something more.

`ecb-show-tags'
     With the option `ecb-show-tags' you specify how ECB should display the
     tags returned by the semantic parser. Semantic divides its tags in
     several so called "tag classes". A tag-class is always a symbol and can
     be for example `type' (tags which represent a class(1), a interface, an
     enumeration etc.), `function' (tags which represent function or methods),
     `variable' (variables and attributes), `include' (import-statements)
     etc. There is no predefined superset of allowed tag-class-symbols
     because each language-parser can define its own tag-classes. But to get
     an overview of the most common tag-classes see the default value of the
     option `ecb-show-tags'.

     With the option `ecb-show-tags' you can now specify how ECB should
     display tags of a certain tag-class in a certain major-mode.  You can
     tell ECB that all tags of a tag-class `X' should be displayed in an
     expanded bucket and all tags of a tag-class `Y' should be displayed in a
     collapsed bucket and all tags of a tag-class `Z' should be displayed
     flattened (means not contained in a expandable/collapsable bucket-node).
     These settings can be made separately for each major-mode but you can
     also define a default-display which takes effect when for a major-mode
     no special setting can be found in `ecb-show-tags'.

     For every tag-class you can tell ECB how the tags should be sorted.

`ecb-font-lock-tags'
`ecb-type-tag-display'
     How to fontify the tags in the Method-buffer

`ecb-tag-display-function'
     ECB and semantic offer several predefined functions for displaying the
     tags. Here you can customize, what informations tags should contain
     (only the method-name or the whole signature or something else) and what
     notation should be used, e.g. UML or not.


These are the most important options for this topic but it is recommended to
have a look into the customize-group `ecb-methods' (*note ecb-methods::) and
check all the options offered there!

All these options are only relevant for semantic-sources and take no effect
for non-semantic-sources!

XXXXX

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

(1) Do not confuse the term "class" in the context of a tag, which means the
class of the tag and which is a semantic-term and a "class" in the context of
an object oriented language like Java or C++! Normally the surrounding
context sould be sufficient to understand which type of "class" is meant
whenever the term "class" is used in this manual.


File: ecb.info,  Node: Updating Methods-window,  Next: Updating for ind. buffers,  Prev: Customizing the display,  Up: The Methods window

6.6.4 Updating the Methods-window with contents of current source-buffer
------------------------------------------------------------------------

First a preliminary remark: Do not confuse this chapter with that
synchronizing described in *Note ECB-window synchronizing::. The latter one
describes the mechanism for synchronizing the ECB-windows when the
current-buffer in the edit-area has been changed. This chapter describes how
to update the ECB-methods-window with the contents of the current-buffer if
the buffer has been modified!

6.6.4.1 The short version
.........................

In almost all cases there is *NO* need to manually rebuild the method-buffer,
because it is always done automatically if necessary; the mechanism depends
on the sources:

   - semantic-sources: The command `global-semantic-idle-scheduler-mode'
     switches on autom.  reparsing of semantic-sources. All the rest will be
     done by semantic and ECB automatically. ECB and semantic always try to
     reparse and update as less as possible of the sourcecode-buffer.

   - non-semantic-sources (imenu supported): You can switch on autom.
     rescanning/reparsing with the option `imenu-auto-rescan'. But
     nevertheless you have to manually rebuild the Method-buffer (with the
     autom. updated imenu-tags) via the command `ecb-rebuild-methods-buffer'
     (bound to `C-c . r').

   - non-semantic-sources (etags supported): For these sources there is no
     built-in auto-rescan mechanism, because etags is an external tool it can
     only operate on the saved file-contents. So rescanning the buffer
     contents would need to save the buffer before. Therefore there is no
     built-in auto-rescan mechanism because this would always result in
     saving the buffer and running an external tool. But of course you can
     program such a an etags-auto-rescan mechanism for yourself!

6.6.4.2 The full and long story
...............................

Generally ECB calls semantic to get the list of tags for current source-file
of current edit-window. Per default ECB does never automatically force a
reparse of the source-file after this has been changed - this is only done on
demand by calling the command `ecb-rebuild-methods-buffer'. So per default
the idle-scheduler of semantic is responsible for reparsing the source-file
when this is necessary (see `semantic-idle-scheduler-mode' for further
details). So this scheduler is also responsible when updating/sychronizing
the methods-window with current buffer-contents. This is the most
user-resonsible and therefore the recommended approach.

ECB is responsible to update the methods-window after the idle scheduler of
semantic has triggered either a full or partial reparse of the source-buffer.
Semantic always tries to reparse as less tags of the buffer as possible, often
just the edited section (if it has no sideeffect to tags outside the edited
parts). ECB handles this partial reparse output smoothly and updates only
these nodes which are releated to the reparsed tags.

The main effect a user will notice is that edit actions which trigger just a
partial reparse will just update the related node in the methods-window and
not the whole methods-window. One of the main advantages is that this
preserves the expand/collapse state of the methods-window.

Editing examples which trigger only a partial reparse:
   * editing a function- or method-body

   * changing the name of a variable or function/method

   * modifying the return-type of a function/method

   * and some other...

In these cases only the related node in the methods-window will change
nothing else, ie. the expand/collapse-states of all other nodes in the
methods-window will not be changed.

*Summary*: It's strongly recommended to enable `semantic-idle-scheduler-mode'
or `global-semantic-idle-scheduler-mode' (*note Setting up CEDET/semantic::)
because then reparsing is always done during idle-time of Emacs and - maybe
even more important - it is also interruptable.

But if this idle-scheduler is switched off then ECB offers now two
possibilities (via `ecb-force-reparse-when-semantic-idle-scheduler-off'):

   *  Not forcing itself a reparse when tags are needed by ECB: then a user
     declines knowingly Emacs/semantic-driven parsing of code when he/she
     switches off the idle-mode of semantic. This is the default behavior of
     ECB and the default value of this option. But this has also the
     consequence that the methods-buffer is only filed on demand via
     `ecb-rebuild-methods-buffer' (bound to <C-c . r>)!

     This means also in consequence that the methods-buffer is not
     automatically filled when a source-file is opened but first on demand
     after calling the command `ecb-rebuild-methods-buffer'!

   *  Forcing a reparse when tags are needed: Then ECB forces semantic to
     parse the source-file when ECB needs tags to display. For this behavior
     this option has to be set to not nil.

The term "forcing a reparse by semantic" is a simplification: ECB uses then
the function `semantic-fetch-tags' which can decide that the cached tags are
up-to-date so no real reparsing is necessary - but it can also run a full
reparse and this reparse is not being done when Emacs is idle but immediatelly
and not interruptable (as with the idle-scheduler of semantic), which can be
quite annoying with big source-files.

To make a long story short: It is strongly recommended to enable the
`semantic-idle-scheduler-mode' or `global-semantic-idle-scheduler-mode'! See
*Note Setting up CEDET/semantic::. This will give you in all cases the
behavior you would expect of an IDE like ECB/semantic.


File: ecb.info,  Node: Updating for ind. buffers,  Next: Jumping to external tags,  Prev: Updating Methods-window,  Up: The Methods window

6.6.5 Updating Methods for indirect buffers
-------------------------------------------

ECB works out of the box with indirect buffers, especially with indirect
buffer clones created with the command `clone-indirect-buffer' (only
available with GNU Emacs >= 21). They will be handled as all other buffers and
you can work with them with no difference to "normal" buffers. With one
exception:

*Please note*: Cause of a bug in Emacs 22 (and maybe also in Emacs 23) the
propagation of parsing informations from one buffer to all others which are
in an indirect-buffer relation to the same base-buffer does currently not
work.

What does this mean: If you modify a buffer then Emacs propagates this change
to all buffers with the same base-buffer. ECB/semantic recognize this change
and do all necessary to automatically reparse the changed buffer (at least if
you have customized semantic/ECB to do this). So far so good, but: If you
switch to another buffer with the same base-buffer then you will notice that
the methods-window of ECB still displays the contents before the change, ie.
the need for a reparse has not been propagated to these other buffers. This is
a bug in Emacs.

What can you do: As long as this bug is not fixed there is no chance that all
other affected "indirect-related" buffers will be reparsed automatically
after modifying one of them. So you have to do this reparse "by hand" after
switching to such an indirect-related buffer, but this is very simple: Just
call the command `ecb-rebuild-methods-buffer' with prefix arg or hit <C-u C-c
. r> (key this command is bound to).

Lets make an example:

  1.  Suppose we have a sourcefile test.java loaded as a buffer into Emacs and
     suppose further we have created two indirect-buffer clones
     test-clone1.java and test-clone2.java - all of these buffers point to
     the same file: test.java.

  2.  Now lets be the buffer test-clone1.java the current buffer and let us
     modify it (e.g. adding a new method). If you have enabled the
     idle-reparse mechanism of semantic (*note Setting up CEDET/semantic::)
     then this buffer will be reparsed automatically and ECBs methods-window
     will be updated in turn too.

  3.  So far so good. But if you now switch to one of the two other buffers,
     lets say to test.java, then you will notice that the change done in
     test-clone1.java is also visible in the buffer test.java but the
     ECB-methods-window for test.java will display the contents before the
     change.  This is cause of the Emacs-bug described above.

  4.  To update the methods-window for test.java to the new contents you have
     to call `ecb-rebuild-methods-buffer' with prefix argument (ie.
     clear-cache is true) or hitting <C-u C-c . r>. Note: Calling this
     command without prefix argument is not enough!



File: ecb.info,  Node: Jumping to external tags,  Prev: Updating for ind. buffers,  Up: The Methods window

6.6.6 Jumping to the definition of external types
-------------------------------------------------

There are two common types of "external" tags displayed in the method-window,
mostly with object oriented programing-languages:

  1. parent-types

     Tags which represent the type of a parent-class (which can be defined in
     the same file but which is more often defined in another file). All
     parents (regardless if defined internaly or externaly) of a type will be
     displayed under a bucket "[Parents]" in the methods-window of ECB.

  2. "virtual" types

     In OO-languages like CLOS, eieio and C++ there can be nodes with
     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.


In both cases the user wants to jump to the definition of the type if he
clicks onto the related node in the methods-window of ECB.

Here is a C++-example for "virtual" types (2) and parent types (1) which
explains this in detail:

Let's say this class is defined in a file `ParentClass.h':

   class ParentClass
   {
   protected:
     int p;
   };

Let's say this class is defined in a file `ClassWithExternals.h'

   #include "ParentClass.h"

   class ClassWithExternals : public ParentClass
   {
   private:
     int i;

   public:
     ClassWithExternals();
     ~ClassWithExternals();
   };

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

   #include "test.h"

   ClassWithExternals::ClassWithExternals(int i,
                                          boolean b,
                                          char c)
   {
     return;
   }

   void
   ClassWithExternals::~ClassWithExternals()
   {
     return;
   }

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 destructor of the class "ClassWithExternals" are
grouped under their class-type. But this class-type "ClassWithExternals" is
represented by a so called "virtual" or "faux" node-tag, i.e. there is no
real tag in the current source-buffer for this tag.

If a user now clicks onto the node of "ClassWithExternals" then he wants to
jump to the right location in the right file where "ClassWithExternals" is
defined. ECB now uses now some smart mechanisms (see below) to do this. In
case of success (means ECB has found the definition) it opens the right file
and point will stay at beginning of the definition of the type
"ClassWithExternals".

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

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

Now let's play it again: Now we want to go to the definition of the
parent-type "ParentClass" when we click onto the related node under the
bucket "[Parents]". Again ECB uses its smartness to jump to the definition of
the class "ParentClass" when you click onto the node "ParentClass".

Now lets explain the precondition which must be fulfilled so ECB can do its
job:

   * Customizing the semantic analyzer for your needs

     ECB itself is quite stupid concerning finding external tags. But it can
     use the semantic-analyzer of the CEDET-suite (remember: The CEDET-suite
     is a must-requirement of ECB, see *Note Requirements::). But this in
     turn means that the semantic-analyzer must be customized in the right
     way for the needs of your programing projects. Mainly this means
     activating semanticdb and setting the correct include-path etc...

     *Please note*: Read the related manuals of semantic and - strongly
     recommended - read in addition the article "Gentle introduction to
     Cedet".  It's worth to read it! The website of CEDET contains a link,
     you find it here:
     `http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html'

   * Customize the related options of ECB:

     There is exactly one option you have to take into account:
     `ecb-find-external-tag-functions'. This defines the method ECB uses to
     find these external tags.

     Mostly there is nothing to do because the default values should do a
     good job.  But if things are running bad then maybe this is the right
     screw for you.

     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. 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': The most powerfil one,
          based on the semantic-analyzer

        - `ecb-search-type-tag-by-semanticdb': A backup for the first one

        - `ecb-jde-show-class-source': For major-mode `jde-mode' when coding
          in java, uses java-mechanisms - maybe for java the best choice.

     See the documentation of the option and also of these function for
     details how they work and how to write own finding-functions.



File: ecb.info,  Node: Filtering the tree-buffers,  Next: The ECB-layout,  Prev: The Methods window,  Up: Usage of ECB

6.7 Applying filters to the special ECB-tree-buffers
====================================================

To get a fast and good overlook of the contents of a tree-buffer ECB offers a
filter-mechanism for the Directories-, Sources-, the History- and the
Methods-buffer.

* Menu:

* Filtering Directories::       Applying filters to the Directories-buffer
* Filtering Sources::           Applying filters to the Sources--buffer
* Filtering History::           Applying filters to the History-buffer
* Filtering Methods::           Applying filters to the Methods-buffer


File: ecb.info,  Node: Filtering Directories,  Next: Filtering Sources,  Prev: Filtering the tree-buffers,  Up: Filtering the tree-buffers

6.7.1 Applying filters to the Directories-buffer
------------------------------------------------

With the option `ecb-excluded-directories-regexps' certain directories can be
excluded from being displayed in the directories-browser of ECB. This can be
done by defining regular expressions. If the name of a directory matches at
least one of the regexps of this option the directory is not displayed in the
directories-tree-buffer.

The option `ecb-sources-exclude-cvsignore' allows to exclude source-files
from the sources-tree-buffer if their name is listed in a so called
`.cvsignore'-file. This option is a list of regular expressions and if a
directory-name matches at least one of these regexps then all files listed in
the `.cvsignore'-file of this directory are not displayed in the
sources-tree-buffer.


File: ecb.info,  Node: Filtering Sources,  Next: Filtering History,  Prev: Filtering Directories,  Up: Filtering the tree-buffers

6.7.2 Applying filters to the Sources-buffer
--------------------------------------------

6.7.2.1 Interactive Sources-filters
...................................

The command `ecb-sources-filter' allows to filter these tree-buffer either by
a regular expression or by an extension (e.g.  java, cc, el for java-, c++-
rsp elisp-sources). This functionality is also available via the popup-menu
of the Sources-tree-buffer.

The currently applied filter is indicated in the modeline of the related
tree-buffer. Applying a new filter replaces an eventually already applied
filter.

6.7.2.2 Default Sources-filters
...............................

The option `ecb-source-file-regexps' allow to specify which source-files
should be displayed and which not. This is done on a directory-basis, ie. for
each directory-regexp the files to display can be specified. See the
documentation of this option for all details.

In addition to this option you should also know the option
`ecb-sources-exclude-cvsignore' (*note Filtering Directories::).


File: ecb.info,  Node: Filtering History,  Next: Filtering Methods,  Prev: Filtering Sources,  Up: Filtering the tree-buffers

6.7.3 Applying filters to the History-buffer
--------------------------------------------

6.7.3.1 Interactive History-filters
...................................

The command `ecb-history-filter' allows to filter these tree-buffer either by
a regular expression or by an extension (e.g.  java, cc, el for java-, c++-
rsp elisp-sources). This functionality is also available via the popup-menu
of the History-tree-buffer.

The currently applied filter is indicated in the modeline of the related
tree-buffer. Applying a new filter replaces an eventually already applied
filter.

6.7.3.2 Default History-filters
...............................

The option `ecb-history-exclude-file-regexps' allows to exclude source-files
from being historized (ie. displayed in the History-buffer). Despite the fact
that the History-buffer already excludes all non-file-buffers there can be
still buffers which name you do not wat to be displayed in the history. These
are file-buffer like `TAGS' or `semantic.cache' which store meta-informations
used by Emacs and its tools (etags, semantic etc.).  These files can be
excluded via `ecb-history-exclude-file-regexps'.


File: ecb.info,  Node: Filtering Methods,  Prev: Filtering History,  Up: Filtering the tree-buffers

6.7.4 Applying filters to the Methods-buffer
--------------------------------------------

The commands `ecb-methods-filter', `ecb-methods-filter-regexp',
`ecb-methods-filter-protection', `ecb-methods-filter-tagclass',
`ecb-methods-filter-function', `ecb-methods-filter-delete-last',
`ecb-methods-filter-nofilter' allows to filter the tags/nodes of the
Methods-buffer by several criterias. As for the Sources- and the
History-buffer the same functionality is also available via the popup-menu of
the Methods-buffer.

6.7.4.1 Possible filter-criterias
.................................

   * Filter by protection: Just insert the protection you want the
     Methods-buffer being filtered: private, protected or public! For sources
     not supported by semantic the protection filter will not be offered
     because these informations are not available for such sources.

   * Filter by regexp: Insert the filter as regular expression.

   * Filter by tag-class: You can filter by tag-classes. The popup-menu
     contains mode-dependend tag-filter entries and the command
     `ecb-methods-filter' offers only the tag-classes of the current mode.
     This means for sources not supported by semantic the tag-class filter
     will not be offered. And for semantic-supported sources exactly these
     tag-classes are offered the semantic-parser for the current major-mode
     offers. For example texi-sources can only be filtered by the tag-classes
     "Definitions" and "Sections" and java-sources can be filtered by
     "Methods", "Variables", "Classes" etc. In general the semantic-variable
     `semantic-symbol->name-assoc-list' is used to get the right tag-classes.

   * Filter by a filter-function: Such a function gets two arguments: a tag
     and the source-buffer of this tag. If the tag should be displayed (i.e.
     not being filtered out) then the function has to return not nil
     otherwise nil.

   * No special filter: This means to display all tags specified with the
     option `ecb-show-tokens'. If currently some of the above filters are
     applied they will be all removed.

   * Delete the last added: This removes only the topmost filter-layer, means
     that filter added last.

Be aware that the tag-list specified by the option `ecb-show-tags' is the
basis of all filters, i.e. tags which are excluded by that option will never
be shown regardless of the filter type here!

All tags which match the applied filter(s) will be displayed in the
Methods-buffer. Such a filter is only applied to the current source-buffer,
i.e. each source-buffer can have its own tag-filters.

These tag-filters can also applied to sources which are not supported by the
semantic-parser but "only" by imenu or etags. But because for these sources
not all information are avaiable the protection- and tag-class filter are not
offered with such "non-semantic"-sources.  See *Note Non-semantic sources::
for further details about working with source-files not supported by the
semantic-parser.

6.7.4.2 Inverse Filters
.......................

But if `ecb-methods-filter' is called with a prefix-argument then an inverse
filter is applied to the Methods-buffer, i.e. all tags which do *NOT* match
the choosen filter will be displayed in the Methods-buffer!

6.7.4.3 Layered filters
.......................

Per default the choosen filter will be applied on top of already existing
filters. This means that filters applied before are combined with the new
filter. This behavior can changed via the option
`ecb-methods-filter-replace-existing'.

6.7.4.4 Display of currently applied filters
............................................

The current active filter will be displayed in the modeline of the
Methods-buffer [regexp, prot (= protection), tag-class, function (=
filter-function)]. If an inverse filter has been applied then this is
signalized by a preceding caret ^. If currently more than 1 filter is applied
then always the top-most filter is displayed in the modeline but the fact of
more than 1 filter is visualized by the number of the filters - included in
parens. You can see all currently applied filters by moving the mouse over
the filter-string in modeline of the Methods-buffer: They will displayed as
help-echo.

6.7.4.5 Default filters for certain files.
..........................................

The new option `ecb-default-tag-filter' 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. The files can be specified on a
combined major-mode- and filename-regexp-basis.

Usage-example: This can be used to display in outline-mode files (e.g.
`NEWS') only the level-1-headings by defining a filter regexp "^\* .*".


File: ecb.info,  Node: The ECB-layout,  Next: Hiding the ECB windows,  Prev: Filtering the tree-buffers,  Up: Usage of ECB

6.8 Changing, customizing, redrawing and creating layouts
=========================================================

The term "ECB-layout" means in which windows the ECB-frame is divided. This
chapter describes all aspects concerning this layout, especially changing,
customizing, redrawing and also creating new layouts.

* Menu:

* Changing the ECB-layout::     How to change and customize the layout
* Redrawing the ECB-layout::    How and when redrawing the layout
* Changing window sizes::       Changing sizes of the ECB-windows
* Fixing window sizes::         Fixing sizes of the ECB-windows
* Creating a new ECB-layout::   Interactively creating new layouts


File: ecb.info,  Node: Changing the ECB-layout,  Next: Redrawing the ECB-layout,  Prev: The ECB-layout,  Up: The ECB-layout

6.8.1 Changing and customizing the ECB-layout
---------------------------------------------

ECB offers several predefined layouts with different sets and also different
locations of ECB-windows. See below the "ascii-screenshot" of all currently
built-in layouts(1).

In addition to these predefined layouts you can either interactively create
new layouts "by example" (*note Creating a new ECB-layout::) or program new
layouts with the macro `ecb-layout-define' (*note The layout-engine::). The
former method is the recommended one!

There are two ways to interactively change the layout:
   * Changing permanently: Customize the option `ecb-layout-name' and store
     it for future Emacs sessions.

   * Switching between several layouts at runtime: If you want to switch fast
     between a certain sequence of layouts see the option
     `ecb-toggle-layout-sequence' and the command `ecb-toggle-layout' (*note
     Simulating speedbar::). For just selecting another layout during current
     Emacs-session use the command `ecb-change-layout'.

With the option `ecb-show-sources-in-directories-buffer' you can define if
sources are displayed in the directory-window of a layout (*note ECB
Directories-window::).

In addition to the general layout you can specify if the layout should
contain a persistent compilation-window at the bottom of the frame, see
`ecb-compile-window-height' (*note Temp- and compile-buffers::).

Maybe you want also change the look&feel of the tree-buffers. Then you can
change the general style of the tree-buffers with the option
`ecb-tree-buffer-style' and the location of the collapse- and expand-symbols
and the indentation of sub-nodes in a tree. See `ecb-tree-indent' and
`ecb-tree-expand-symbol-before'. More details about the different
tree-buffer-styles are described in *Note Tree-buffer styles::.

Here are all currently available layouts (for creating own new layouts see
*Note Creating a new ECB-layout::); just customize the option
`ecb-layout-name' to the related name:

Layout "left1"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |      |       |                                      |
        | Sour | Hist  |                 Edit                 |
        |      |       |                                      |
        |      |       |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left2"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Sources     |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left3"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Sources     |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left4"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |      |       |                                      |
        |      |       |                                      |
        |      |       |                                      |
        | Sour | Hist  |                                      |
        |      |       |                                      |
        |      |       |                                      |
        |      |       |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left5"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Sources     |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  History     |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "right1"
        -------------------------------------------------------
        |                                      |              |
        |                                      |  Directories |
        |                                      |              |
        |                                      |              |
        |                                      |--------------|
        |                                      |              |
        |                                      |              |
        |             Edit                     |  Sources     |
        |                                      |              |
        |                                      |              |
        |                                      |--------------|
        |                                      |              |
        |                                      |  Methods     |
        |                                      |              |
        |                                      |              |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left6"
        -------------------------------------------------------
        |  Sources     |                                      |
        |--------------|                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Methods     |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |  History     |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "top1"
        -------------------------------------------------------
        |                        |             |              |
        |                        |             |              |
        |      Directories       |  Sources    |  Methods     |
        |                        |             |              |
        |                        |             |              |
        |-----------------------------------------------------|
        |                                                     |
        |                                                     |
        |                                                     |
        |                                                     |
        |                    Edit                             |
        |                                                     |
        |                                                     |
        |                                                     |
        |                                                     |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left7"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |  History     |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left8"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Sources     |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |  History     |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "top2"
        -------------------------------------------------------
        |                                                     |
        |                                                     |
        |                    Methods                          |
        |                                                     |
        |                                                     |
        |-----------------------------------------------------|
        |                                                     |
        |                                                     |
        |                                                     |
        |                                                     |
        |                    Edit                             |
        |                                                     |
        |                                                     |
        |                                                     |
        |                                                     |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left9"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |   Methods    |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left10"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Methods     |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |      |       |                                      |
        | Sou  | Hist  |                                      |
        |      |       |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left11"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Methods     |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  History     |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left12"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |   History    |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left13"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        | Directories  |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left14"
        -------------------------------------------------------
        |              |                                      |
        |              |                                      |
        |              |                                      |
        | Directories  |                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  History     |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left15"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |              |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "leftright1"
        -------------------------------------------------------
        |             |                         |             |
        | Directories |                         |  Methods    |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |-------------|          Edit           |             |
        |             |                         |             |
        | Sources     |                         |             |
        |             |                         |             |
        |-------------|                         |             |
        |             |                         |             |
        | History     |                         |             |
        |             |                         |             |
        -------------------------------------------------------
        |                                                     |
        |                   Compilation                       |
        |                                                     |
        -------------------------------------------------------

Layout "leftright2"
        -------------------------------------------------------
        |             |                         |             |
        | Directories |                         |  Methods    |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |          Edit           |             |
        |-------------|                         |-------------|
        |             |                         |             |
        | Sources     |                         |  History    |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        -------------------------------------------------------
        |                                                     |
        |                   Compilation                       |
        |                                                     |
        -------------------------------------------------------

Layout "leftright3"
        -------------------------------------------------------
        |             |                         |             |
        | Directories |                         |  Methods    |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |          Edit           |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        |             |                         |             |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left-dir-plus-speedbar"
        -------------------------------------------------------
        |             |                                       |
        | Directories |                                       |
        |             |                                       |
        |             |                                       |
        |             |                                       |
        |             |                                       |
        |             |                                       |
        |-------------|                                       |
        |             |                                       |
        |             |                                       |
        |             |                                       |
        | Speedbar    |                                       |
        |             |                                       |
        |             |                                       |
        |             |                                       |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left-analyse"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Sources     |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Analyse     |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------

Layout "left-symboldef"
        -------------------------------------------------------
        |              |                                      |
        |  Directories |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Sources     |                                      |
        |              |                                      |
        |--------------|                 Edit                 |
        |              |                                      |
        |  Methods     |                                      |
        |              |                                      |
        |--------------|                                      |
        |              |                                      |
        |  Symbol-defs |                                      |
        |              |                                      |
        -------------------------------------------------------
        |                                                     |
        |                    Compilation                      |
        |                                                     |
        -------------------------------------------------------


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

(1) The command `ecb-show-layout-help'' shows the outline-picture for all
built-in layouts.


File: ecb.info,  Node: Redrawing the ECB-layout,  Next: Changing window sizes,  Prev: Changing the ECB-layout,  Up: The ECB-layout

6.8.2 Redrawing the ECB-layout
------------------------------

If you have unintentionally destroyed the ECB-layout, you can always restore
the layout with calling `ecb-redraw-layout'. This is even true, if you get
messages like "wrong-type-argument window-live-p #<window 222>".

If the variable `ecb-redraw-layout-quickly' is not nil then the redraw is
done by the `ecb-redraw-layout-quickly' function, otherwise by
`ecb-redraw-layout-full'. But it's strongly recommended to use the quick
redraw only if you have really slow machines where a full redraw takes
several seconds because the quick redraw is not really safe and may have some
drawbacks! On normal machines the full redraw should be done in << 1s!

Please read the documentation of the command `ecb-redraw-layout'!

See also the hooks `ecb-redraw-layout-after-hook' and
`ecb-redraw-layout-before-hook'!


File: ecb.info,  Node: Changing window sizes,  Next: Fixing window sizes,  Prev: Redrawing the ECB-layout,  Up: The ECB-layout

6.8.3 Changing the sizes of the special ECB-windows
---------------------------------------------------

The standard width and height of the special ECB-windows is defined with the
options `ecb-windows-width' and `ecb-windows-height'. But changing these
options always influences all layouts which is not always desired.

ECB offers to re-adjust the width and height of the ECB-windows (e.g. by
dragging the windows-borders via the mouse) and then saving exactly these
current window-sizes for the current layout so after activating this layout
all windows have autom. the stored sizes.

This is done via the option `ecb-layout-window-sizes' and the commands
`ecb-store-window-sizes', `ecb-restore-window-sizes' and
`ecb-restore-default-window-sizes'.

Here is an example how to resize and store the sizes of the ECB-windows of
layout "left1":

  1. Switch to layout "left1" via `ecb-change-layout' (`C-c . lc')

  2. Resize the ECB-windows by dragging the window-borders with the mouse

  3. Call `ecb-store-window-sizes'

After this layout "left1" will be always drawn with the new sizes until you
call `ecb-restore-default-window-sizes' during layout "left1" is active.

*Please note*: `ecb-store-window-sizes' stores the width and height of the
windows per default as fractions of the width (rsp.  height) of the
ECB-frame, so the stored sizes are always correct regardless of the current
frame-size! But if called with a prefix argument then fixed sizes are stored.


File: ecb.info,  Node: Fixing window sizes,  Next: Creating a new ECB-layout,  Prev: Changing window sizes,  Up: The ECB-layout

6.8.4 Fixing the sizes of the special ECB-windows
-------------------------------------------------

GNU Emacs 21 introduced a new feature which can fix the sizes of a window
displaying a certain buffer even after resizing the frame. This new feature
is driven by the new buffer-local variable `window-size-fixed'(1).

ECB offers an option `ecb-fix-window-size' for fixing the sizes of the
special 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. In 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'.

Probably the most senseful value is `auto' for all layouts because it makes
less sense to fix the height of the ecb-windows in a left-, right- or
leftright-layout. Same for fixing the width in a top-layout.

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

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

(1) Currently XEmacs does not support this feature therefore
`ecb-fix-window-size' has no effect with XEmacs


File: ecb.info,  Node: Creating a new ECB-layout,  Prev: Fixing window sizes,  Up: The ECB-layout

6.8.5 Interactively creating new layouts
----------------------------------------

If you want to create your own ECB-layout then you can do this very easy "by
example" with the command `ecb-create-new-layout'.  This command creates a
new empty frame and offers a small set of keys to create the new layout by
splitting windows.  `ecb-create-new-layout' and this couple of keys are your
guide during the layout-creation-process(1).

After calling `ecb-create-new-layout' you will be asked which type of layout
you want to create: "left", "right", "top" or "left-right". Here you specify
where the ECB-tree-windows/buffers should be located in the ECB-frame:

   - left: All ECB-tree-windows are located on the left side

   - right: All ECB-tree-windows are located on the right side

   - top: All ECB-tree-windows are located on the top side

   - left-right: All ECB-tree-windows are located on the left and right side

Depending on the type you choose the window is splitted by the values of the
options `ecb-windows-width' (types "left", "right" and "left-right") or
`ecb-windows-height' (type "top").

Afterwards you will see a frame like follows (here the layout-type is
"left-right"):

   -----------------------------------------------------------------
   |<point>       |                                   |            |
   |              | ECB-layout creation mode          |            |
   |              | ========================          |            |
   |              |                                   |            |
   |              | <This is a persistent help-screen>|            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   |              |                                   |            |
   -----------------------------------------------------------------
                  |
                  |   ,---
                  `---| Splitted by the value of `ecb-windows-width'.
                      `---

The big window (here the middle window) will be the edit-area of the new
layout and can not be selected, deleted or splitted during the creation
process. It displays the help-screen for the layout-creation mode. Here all
the available commands are displayed.

The small window(s) (here the left and right windows) can be splitted by you
wherever you want (`C-s'). The left one contains the point.  You must give
every ECB-tree-window you create a type (`C-t') which can be either

   * One of the built-in types

     This can be either "directories", "sources", "methods", "history" or
     "speedbar".

   * Any user-defined type:

     In this case you insert "other" after hitting `C-t' and you will then be
     asked for the name of the user-defined type. You can insert any
     arbitrary type name X. But to get this layout working you have to define
     a function with name `ecb-set-X-buffer' whereas X is the name of the
     user-defined type you have specified during layout-creation.

     This function `ecb-set-X-buffer' must be defined with the macro
     `defecb-window-dedicator-to-ecb-buffer' and has to switch to the buffer
     you want to display in this window. This macro automatically ensures that
     this window is dedicated to that buffer.

     Here is an example: Suppose you have inserted as type name "example"
     then you have to define and load a function `ecb-set-example-buffer'
     which could be defined like follows:

        (defecb-window-dedicator-to-ecb-buffer ecb-set-example-buffer " *ECB example-buf*"
          (switch-to-buffer (get-buffer-create " *ECB example-buf*")))

     If you forget to define such a function for the user-defined type then
     nevertheless ECB will draw this layout but it will use the
     default-function `ecb-set-default-ecb-buffer' instead.

If you are satisfied with your new layout just hit `C-q'. You will be asked
for a new layout-name (TAB-completion is offered to get a list of all names
already in use) and after inserting a new(!) name the new layout is saved in
the file defined by the option `ecb-create-layout-file'. The new layout is
now available via the option `ecb-layout-name'.

There is no need for you to load the file `ecb-create-layout-file' manually
into your Emacs because it's automatically loaded by ECB!

*Please note*: During the layout-creation process only the commands displayed
in the help-screen are available. ALL other commands are temporally disabled
(even the mouse-commands).

For programming new layouts with emacs-lisp see *Note The layout-engine::.

With the command `ecb-delete-new-layout' you can delete previously created
layouts (TAB-completion is offered for all names of user created layouts).

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

(1) During the creation process you will be asked in the minibuffer for
several options; here you can use TAB-completion and an "empty" RET chooses
always the first option!


File: ecb.info,  Node: Hiding the ECB windows,  Next: Maximizing the ECB windows,  Prev: The ECB-layout,  Up: Usage of ECB

6.9 Hiding/Showing the ECB windows
==================================

With `ecb-toggle-ecb-windows', `ecb-hide-ecb-windows' and
`ecb-show-ecb-windows' you can hide/show all the ECB windows without changing
the activation state of ECB and also without deactivating the advices for
`delete-other-windows' and/or `delete-window'. This is most useful if you use
a layout like "top2" (*note Common use-cases::) or if you want to have
maximum space for editing and you don't need the browsing windows all the
time.

The following sequence of hooks is evaluated during showing again 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'

The following sequence of hooks is evaluated during hiding the ECB-windows:
  1. `ecb-hide-ecb-windows-before-hook'

  2. `ecb-redraw-layout-before-hook'

  3. <Hiding the ECB-windows>

  4. `ecb-redraw-layout-after-hook'

  5. `ecb-hide-ecb-windows-after-hook'

If the special ECB-windows are hidden (e.g. by `ecb-toggle-ecb-windows') all
adviced functions behave as their originals. So the frame can be used as if
ECB would not be active but ECB IS still active in the "background" and all
ECB-commands and all ECB-keybindings can be used. Of course some of them
doesn't make much sense but nevertheless they can be called. Toggling the
visibility of the ECB-windows preserves the splitting-state of the edit-area:
If you hide the ECB-windows then the frame will be divided in the same
window-layout the edit-area had before the hiding and if you show the
ECB-windows again the edit-area will be divided into all the edit-windows the
ECB-frame had before the showing.

Therefore it should be enough to hide the ECB-windows to run other
Emacs-applications which have their own window-layout-managing. There should
be no conflicts. But nevertheless the most recommended method for running ECB
and other applications (e.g. xrefactory, Gnus etc.) in the same frame is to
use a window-manager like winring.el or escreen.el (*note Window-managers and
ECB::).


File: ecb.info,  Node: Maximizing the ECB windows,  Next: Back/forward navigation,  Prev: Hiding the ECB windows,  Up: Usage of ECB

6.10 Maximizing the ECB windows
===============================

6.10.1 How to maximize and minimize special ecb-tree-windows
------------------------------------------------------------

To get a better overlook about the contents of a certain ECB-window every
ECB-window can be "maximized", means all other ECB-windows are deleted so
only the edit-window(s) and this maximized ECB-window are visible (and maybe
a compile-window if active). There are several ways to do this:

   * Via the node-popup-menus of the ECB-windows

   * Via the main "ECB"-menu and here "Display window maximized"

   * Via calling the adviced version of `delete-other-windows'(1) (bound to
     `C-x 1') in one of the ECB windows.

   * Via one of the commands `ecb-maximize-window-directories',
     `ecb-maximize-window-sources', `ecb-maximize-window-methods',
     `ecb-maximize-window-history' or `ecb-maximize-window-speedbar' or the
     bound short-cuts for those commands.

   * Via the new command `ecb-cycle-maximized-ecb-buffers' which cycles
     through all ecb-buffers of current layout by maximizing exactly one of
     the ecb-windows after every cycle-step.

   * Via the option `ecb-maximize-ecb-window-after-selection' and then just
     by selecting an ECB-window. "Deselecting" an ECB-window brings back all
     ECB-windows of current layout.

   * Via the default modeline-mechanisms for deleting other windows. GNU
     Emacs binds `mouse-2' in its modeline to `delete-other-window'. XEmacs
     binds a popup-menu with some window commands to `button-3' in its
     modeline.

     ECB combines the best of both worlds by supporting both of these
     mechanisms for both Xemacs and Emacs: ECB binds a toggle-command to
     `mouse-2' in the modeline of each tree-buffer which maximizes the
     current tree-window if all ECB-windows are visible and displays all
     ECB-windows if current tree-window is maximized. In addition ECB binds a
     popup-menu to `mouse-3' which offers exactly 2 commands: Maximizing
     current tree-window and displaying all ECB-windows.

"Minimizing" such a maximized ECB-window, i.e. bringing back to its original
size and displays all ecb-windows of current layout, can simply be done by
redrawing the layout via the command `ecb-redraw-layout' (bound to `C-c .
lr').

6.10.2 Selecting a node in a maximized ecb-tree-window
------------------------------------------------------

When you select a node (either via mouse or RET) in a maximized tree-window
the default behavior of ECB is the following:

Maximized directories-window: When selecting a directory then first
automatically the maximized directories-window will be "minimized" (i.e. all
ecb-windows of current layout are displayed) if the current layout contains a
sources-buffer and no sources are shown in the directories-window - see
`ecb-show-sources-in-directories-buffer'.  So the source-files can be
displayed in the sources-window.

Maximized sources- or history-window: When selecting a source-file in one of
these buffers then first automatically the maximized window will be
"minimized" (i.e. all ecb-windows of current layout are displayed) if the
current layout contains a methods-buffer. So the tag-contents of the selected
source-file can be displayed in the methods-window.

For a even smarter behavior ECB offers the option
`ecb-maximize-next-after-maximized-select' which automatically maximizes the
next logical tree-window after a node selection. The definition of "next
logical is": 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 source-file from the sources-buffer.

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

(1) This command is adviced per default, see *Note The edit-area::.


File: ecb.info,  Node: Back/forward navigation,  Next: ECB-window synchronizing,  Prev: Maximizing the ECB windows,  Up: Usage of ECB

6.11 Back- and forward navigation like a browser
================================================

With ECB you can "browse" in your source-files like with a web-browser. This
means ECB stores the current buffer- and window-position relative to the
current tag(1) in the edit-window after

   - selecting a tag in the ECB-methods buffer or

   - selecting a source-file in the ECB-sources/history-buffer.

ECB offers two commands `ecb-nav-goto-next' (`C-c . n') and
`ecb-nav-goto-previous' (`C-c . p') to go forward and backward within this
navigation history-list. These commands are also available via the menu "ECB
-> Navigate".

Aside normal "location-browsing" this is useful for example in a scenario
where the buffer is narrowed to a tag (see `ecb-tag-visit-post-actions'):

  1. You edit a function

  2. Goto another function above the current in the same file

  3. Add a few lines

  4. Call ecb-nav-goto-previous

     Now you will edit at the same place in the function.

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

(1) e.g. a method, a variable or any other semantic tag


File: ecb.info,  Node: ECB-window synchronizing,  Next: Stealthy background tasks,  Prev: Back/forward navigation,  Up: Usage of ECB

6.12 Synchronization of the ECB-windows
=======================================

Per default ECB synchronizes automatically the contents of the ECB-windows
(e.g. tree-buffers) with the current active edit-window (rsp. the current
buffer of the edit window).

ECB distinguishes between the so called "basic" ECB-windows (for a general
description see *Note Basic ECB-windows::) and add-on ECB-windows (*note
Add-on ECB-windows::). This distinction is also important concerning
synchronization:

The basic ECB-windows are always synchronized together whereas for each add-on
ECB-window a separate synchronization option is offered.

This section describes at beginning some general synchronization aspects
(common for all ECB-windows, basic ones as well as add-ons), then the
synchronization of the basic-ECB-windows and finally the synchronization of
the add-on ECB-windows.

* Menu:

* General synchronization aspects::       General synchronization aspects
* Synchronization of basic ECB-windows::  Synchronization of basic ECB-windows
* Add-on synchronization::                Synchronization of add-on ECB-windows


File: ecb.info,  Node: General synchronization aspects,  Next: Synchronization of basic ECB-windows,  Prev: ECB-window synchronizing,  Up: ECB-window synchronizing

6.12.1 General synchronization aspects
--------------------------------------

For each separate ECB-window-synchronization (remember: One common for the
basic ECB-windows, one for each add-on ECB-window) ECB offers the following
option-triple (demonstrated for the basic ECB-windows):

   * `ecb-basic-buffer-sync':

     Enables or disables the synchronization in general.

     If active then the synchronization for the related
     ECB-window-buffers/windows takes place whenever a buffer changes in an
     edit window or if another edit-window with another buffer will be
     selected, if deactivated then never.  But you can also set this option
     to a list of major-modes and then the sync.  will only be done if the
     major-mode of the current buffer does NOT belong to this list.

     But in every case the synchronization only takes place if the major-mode
     of the current-buffer in the current selected edit-window has a relation
     to files or directories. Examples for the former one are all
     programming-language-modes like `c++-mode' or `java-mode', `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 a synchronization will never 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 of the dired-buffer in the edit-window.

   * `ecb-basic-buffer-sync-delay':

     This option takes only effect if the synchronization is switched on via
     `ecb-basic-buffer-sync' and determines when ECB synchronizes.

     This option sets the time in seconds (fractions allowed) Emacs must be
     idle before the related ECB-window(s) are synchronized. 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.

     Per default ECB always synchronizes on idle-basis and it is strongly
     recommened not to change this (ie. not setting the delay-option to nil)
     because this can be very performance consuming (e.g. at least the check
     if a synchronization must be performed is done after *every* key- or
     mouse-button press!

     Some fraction of a second is probably always the best choice, because it
     does not cost cpu-power and nonetheless the synchronization takes place
     quite immediately. So in most cases there is no need to bother with this
     option, just use the default value.

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

     For each separate synchronization a hook variable is offered where you
     can hook in with some elisp code if you need some tasks performed
     afterwards the synchronization has been finished.

     In most cases no hook will be needed.


Analogous to the shown options for the basic ECB-windows each add-on
ECB-window has its own separate triple of these options, named congruent to
the name of the buffer-name of the add-on ECB-window (e.g. for the analyse
ECB-window with the buffer-name hold in `ecb-analyse-buffer-name' these three
options are named `ecb-analyse-buffer-sync', `ecb-analyse-buffer-sync-delay'
and `ecb-analyse-buffer-sync-hook'.  For some specialities see *Note Add-on
synchronization::.

*Please note*: With the command `ecb-window-sync' you can do a manual
synchronization if the automatic one is switched off or if you just want to
do this! See the documantation of this command.


File: ecb.info,  Node: Synchronization of basic ECB-windows,  Next: Add-on synchronization,  Prev: General synchronization aspects,  Up: ECB-window synchronizing

6.12.2 Synchronization of the basic ECB-windows
-----------------------------------------------

This section describes some special aspects of the synchronizing of the basic
ECB-windows:

   * ECB-directories:

     This windows is synchronized to display the directory where the
     source-file which is displayed in the current active edit-window is
     located. If the source-path (i.e. an element of the option
     `ecb-source-path') containing this directory is not expanded it will be
     auto. expanded according to the value of the option
     `ecb-auto-expand-directory-tree' (*note ecb-directories::).

   * ECB-sources:

     The ECB-sources-buffer contains after synchronizing all the sources of
     the directory of the "current" source-file displayed in the edit-window.
     The entry of the "current" source-file is highlighted.

   * ECB-methods:

     Contains after synchronizing all the tags of the buffer in the current
     selected edit-window, i.e. all methods, variables etc... depending on
     the major-mode.

   * ECB-history:

     Highlights the entry of the buffer displayed in the current active
     edit-window if this buffer is a source-file.


The synchronization can be customized via the option triple
`ecb-basic-buffer-sync', `ecb-basic-buffer-sync-delay' and
`ecb-basic-buffer-sync-hook'. The four basic ECB-windows of ECB are always
synchonized together, never separate!


File: ecb.info,  Node: Add-on synchronization,  Prev: Synchronization of basic ECB-windows,  Up: ECB-window synchronizing

6.12.3 Synchronization of add-on ECB-windows
--------------------------------------------

Currently ECB has a separate synchronization for the add-on ECB-windows
ECB-analyse and ECB-symboldef and also for the eshell and
speedbar-integration. Customizing can be done via:

   * ECB-analyse: `ecb-analyse-buffer-sync', `ecb-analyse-buffer-sync-delay'
     and `ecb-analyse-buffer-sync-hook'

   * ECB-symboldef: `ecb-symboldef-buffer-sync',
     `ecb-symboldef-buffer-sync-delay' and `ecb-symboldef-buffer-sync-hook'

   * ECB-eshell: `ecb-eshell-buffer-sync', `ecb-eshell-buffer-sync-delay' and
     `ecb-eshell-buffer-sync-hook'

   * ECB-speedbar: `ecb-speedbar-buffer-sync',
     `ecb-speedbar-buffer-sync-delay' and `ecb-speedbar-buffer-sync-hook'


Each enabling- and delay-option has an additonal special value 'basic which is
the default for all these options because it allows to use the current setting
of `ecb-basic-buffer-sync' rsp. `ecb-basic-buffer-sync-delay' for the add-on
synchronization too. Example: If `ecb-basic-buffer-sync' is set to the value
`(Info-mode dired-mode)' then a setting of 'basic for
`ecb-analyse-buffer-sync' means that synchronization is always done unless
the current major-mode is Info-mode or dired-mode. Per default all add-on
synchronization enabling- and delay-options are set to 'basic with one
exeption: `ecb-analyse-buffer-sync-delay': See the documentation of this
option for a detailed description.

In general it is recommended to read the documentation of all these options.


File: ecb.info,  Node: Stealthy background tasks,  Next: Interactive ECB commands,  Prev: ECB-window synchronizing,  Up: Usage of ECB

6.13 Stealthy background-tasks of ECB
=====================================

ECB performs some tasks stealthily in the background and also interruptable
by the user because these tasks can be time-consuming and could otherwise
block ECB. Currently the following tasks are performed stealthily and in the
background by ECB:

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

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

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


All of these tasks (e.g. checking if a directory is empty or not) perform a
certain action for all directories or sources displayed in the current
visible tree-buffers of ECB. Normally there should be no annoying delay for
the user because each of these tasks will be only performed when Emacs is
idle and will be interrupted immediatelly when a user hits a key or clicks
the mouse but especially for remote-directories one single action (e.g.
checking if a certain directory is empty or checking the VC-state of a
sourcefile in such a remote directory) can be very time-consuming and such a
single action is not interruptable (an interrupt can only occur between the
single-actions for two directories or sources) For a further discussion how
to deal best with remote directories see *Note Remote directories::.!

ECB offers for all stealthy tasks three steps of activation:
   * `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.

In combination with the option `ecb-stealthy-tasks-delay' these three choices
already allow adapting the stealthy tasks to most needs. But to offer finest
granularity for which directories a certain stealthy task should be switched
on and for which not ECB offers for every stealthy task an additional option
which allows a finer adjustment:

   * Prescanning directories for emptyness:
     `ecb-prescan-directories-exclude-regexps'.

   * Checking the read-only-state of a sourcefile:
     `ecb-read-only-check-exclude-regexps'

   * Checking the VC-state of sourcefiles: `ecb-vc-directory-exclude-regexps'

These options take only effect when the related task is not completely
switched off. If this is the case they allow excluding certain directories
(or the sources of directories) from being processed by a certain stealthy
task.


File: ecb.info,  Node: Interactive ECB commands,  Prev: Stealthy background tasks,  Up: Usage of ECB

6.14 Interactive ECB commands
=============================

ECB offers a lot of interactive commands. Some of these commands prompt the
user in the minibuffer if called with a prefix argument.

Example: If `ecb-clear-history' is called with a prefix argument then you
will be prompted in the minibuffer with:

   Clear from history: [all, not-existing-buffers, existing-buffers]

You can choose one of the options enclosed in brackets with TAB-completion;
hitting RET direct after the prompt chooses auto. the first offered option
(in the example above "all").

*Please note*: The following interactive commands of ECB are listed without
the prefix "ecb-" (e.g. the command `ecb-activate' is listed with name
"activate"). This has been done for a better readable command index. *Note
Command Index::.

 -- Command: activate
     Activates ECB and creates the special buffers for the choosen layout.
     For the layout see `ecb-layout-name'. This function always raises the
     ECB-frame if called from another frame. This is the same as calling
     `ecb-minor-mode' with a positive argument.

 -- Command: add-all-buffers-to-history
     Add all current file-buffers to the history-buffer of ECB.  Dependend on
     the values of `ecb-history-make-buckets' and `ecb-history-sort-method'
     afterwards the history is bucketized or not and sorted either by name or
     by extension (if bucketized then the sorting is only within each
     bucket). If `ecb-history-sort-method' is nil the most recently used
     buffers are on the top of the history and the seldom used buffers at the
     bottom (again: when bucketized then this holds only within each bucket).

 -- Command: analyse-buffer-sync
     Synchronize the analyse buffer with the current buffer and point. This
     means in fact display the current analysis for current point.

 -- Command: change-layout &optional preselect-type
     Select a layout-name from all current available layouts (TAB-completion
     is offered) and change the layout to the selected layout-name. If
     optional argument PRESELECT-TYPE is not nil then you can preselect a
     layout-type \(TAB-completion is offered too) and then you will be asked
     only for layouts of that preselected type. Note: This function works by
     changing the option `ecb-layout-name' but only for current Emacs-session.

 -- Command: clear-history
     Clears the history-buffer.

 -- Command: customize
     Open a customize-buffer for all customize-groups of ECB.

 -- Command: customize-most-important
     Open a customize-buffer for the most important options of ECB.

 -- Command: create-new-layout
     Start process for interactively creating a new ECB-layout (*note
     Creating a new ECB-layout::).

 -- Command: cycle-maximized-ecb-buffers
     Cycles through all ecb-buffers of current layout by maximizing exactly
     one of the ecb-windows after every cycle-step.

 -- Command: cycle-through-compilation-buffers &optional choose-buffer
     Cycle through all compilation buffers currently open and display them
     within the compilation window `ecb-compile-window'. If the currently
     opened buffer within the compilation window is not a compilation buffer,
     we jump to the first compilation buffer. If not we try to loop through
     all compilation buffers. If we hit the end we go back to the beginning.

     If CHOOSE-BUFFER is not `nil' then the user will be prompted for the
     compilation-buffer to switch to.

 -- Command: deactivate
     Deactivates the ECB and kills all ECB buffers and windows.

 -- Command: delete-new-layout
     Select a layout-name for a layout created by `ecb-create-new-layout' and
     delete this layout. This means the layout-definition is removed from the
     file `ecb-create-layout-file' and the layout-function and associated
     aliases are unbound.

 -- Command: display-news-for-upgrade &optional FULL-NEWS
     Display the most important NEWS after an ECB-upgrade. If you call this
     function but no ECB-upgrade has been performed before starting ECB then
     nothing is display unless FULL-NEWS is not nil.

     If FULL-NEWS is not nil then the NEWS-file is displayed in another
     window.

 -- Command: display-upgraded-options
     Display a 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 saving is possible this command display where the options would be
     saved. It is that file Emacs uses to save customize-settings. This file
     is "computed" from the settings in `custom-file' and `user-init-file'
     (see the documentation of these variables).

     ECB automatically makes a backup-file of that file which will be
     modified by storing the upgraded rsp. renamed ECB-options. This backup
     file gets a unique name by adding a suffix ".before_ecb_<version>" to
     the name of the modified file. If such a file already exists ECB adds a
     unique number to the end of the filename to make the filename unique.
     This is a safety mechanism if something fails during storing the
     upgraded options, so you never lose the contents of your
     customization-file!

 -- Command: expand-methods-nodes &optional force-all
     Set the expand level of the nodes in the ECB-methods-buffer.

     This command asks in the minibuffer for an indentation level LEVEL. With
     this LEVEL you can precisely specify which level of nodes should be
     expanded. LEVEL means the indentation-level of the nodes.

     A LEVEL value X means that all nodes with an indentation-level <= X are
     expanded and all other are collapsed. A negative LEVEL value means all
     visible nodes are collapsed.

     Nodes which are not indented have indentation-level 0!

     Which node-types are expanded (rsp. collapsed) by this command depends
     on the options `ecb-methods-nodes-expand-spec' and
     `ecb-methods-nodes-collapse-spec'! With optional argument FORCE-ALL all
     tags will be expanded/collapsed regardless of the values of these
     options.

     Examples:
        - LEVEL = 0 expands only nodes which have no indentation itself.

        - LEVEL = 2 expands nodes which are either not indented or indented
          indented once or twice

        - LEVEL ~ 10 should normally expand all nodes expect there are nodes
          which are indented deeper than 10.

     Note 1: This command switches off auto. expanding of the method-buffer
     if `ecb-expand-methods-switch-off-auto-expand' is not nil. But it can be
     switched on again quickly with `ecb-toggle-auto-expand-tag-tree' or
     `[C-c . a]'.

     Note 2: All this is only valid for file-types parsed by semantic. For
     other file types which are parsed by imenu or etags (see
     `ecb-process-non-semantic-files') FORCE-ALL is always true!

 -- Command: dump-semantic-toplevel
     Dump the current semantic-tags in special buffer and display them.

 -- Command: eshell-current-buffer-sync
     Synchronize the eshell with the directory of current source-buffer.
     This is only done if the eshell is currently visible in the
     compile-window of ECB and if either this function is called
     interactively or `ecb-eshell-buffer-sync' is not nil.

 -- Command: eshell-recenter
     Recenter the eshell window so that the prompt is at the buffer-end.

 -- Command: expand-directory-nodes
     Set the expand level of the nodes in the ECB-directories-buffer. For
     argument LEVEL see `ecb-expand-methods-nodes'.

     Be aware that for deep structured paths and a lot of source-paths this
     command can last a long time - depending on machine- and
     disk-performance.

 -- Command: goto-window-analyse
     Make the ECB-analyse window the current window.

 -- Command: goto-window-compilation
     Goto the ecb compilation window `ecb-compile-window'.

 -- Command: goto-window-directories
     Make the ECB-directories window the current window. If
     `ecb-use-speedbar-instead-native-tree-buffer' is `dir' then goto to the
     speedbar-window.

 -- Command: goto-window-ecb-by-smart-selection
     selects a special ecb-browsing-window by smart selection. The command
     offers a list of all special ecb-windows by buffer-name. Selecting the
     buffer-name will select the displaying window. Which special ecb-windows
     are offered depends on the currently selected window: If not a special
     ecb-window is the currently selected-window then all edit-windows are
     offered in canonical order (means from top-left to button-right). If an
     ecb-window is the currently selected-window then all other(!) special
     ecb-windows are offered, beginning with the next special ecb-window to
     the current ecb-window (the following special ecb-windows also in
     canonical order). If there is only one senseful destination-ecb-window
     then this window is immediately selected, without confirmation (e.g.:
     There are two special ecb-windows and point stays in one of them. Or
     there is only one ecb-window and point stays either in one of the
     edit-windows or in the compile-window).

     If optional argument USE-IMMEDIATE-COMPLETION is nil then all possible
     destination-windows are displayed in the message-area and only hitting
     TAB offers completion. If USE-IMMEDIATE-COMPLETION is not nil then all
     possible destinations are immediately shown in a completion-buffer.

 -- Command: goto-window-edit-by-smart-selection
     Selects an edit-window by smart selection. The command offers a list of
     all edit-windows by buffer-name. Selecting the buffer-name will select
     the displaying window. Which edit-windows are offered depends on the
     currently selected window: If not an edit-window is the currently
     selected-window then all edit-windows are offered in canonical order
     (means from top-left to button-right). If an edit-window is the
     currently selected-window then all other(!) edit-windows are offered,
     beginning with the next edit-window to the current edit-window (the
     following edit-windows also in canonical order). If there is only one
     senseful destination-edit-window then this window is immediately
     selected, without confirmation (e.g.: There are two edit-windows and
     point stays in one of them. Or there is only one edit-window and point
     stays either in one of the special ecb-windows or in the compile-window).

     If optional argument USE-IMMEDIATE-COMPLETION is nil then all possible
     destination-windows are displayed in the message-area and only hitting
     TAB offers completion. If USE-IMMEDIATE-COMPLETION is not nil then all
     possible destinations are immediately shown in a completion-buffer.

 -- Command: goto-window-edit1
     Make the (first) edit-window window the current window.

 -- Command: goto-window-edit2
     Make the second edit-window (if available) window the current window.

 -- Command: goto-window-edit-last
     Make the last selected edit-window window the current window. This is
     the same as if `ecb-mouse-click-destination' is set to `last-point'.

 -- Command: goto-window-history
     Make the ECB-history window the current window.

 -- Command: goto-window-methods
     Make the ECB-methods window the current window. If
     `ecb-use-speedbar-instead-native-tree-buffer' is `method' then goto to
     the speedbar-window.

 -- Command: goto-window-sources
     Make the ECB-sources window the current window. If
     `ecb-use-speedbar-instead-native-tree-buffer' is `source' then goto to
     the speedbar-window.

 -- Command: history-filter
     Apply a filter to the history-buffer to reduce the number of entries.
     So you get a better overlooking. There are three choices:

        - Filter by extension: Just insert the extension you want the
          History-buffer being filtered.  Insert the extension without
          leading dot!

        - Filter by regexp: Insert the filter as regular expression.

        - No filter: This means to display an entry for all currently living
          file-buffers.

 -- Command: jde-display-class-at-point
     Display in the ECB-methods-buffer the contents (methods, attributes
     etc...) of the class which contains the definition of the "thing" under
     point (this can be a variable-name, class-name, method-name,
     attribute-name). This function needs the same requirements to work as
     the method-completion feature of JDEE (see `jde-complete')!. The
     source-file is searched first in `jde-sourcepath', then in
     `jde-global-classpath', then in $CLASSPATH, then in current-directory.

     Works only for classes where the source-code (i.e. the *.java-file) is
     available.

 -- Command: maximize-window-analyse
     Maximize the ECB-analyse-window. I.e. delete all other ECB-windows, so
     only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Works also if the ECB-analyse-window is not visible in
     current layout.

 -- Command: maximize-window-directories
     Maximize the ECB-directories-window, i.e. delete all other ECB-windows,
     so only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Works also if the ECB-directories-window is not visible
     in current layout.

 -- Command: maximize-window-sources
     Maximize the ECB-sources-window, i.e. delete all other ECB-windows, so
     only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Works also if the ECB-sources-window is not visible in
     current layout.

 -- Command: maximize-window-methods
     Maximize the ECB-methods-window, i.e. delete all other ECB-windows, so
     only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Works also if the ECB-methods-window is not visible in
     current layout.

 -- Command: maximize-window-history
     Maximize the ECB-history-window, i.e. delete all other ECB-windows, so
     only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Works also if the ECB-history-window is not visible in
     current layout.

 -- Command: maximize-window-speedbar
     Maximize the ECB-speedbar-window, i.e. delete all other ECB-windows, so
     only one ECB-window and the edit-window(s) are visible (and maybe a
     compile-window). Does nothing if the speedbar-window is not visible
     within the ECB-frame.

 -- Command: methods-filter
     Apply a filter to the Methods-buffer to reduce the number of entries.
     So you get a better overlooking. There are six choices:

        * Filter by protection: Just insert the protection you want the
          Methods-buffer being filtered: private, protected or public!

        * Filter by regexp: Insert the filter as regular expression.

        * Filter by tag-class: You can filter by the tag-classes of current
          major-mode. The available tag-classes come from the variable
          `semantic--symbol->name-assoc-list'. The are normally methods,
          variables etc.

        * Filter by current type: In languages which have types like Java or
          C++ this filter displays only the current type and all its members
          (e.g. attributes and methods). If ECB can not identify the current
          type in the source-buffer or in the methods-window then nothing
          will be done.

        * Filter by a filter-function: Such a function gets two arguments: a
          tag and the source-buffer of this tag. If the tag should be
          displayed (i.e. not being filtered out) then the function has to
          return not nil otherwise nil.

        * No special filter: This means to display all tags specified with
          the option `ecb-show-tokens'. If currently some of the above
          filters are applied they will be all removed.

        * Delete the last added: This removes only the topmost filter-layer,
          means that filter added last.

     The protection-, current-type- and the tag-class-filter are only
     available for semantic-supported sources.

     Be aware that the tag-list specified by the option `ecb-show-tags' is
     the basis of all filters, i.e. tags which are excluded by that option
     will never be shown regardless of the filter type here!

     All tags which match the applied filter(s) will be displayed in the
     Methods-buffer.

     If called with a prefix-argument or when optional arg INVERSE is not nil
     then an inverse filter is applied to the Methods-buffer, i.e. all tags
     which do NOT match the choosen filter will be displayed in the
     Methods-buffer!

     Per default the choosen filter will be applied on top of already
     existing filters. This means that filters applied before are combined
     with the new filter. This behavior can changed via the option
     `ecb-methods-filter-replace-existing'. But regardless of the setting in
     `ecb-methods-filter-replace-existing' applying one of the not-inverse
     filters protection, tag-class or current-type always replaces exactly
     already existing filters of that type. On the other hand applying more
     than one inverse tag-class- or protection-filter can make sense.

     Such a filter is only applied to the current source-buffer, i.e. each
     source-buffer can have its own tag-filters.

     The current active filter will be displayed in the modeline of the
     Methods-buffer [regexp, prot (= protection), tag-class, function (=
     filter-function)]. If an inverse filter has been applied then this is
     signalized by a preceding caret ^. If currently more than 1 filter is
     applied then always the top-most filter is displayed in the modeline but
     the fact of more than 1 filter is visualized by the number of the
     filters - included in parens. You can see all currently applied filters
     by moving the mouse over the filter-string in modeline of the
     Methods-buffer: They will displayed as help-echo.

     See the option `ecb-default-tag-filter' if you search for automatically
     applied default-tag-filters.

 -- Command: methods-filter-current-type
     Display in the Methods-buffer only the current type and its members.
     For further details see `ecb-methods-filter'.

 -- Command: methods-filter-delete-last
     Remove the most recent filter from the Methods-buffer. For further
     details see `ecb-methods-filter'.

 -- Command: methods-filter-function &optional inverse
     Filter the methods-buffer by a function. If INVERSE is not nil (called
     with a prefix arg) then an inverse filter is applied. For further
     details see `ecb-methods-filter'.

 -- Command: methods-filter-nofilter
     Remove any filter from the Methods-buffer. For further details see
     `ecb-methods-filter'.

 -- Command: methods-filter-protection &optional inverse
     Filter the methods-buffer by protection. If INVERSE is not nil (called
     with a prefix arg) then an inverse filter is applied. For further
     details see `ecb-methods-filter'.

 -- Command: methods-filter-regexp &optional inverse
     Filter the methods-buffer by a regexp. If INVERSE is not nil (called
     with a prefix arg) then an inverse filter is applied. For further
     details see `ecb-methods-filter'.

 -- Command: methods-filter-tagclass &optional inverse
     Filter the methods-buffer by tag-class. If INVERSE is not nil (called
     with a prefix arg) then an inverse filter is applied. For further
     details see `ecb-methods-filter'.

 -- Command: minor-mode &optional arg
     Toggle ECB minor mode. With prefix argument ARG, turn on if positive,
     otherwise off. Return non-`nil' if the minor mode is enabled.

 -- Command: nav-goto-previous
     Go backward in the navigation history-list, see *Note Back/forward
     navigation::.

 -- Command: nav-goto-next
     Go forward in the navigation history-list, see *Note Back/forward
     navigation::.

 -- Command: rebuild-methods-buffer
     Updates the methods buffer with the current buffer after deleting the
     complete previous parser-information, means no semantic-cache is used!
     Point must stay in an edit-window otherwise nothing is done. This method
     is merely needed for semantic parsed buffers if semantic parses not the
     whole buffer because it reaches a not parse-able code or for buffers not
     supported by semantic but by imenu or etags.

     Examples when a call to this function can be necessary:

        * If an Elisp-file is parsed which contains in the middle a defun X
          where the closing ) is missing then semantic parses only until this
          defun X is reached and you will get an incomplete ECB-method buffer.
          In such a case you must complete the defun X and then call this
          function to completely reparse the Elisp-file and rebuild the ECB
          method buffer!

        * For not semantic supported buffers which can be parsed by imenu or
          etags (see `ecb-process-non-semantic-files') because for these
          buffers there is no built-in auto-rebuild mechanism. For these
          buffers this command calls
          `ecb-rebuild-methods-buffer-for-non-semantic'.

     For non-semantic-sources supported by etags the option
     `ecb-auto-save-before-etags-methods-rebuild' is checked before
     rescanning the source-buffer and rebuilding the methods-buffer.

     If point is in one of the ecb-windows or in the compile-window then this
     command rebuids the methods-buffer with the contents of the
     source-buffer the last selected edit-window.

 -- Command: redraw-layout &optional ARG
     Redraw the ECB screen.

     Do not call this command from elisp-program but only interactively!

     Called without a prefix-argument the state of the ECB-frame-layout will
     preserved. This means:

        - The state of compile-window (hidden or visible) will be preserved
          but if visible then the height will be as specified in
          `ecb-compile-window-height'.

        - The state of the ECB-windows will be preserved (hidden or visible)
          but if visible then the sizes will be as specified in the layout
          (and with the options `ecb-windows-width' and `ecb-windows-height')
          or as stored with `ecb-store-window-sizes'.

     If called with ONE prefix-argument (`[C-u]') then the layout will be
     drawn with all ECB-windows and also with a visible compile-window (when
     `ecb-compile-window-height' is not nil). The splitting-state of the
     edit-area will be preserved.

     If called with TWO prefix-arguments (i.e. hitting `[C-u]' twice:
     (`[C-u]' `[C-u]') then an emergency-redraw will be performed.  This
     means the same as if called with one prefix-argument (s.a.) but the
     splitting-state of the edit-area will NOT be preserved but all
     edit-windows besides the current one will be deleted. Use this only if
     there are some anomalies after standard redraws!

     If the variable `ecb-redraw-layout-quickly' is not nil then the redraw
     is done by the `ecb-redraw-layout-quickly' function, otherwise by
     `ecb-redraw-layout-full'.

     Please not: It's strongly recommended to use the quick redraw only if
     you have really slow machines where a full redraw takes several seconds
     because the quick redraw is not really safe and has some annoying
     drawbacks! On normal machines the full redraw should be done in << 1s so
     there should be no need for the quick version!

 -- Command: restore-default-window-sizes
     Resets the sizes of the ECB windows to their default values.

 -- Command: restore-window-sizes
     Sets the sizes of the ECB windows to their stored values. See option
     `ecb-layout-window-sizes' and command `ecb-store-window-sizes'.

 -- Command: select-ecb-frame
     Selects the `ecb-frame' if ECB is activated - otherwise reports an error.

 -- Command: show-help &optional format
     Shows the online help of ECB either in Info or in HTML format depending
     on the value of `ecb-show-help-format'. If called with prefix argument,
     i.e. if FORMAT is not nil then the user is prompted to choose the format
     of the help (Info or HTML). If an error about not finding the needed
     help-file occurs please take a look at the options
     `ecb-help-info-start-file' and `ecb-help-html-start-file'!

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

 -- Command: show-layout-help
     Select a name of a layout and shows the documentation of the associated
     layout-function. At least for the built-in layouts the documentation
     contains a picture of the outline of the chosen layout.

 -- Command: show-tip-of-the-day
     Show tip of the day if `ecb-tip-of-the-day' is not nil or if called
     interactively.

 -- Command: sources-filter
     Apply a filter to the sources-buffer to reduce the number of entries.
     So you get a better overlooking. There are three choices:

        - Filter by extension: Just insert the extension you want the
          Sources-buffer being filtered.  Insert the extension without
          leading dot!

        - Filter by regexp: Insert the filter as regular expression.

        - No filter: This means to display an entry for every file in the
          current selected directory (all except these filter already
          filtered out by `ecb-source-file-regexps' and
          `ecb-sources-exclude-cvsignore').

     Such a filter is only applied to the current selected directory, i.e.
     each directory has its own filtered sources-buffer.

 -- Command: store-window-sizes &optional FIX
     Stores the sizes of the ECB windows for the current layout. The size of
     the ECB windows will be set to their stored values when
     `ecb-redraw-layout' or `ecb-restore-window-sizes' is called.  To reset
     the window sizes to their default values call
     `ecb-restore-default-window-sizes'. Please read also the documentation
     of `ecb-layout-window-sizes'!

     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. If a permanent compile-window is
     visible then ECB will tell you that window-sizes should be stored with
     hidden compile-window and ask you if you want proceed; if you proceed
     then the window-heights will be stored as fractions of current
     (frame-height minus current visible compile-window-height) so you should
     ensure that the current compile-window has its standard-height as
     specified in `ecb-compile-window-height'!. If FIX is not nil (means
     called with a prefix argument) then always the fixed values of current
     width and height are stored!

 -- Command: submit-problem-report
     Submit a problem report for the ECB to the ECB mailing-list. This
     command generates in the edit-window a problem-report which contains
     already the current values of all ECB options, the current
     backtrace-buffer if there is any and the current message-buffer. You
     will be asked for a problem-report subject and then you must insert a
     description of the problem. Please describe the problem as detailed as
     possible!

 -- Command: toggle-auto-expand-tag-tree &optional arg
     Toggle auto expanding of the ECB-methods-buffer. With prefix argument
     ARG, make switch on if positive, otherwise switch off. If the effect is
     that auto-expanding is switched off then the current value of
     `ecb-auto-expand-tag-tree' is saved so it can be used for the next
     switch on by this command.

 -- Command: toggle-compile-window &optional arg
     Toggle the visibility of the compile-window of ECB. With prefix argument
     ARG, make visible if positive, otherwise invisible. The height of the
     compile-window is always the current value of
     `ecb-compile-window-height'! If called and `ecb-compile-window-height'
     is nil then ECB asks for the height of the compile-window, sets this
     height as new value of `ecb-compile-window-height' and displays the
     compile-window (so if you have called this command by mistake and you do
     not want a compile-window you have to quit with <C-g>).

 -- Command: toggle-compile-window-height &optional arg
     Toggle whether the `ecb-compile-window' is enlarged or not. If ARG > 0
     then shrink or enlarge the the compile-window according to the value of
     `ecb-enlarged-compilation-window-max-height'. But never shrink below the
     value of `ecb-compile-window-height'. If ARG <= 0 then shrink
     `ecb-compile-window' to `ecb-compile-window-height' and if ARG is nil
     then toggle the enlarge-state.

 -- Command: toggle-ecb-windows &optional arg
     Toggle visibility of the ECB-windows. With prefix argument ARG, make
     visible if positive, otherwise invisible. This has nothing to do with
     (de)activating ECB but only affects the visibility of the ECB windows.
     ECB minor mode remains active!

 -- Command: toggle-layout &optional last-one
     Toggles between the layouts defined in `ecb-toggle-layout-sequence' (See
     also option `ecb-show-sources-in-directories-buffer'). Note: This
     function works by changing the options `ecb-layout-name' but only for
     current Emacs-session.

     If optional argument LAST-ONE is not nil (e.g. called with a prefix-arg)
     then always the last selected layout was choosen regardless of the
     setting in `ecb-toggle-layout-sequence'. The last selected layout is
     always that layout which was current direct before the most recent
     layout-switch. So now a user can switch to another layout via
     `ecb-change-layout' and always come back to his previous layout via
     `[C-u]' `ecb-toggle-layout'.

 -- Command: toggle-scroll-other-window-scrolls-compile &optional ARG
     Toggle the state of `ecb-scroll-other-window-scrolls-compile-window'.
     With prefix argument ARG, set it to `t', otherwise to `nil'. For all
     details about the scroll-behavior of `scroll-other-window' see the
     advice documentation of `other-window-for-scrolling'.

 -- Command: update-directories-buffer
     Updates the ECB directories buffer.

 -- Command: upgrade-options
     Check for all ECB-options if their current value is compatible to the
     defined type. If not upgrade it to the new type or reset it to the
     default-value of current ECB. Try also to upgrade renamed options.
     Displays all upgraded or reset options with their old (before the
     upgrade/reset) and new values.

 -- Command: window-sync
     ynchronizes all special ECB-buffers with current buffer.  Depending on
     the contents of current buffer this command performs different
     synchronizing tasks but only if ECB is active and point stays in an
     edit-window.

        * If current buffer is a file-buffer (or an indirect-buffer with a
          file-buffer as base-buffer) then all basic ECB-windows
          (directories, sources, methods and history) are synchronized with
          current buffer.

        * If current buffer is a dired-buffer then the directory- and the
          sources-tree-buffer are synchronized if visible

     In addition to this the hooks in `ecb-basic-buffer-sync-hook' run.

     If optional argument ONLY-BASIC-WINDOWS is not nil then only the basic
     tree-buffer directories, sources, methods and history are synchronized.
     Otherwise all registered special ecb-buffers are synchronized too.

     See *Note ECB-window synchronizing::.

Most of these functions are also available via the menu "ECB" and also via
the ECB key-map with prefix `C-c .' (see `ecb-minor-mode' for a complete list
of the keybindings).


File: ecb.info,  Node: Customizing,  Next: Submitting problem report,  Prev: Usage of ECB,  Up: Top

7 Customizing ECB
*****************

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

* Menu:

* General aspects::             General aspects for customizing ECB
* Most important options::      Which option you must know
* Customizable options::        All customizable options of ECB


File: ecb.info,  Node: General aspects,  Next: Most important options,  Prev: Customizing,  Up: Customizing

7.1 General aspects for customizing ECB
=======================================

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

* Menu:

* setq or customize::           Should i use setq or customize?
* Site-wide customizing::       Site-wide customizing of ECB


File: ecb.info,  Node: setq or customize,  Next: Site-wide customizing,  Prev: General aspects,  Up: General aspects

7.1.1 Setq or customize - what should i use?
--------------------------------------------

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

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

   - `ecb-analyse-buffer-sync-delay'

   - `ecb-analyse-show-node-info'

   - `ecb-basic-buffer-sync-delay'

   - `ecb-bucket-node-display'

   - `ecb-compile-window-height'

   - `ecb-compile-window-temporally-enlarge'

   - `ecb-compile-window-width'

   - `ecb-directories-show-node-info'

   - `ecb-eshell-buffer-sync-delay'

   - `ecb-exclude-parents-regexp'

   - `ecb-fix-window-size'

   - `ecb-font-lock-tags'

   - `ecb-highlight-tag-with-point-delay'

   - `ecb-history-show-node-info'

   - `ecb-key-map'

   - `ecb-layout-name'

   - `ecb-layout-window-sizes'

   - `ecb-methods-show-node-info'

   - `ecb-mode-line-data'

   - `ecb-mode-line-display-window-number'

   - `ecb-mode-line-prefixes'

   - `ecb-show-tags'

   - `ecb-source-path'

   - `ecb-sources-show-node-info'

   - `ecb-speedbar-buffer-sync-delay'

   - `ecb-symboldef-buffer-sync-delay'

   - `ecb-toggle-layout-sequence'

   - `ecb-tag-display-function'

   - `ecb-tree-do-not-leave-window-after-select'

   - `ecb-type-tag-display'

   - `ecb-type-tag-expansion'

   - `ecb-use-speedbar-instead-native-tree-buffer'

   - `ecb-windows-height'

   - `ecb-windows-width'


File: ecb.info,  Node: Site-wide customizing,  Prev: setq or customize,  Up: General aspects

7.1.2 Site-wide customizing of ECB
----------------------------------

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

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

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

7.1.2.1 Storing all option-settings in the users custom-file
............................................................

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

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

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

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

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

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

7.1.2.2 Using a special setq for site-wide settings
...................................................

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

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

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

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

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

First two helper-macros are needed:

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

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

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

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

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

(1) At least for the options for which `setq' is explicitly forbidden, but it
is recommended to use always such a mechanism

(2) The file `site-ecb.el' contains all site-wide settings for ECB


File: ecb.info,  Node: Most important options,  Next: Customizable options,  Prev: General aspects,  Up: Customizing

7.2 The most important options of ECB
=====================================

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

`ecb-source-path'
     Where ECB can find your sources. You must set this option!

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

`ecb-auto-activate'

`ecb-major-modes-show-or-hide'
     Auto. activation of ECB after start (*note Automatic activation::) or
     major-mode-based showing or hiding the ecb-windows.

`ecb-winman-escreen-number'
`ecb-winman-winring-name'
     Support of several window-managers (*note Window-managers and ECB::).

`ecb-key-map'
     All ECB-keybindings incl. a common prefix-key (*note Using the
     keyboard::).

`ecb-new-ecb-frame'
     Should ECB create a new frame at activation time.

`ecb-primary-secondary-mouse-buttons'
`ecb-mouse-click-destination'
     Define how to use the mouse (*note Using the mouse::).

`ecb-tree-buffer-style'
`ecb-tree-expand-symbol-before'
`ecb-tree-indent'
`ecb-truncate-lines'
     The look&feel of the trees in the tree-buffers. The former option
     defines the general style of the tree-buffers and the latter ones allow
     to customize the ascii-style tree-buffers (maybe you like a value of 4
     for the latter one if you display the expand-symbol before (*note
     Tree-buffer styles::).

`ecb-source-file-regexps'
     Which files will (not) be shown in ECB.

`ecb-layout-name'
`ecb-compile-window-height'
`ecb-compile-window-width'
`ecb-other-window-behavior'
     The ECB layout, means which windows you want to be displayed in the
     ECB-frame and also the location of these windows (*note Changing the
     ECB-layout::).

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

`ecb-tag-display-function'
`ecb-type-tag-display'
`ecb-type-tag-expansion'
`ecb-show-tags'
     How to display the entries in the ECB-method window for semantic
     supported sources (*note Customizing the display::). These options take
     only effect for semantic-sources (*note Definition of semantic- and
     non-semantic-sources::).

`ecb-process-non-semantic-files'
     Displaying file-contents for not by semantic supported files too, e.g.
     for LaTeX- and perl-sources (*note Non-semantic sources::).

But to make ECB working best for you it is also recommended to have a look at
*Note Customizable options::!


File: ecb.info,  Node: Customizable options,  Prev: Most important options,  Up: Customizing

7.3 All customizable options of ECB
===================================

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

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

* Menu:

* ecb-general::                 General customizing ECB
* ecb-tree-buffer::             Customizing the general tree layout
* ecb-directories::             Customizing the ECB-directories-tree
* ecb-sources::                 Customizing the ECB-sources-window
* ecb-methods::                 Customizing the ECB-methods-window
* ecb-history::                 Customizing the ECB-history-window
* ecb-analyse::                 Customizing the ECB-analyse-window
* ecb-symboldef::               Customizing the ECB-symboldef-window
* ecb-layout::                  Customizing the ECB-layout
* ecb-compilation::             Customizing the compile-window
* ecb-create-layout::           Customizing options for creating layouts
* ecb-face-options::            Customizing options for faces
* ecb-faces::                   Customizing the faces
* ecb-help::                    Customizing the online help of ECB
* ecb-eshell::                  Customizing the eshell-integration
* ecb-speedbar::                Customizing the speedbar-integration
* ecb-non-semantic::            Customizing parsing non-semantic sources
* ecb-winman::                  Customizing window-manager support
* ecb-mode-line::               Customizing the tree-buffer-modelines
* ecb-version-control::         Customizing the version-control-support


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

7.3.1 Group ecb-general
-----------------------

This group contains general settings for the Emacs code browser:

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

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

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

       2. `ecb-redraw-layout-before-hook'

       3. <Drawing the layout>

       4. `ecb-redraw-layout-after-hook'

       5. `ecb-activate-hook'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 -- User Option: grep-function
     Function used for performing a grep. The popup-menu of the tree-buffers
     "Directories", "Sources" and "History" offer to grep the "current"
     directory:
        - Directory-buffer: The grep is performed in the current
          popup-directory after clicking the right mouse-button onto a node.

        - Sources-buffer: The grep is performed in the current selected
          directory.

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

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

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

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

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

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

    `<function>:'
          The function to bind to the key. This can also be a
          lambda-expression .

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

     You MUST change this option via customize to take effect!

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

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

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

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

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

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

        * The `^' notation for control characters also works: ^M = C-m.

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

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

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

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

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

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

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

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


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

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

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

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

 -- User Option: version-check
     Checks at start-time if the requirements are fulfilled. It checks if the
     required versions of CEDET is installed and loaded into Emacs.

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

