This is ecb.info, produced by makeinfo version 4.3 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)

ECB (Emacs Code Browser) is a source code browser for Emacs. It is a
global minor-mode which displays a couple of windows that can be used
to browse directories, files and methods. It supports method parsing
for Java, C, C++, Elisp and some more.

*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://home.swipnet.se/mayhem/ecb.html>.

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

* Menu:

* Install and first steps::     Installing ECB and first steps
* Overview::                    Introduce basic concepts
* 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
* Tips and tricks::             Useful hints and tips
* Elisp programming::           Entry points for elisp programmers
* Conflicts and bugs::          Known Conflicts with other packages and bugs
* 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
* First steps::                 First steps after activating ECB first time

Overview

* ECB Directories::             Contents of the ECB Directories-buffer
* ECB Sources::                 Contents of the ECB Sources/history-buffer
* ECB Methods::                 Contents of the ECB Methods-buffer

Activation and Deactivation

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

Usage of ECB

* Using the mouse::             Working with the mouse
* Using the keyboard::          Working with the keyboard
* The edit-window::             How to use the edit-window(s)
* Temp- and compile-buffers::   Displaying temp- and compilation-buffers
* The Methods buffer::          Using and customizing he Methods-buffer
* The ECB-layout::              Changing, customizing, redrawing the layout
* Hiding the ECB windows::      Hiding/Showing the ECB-windows
* Back/forward navigation::     Back- and forward navigation like a browser
* ECB-window synchronizing::    Auto./manual synchronizing the ECB-windows
* Interactive ECB commands::    All interactive user-commands of ECB

Working with the keyboard in the ECB-windows

* Navigation::                  Keyboard navigation in a tree-buffer
* Incremental search::          Find nodes as fast as possible

Using and customizing the ECB-Methods buffer

* Customizing the display::     How to customize the Methods-buffer display
* Rebuilding the Methods::      When to rebuild the Methods-buffer

Changing, customizing and redrawing the ECB-layout

* Changing the ECB-layout::     How to change and customize the layout
* Redrawing the ECB-layout::    How and when redrawing the layout

Customizing ECB

* Most important options::      Which option you must know
* Customizable options::        All customizable options of ECB

All customizable options of ECB

* ecb-general::                 General customizing ECB
* ecb-directories::             Customizing the ECB-directories
* ecb-sources::                 Customizing the ECB-sources
* ecb-methods::                 Customizing the ECB-methods
* ecb-history::                 Customizing the ECB-history
* ecb-layout::                  Customizing the ECB-layout
* ecb-face-options::            Customizing options for faces
* ecb-faces::                   Customizing the faces
* ecb-download::                Customizing how to download ECB
* ecb-help::                    Customizing the online help of ECB

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

Tips and tricks

* Changing faces::              Changing faces in the ECB tree-buffers
* Small screens::               Working with small screens
* Simulating speedbar::         Simulating speedbar without an extra frame
* Integrating speedbar::        Integrating speedbar in the ECB-frame
* Optimize scrolling::          Optimize scrolling in the edit-window
* Large directories::           Working with large directories
* Using eshell::                Optimal using of eshell in ECB

Entry points for elisp programmers

* List of variables::           Which variables an elisp-program can use
* List of hooks::               All available hooks
* tree-buffer::                 Some words to the tree-buffer-library
* Adviced functions::           How to deal with the adviced functions
* New layouts::                 How to program new layouts

Known conflicts and bugs of ECB

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

Known conflicts with other packages

* VC::                          Conflicts with Version Control
* follow-mouse::                Conflicts with follow-mouse.el
* avoid::                       Conflicts with avoid.el
* calendar::                    Conflicts with calendar.el
* calculator::                  Conflicts with calculator.el


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

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

This chapter describes how to install ECB and what are the first steps
after activation of ECB

* Menu:

* Installation::                Installation of ECB
* First steps::                 First steps after activating ECB first time


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

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

*IMPORTANT*: The following steps 1., 2., 3., 6. and 7. describe
installation tasks if you got the archive in the format available at
the ECB website. If you use XEmacs and got ECB as regular
XEmacs-package (e.g. downloaded and installed by the net-installer of
XEmacs) then the steps 1., 2., 3., 6. and 7. are not necessary for you.

1. Unpack the ECB archive.

2. Read the file `README' in the ECB-directory and install the required
   semantic- and eieio-version.

   *Note*: ECB maybe requires a newer version of these libraries than
   shipped with Emacs or XEmacs. You have to install exactly a version
   ECB requires and also to make sure that the correct version is loaded
   into (X)Emacs!

   But ECB checks auto. during start-time if the correct versions of
   semantic and eieio are installed and gives you proper feedback.
   *Note Download required packages::.

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

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

4. Add to your `.emacs' or `site-lisp/site-start.el' the line:

      (require 'ecb)

5. Restart Emacs.

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

6. Call `ecb-byte-compile'

   This byte compiles ECB. You can safely ignore all messages.  (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.)

7. Install the supplied `ecb.info'

   The ECB distribution contains a file `ecb.info' which is 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 file `ecb.info' into the info-directory of Emacs

      2. Install it 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 file `ecb.info' into the info-directory of Emacs and
      modify the file `dir' manually.

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



File: ecb.info,  Node: First steps,  Prev: Installation,  Up: Install and first steps

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. Read the online-help of ECB:

   The online-help of ECB is available via

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

    - pressing `C-c . o' or

    - using the menu "ECB".

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

3. Start working with ECB.

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

(1) This means first hitting the keys `M' (Meta- or Alt-key) and `x'
simultaniously, 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: Activation and Deactivation,  Prev: Install and first steps,  Up: Top

Overview
********

ECB is a global minor-mode which offers a few "ECB-windows" for
browsing your sources comfortable with the mouse and the keyboard.
These "special" windows are also called "tree-buffer" in this manual.
Every "item" in such a tree-buffer, i.e. every line, is also called a
"node" of this tree-buffer. There are currently three different types
of ECB-windows/tree-buffers:

 - ECB-Directories

 - ECB-Sources

 - ECB-Methods

In addition to these "special" ECB-windows you have always one or two
"edit-windows" (*note The edit-window::) in the ECB-frame and at the
bottom a "compilation-window" (optional), where all the output of
Emacs-compilation (compile, grep etc.) is shown (*note Temp- and
compile-buffers::).

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

   ------------------------------------------------------------------
   |              |                                                 |
   |  Directories |                                                 |
   |              |                                                 |
   |--------------|                                                 |
   |              |                                                 |
   |  Sources     |                                                 |
   |              |                                                 |
   |--------------|                 Edit-window(s)                  |
   |              |        (can be splitted in two windows)         |
   |  Methods     |                                                 |
   |              |                                                 |
   |--------------|                                                 |
   |              |                                                 |
   |  History     |                                                 |
   |              |                                                 |
   ------------------------------------------------------------------
   |                                                                |
   |                 Compilation-window (optional)                  |
   |                                                                |
   ------------------------------------------------------------------

In the following subsections the "special" ECB-windows will be
explained in detail.

* Menu:

* ECB Directories::             Contents of the ECB Directories-buffer
* ECB Sources::                 Contents of the ECB Sources/history-buffer
* ECB Methods::                 Contents of the ECB Methods-buffer

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

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


File: ecb.info,  Node: ECB Directories,  Next: ECB Sources,  Prev: Overview,  Up: Overview

ECB Directories
===============

 * 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,
   *Note Usage of ECB::.

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

 * Right clicking on an item will open a popup menu where different
   operations on the item under the mouse cursor can be performed.

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


File: ecb.info,  Node: ECB Sources,  Next: ECB Methods,  Prev: ECB Directories,  Up: Overview

ECB Sources
===========

 * Source files can be selected by clicking a mouse button (*note Using
   the mouse::) or hitting RETURN (*note Using the keyboard::) on the
   source row in the "ECB-Sources" or "ECB- History" windows.

   IMPORTANT: If you 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 or
   ECB-History windows then the source will not be displayed in the
   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::. 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 the
   other edit window.

 * Right clicking on a source file will open a popup menu where
   different operation on the item under the mouse cursor can be
   performed.


File: ecb.info,  Node: ECB Methods,  Prev: ECB Sources,  Up: Overview

ECB Methods
===========

 * The "ECB-Methods" buffer contains the methods (and variables, if you
   want) in the selected source file. When a method/variable is selected
   with the primary mouse button  or RETURN (*note Usage of ECB::) the
   edit buffer will jump to the method/variable.

 * Clicking on a method/variable with the secondary mouse button or
   C-RETURN (*note Usage of ECB::) will jump to the method in the other
   edit window.


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

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

This chapter describes all aspects of activating and deactivating ECB.

* Menu:

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


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

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

Call `M-x ecb-activate' and `M-x ecb-deactivate' to activate or
deactivate ECB. 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'.


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

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

There are three options for auto. (de)activation ECB after Emacs-start
and also major-mode based.

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

`ecb-major-modes-activate'
`ecb-major-modes-deactivate'
   These option give you the possibility to activate (rsp. deactivate)
   ECB on a major-mode basis, means you can define for which major-modes
   ECB should be activated and for which modes it should activated.

   If activating or deactivating is too strong you can also customize
   ECB with these two option only hiding/showing it's ECB-windows
   (tree-buffers) on a major-mode basis. At last this is nothing more
   than auto. calling `ecb-toggle-ecb-windows' (*note Interactive ECB
   commands:: depending which major-mode is active.


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

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-window::             How to use the edit-window(s)
* Temp- and compile-buffers::   Displaying temp- and compilation-buffers
* The Methods buffer::          Using and customizing he Methods-buffer
* The ECB-layout::              Changing, customizing, redrawing the layout
* Hiding the ECB windows::      Hiding/Showing the ECB-windows
* Back/forward navigation::     Back- and forward navigation like a browser
* ECB-window synchronizing::    Auto./manual synchronizing the ECB-windows
* 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

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:

A click with the primary button causes the main effect in each
ECB-buffer:

 - ECB Directories: Expanding/collapsing nodes and displaying files in
   the ECB-Sources buffer.

 - ECB sources/history: Opening the file in that edit-window specified
   by the option `ecb-primary-mouse-jump-destination'.

 - ECB Methods: Jumping to the method in that edit-window specified by
   the option `ecb-primary-mouse-jump-destination'.

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 can get the same
effect if you click with the primary mouse-button onto a node while
SHIFT is held. In general: Via `ecb-show-node-info-in-minibuffer' you
can specify in a detailled manner for every ECB tree-buffer when and
which node-info should be displayed in the minibuffer.

IMPORTANT: Doing this SHIFT-click in the ECB-Sources or ECB-History
windows does not only show the node in the echo-area but it also 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.

The secondary mouse-button is for opening (jumping to) the file in the
other window (see the documentation
`ecb-primary-mouse-jump-destination').

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

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.

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

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


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

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 without a mouse.

IMPORTANT: Do not modify `ecb-mode-map' directly! The option
`ecb-key-map' defines all ECB keybindings, including a common prefixkey
(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::).!

* Menu:

* Navigation::                  Keyboard navigation in a tree-buffer
* Incremental search::          Find nodes as fast as possible


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

Navigation
----------

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. The terms primary and secondary are
   explained in *Note Using the mouse::. S-RETURN is the same as the
   SHIFT-click (*note ECB Sources::). See also the option
   `ecb-tree-RET-selects-edit-window' and the function
   `ecb-toggle-RET-selects-edit-window' which is bound to `C-t' in each
   tree-buffer of ECB!

 * 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 left- and
right-arrow keys work in the ECB tree-window in the following smart way
if onto an expandable node:

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

 * Right-arrow: If node is not expanded then it will be expanded.

Onto a not expandable node the horizontal arrow-keys go one character
in the senseful correct direction.


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

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

Each displayable key (e.g. all keys normally bound to
`self-insert-command') is appended to the current seach-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 greates 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 thi
incremental search ignores the following non interesting stuff:

 - any leading spaces

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

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

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

 - const specifier for variables

This means: Just type in the prefix (resp. 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 . m'.


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

Working with the edit-window
============================

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

ECB offers you to advice the following functions so they work best with
ECB:

 - `other-window'

 - `delete-window'

 - `delete-other-windows'

 - `split-window-horizontally'

 - `split-window-vertically'

 - `switch-to-buffer'

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

 - `other-window-for-scrolling'

The behavior of the adviced functions is:

 * All these adviced functions behaves exactly like their corresponding
   original functons 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.

 * If called in a not edit-window of ECB all these function jumps first
   to the (first) edit-window, so you can never destroy the ECB-window
   layout unintentionally.

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

ATTENTION: If you want to work within the edit-window with splitting
and unsplitting the edit-window(s) it is highly recommended to use the
adviced-functions of ECB instead of the original Emacs-functions (see
above). Per default ECB does advice all of the functions mentioned
above but with the option `ecb-advice-window-functions' you can
customizes which functions should be adviced by ECB. Please read
carefully the documentation of this option!

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


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

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.
If the edit-window is already splitted then the temp-buffer is
displayed in the "other" edit-window otherwise the edit-window will be
splitted first. The variables `temp-buffer-max-height' and
`temp-buffer-resize-mode' work also correctly with ECB.

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

This is default behavior of ECB. But there is also another way to
display such buffers:

 * With the option `ecb-compile-window-height' you can define if the ECB
   layout should contain per default a compilation-window at the bottom
   (and if yes the height of it). If yes ECB displays all output of
   compilation-mode (compile, grep etc.) in this special window. Same
   for displaying help-buffers or similar stuff.

 * 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 function `ecb-toggle-enlarged-compilation-window'.

 * With the option `ecb-layout-switch-to-compilation-window' you can
   modify the switch-to-buffer...-functions to work best if your layout
   contains a compilation-window. See the docstring of this option.

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

But because ECB works best without such a durable compilation-window
you should read the documentation of these two options carefully!


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

Using and customizing the ECB-Methods buffer
============================================

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

* Menu:

* Customizing the display::     How to customize the Methods-buffer display
* Rebuilding the Methods::      When to rebuild the Methods-buffer


File: ecb.info,  Node: Customizing the display,  Next: Rebuilding the Methods,  Prev: The Methods buffer,  Up: The Methods buffer

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

The ECB-Methods buffer is probably the most important browsing window
offered by ECB. It displays all semantic informations of the current
buffer in the edit-window.

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

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

`ecb-show-tokens'
   Which semantic-tokens (e.g. types, methods, variables etc.) should be
   displayed and should they be collapsed, flattened or expanded.
   Sorting is also possible.

`ecb-font-lock-tokens'
`ecb-type-token-display'
   How to fontify the tokens in the Method-buffer

`ecb-token-display-function'
   ECB and semantic offer several predefined functions for displaying
   the tokens. Here you can customize, what informations tokens 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!


File: ecb.info,  Node: Rebuilding the Methods,  Prev: Customizing the display,  Up: The Methods buffer

Rebuilding the Methods-buffer
-----------------------------

In almost all cases there is *NO* need to manually rebuild the
method-buffer, because it is always done automatically if necessary.
But nevertheless there exist a few rare scenarios where a complete
manual rebuild can be necessary. Here is one example:

Depending on the semantic-version: If an elisp-file is parsed which
contains a defun X in the middle 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 completely reparse the elisp-file and rebuild the ECB
method buffer!

A complete manually rebuild is done by `ecb-rebuild-methods-buffer'.


File: ecb.info,  Node: The ECB-layout,  Next: Hiding the ECB windows,  Prev: The Methods buffer,  Up: Usage of ECB

Changing, customizing and redrawing the ECB-layout
==================================================

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

* Menu:

* Changing the ECB-layout::     How to change and customize the layout
* Redrawing the ECB-layout::    How and when redrawing the layout


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

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

ECB offers several predefined layouts with different sets and also
different locations of ECB-windows. To see which layouts are available
and choose an appropriate one just customize the option
`ecb-layout-nr'. The docstring of this option explains how to see the
different available layouts.

If you want to switch fast between some layouts see the option
`ecb-toggle-layout-sequence' and the command `ecb-toggle-layout' (*note
Simulating speedbar::)

In addition to the general layout you can specify if the layout should
contain a durable 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 location of the collapse- and expand-symbols and the
indendation of sub-nodes in a tree. See `ecb-tree-indent' and
`ecb-tree-expand-symbol-before'.


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

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

If you have unintenionally 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!


File: ecb.info,  Node: Hiding the ECB windows,  Next: Back/forward navigation,  Prev: The ECB-layout,  Up: Usage of ECB

Hiding/Showing the ECB windows
==============================

With `ecb-toggle-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 nr.10
(*note Tips and tricks::) or if you want to have maximum space for
editing and you don't need the browsing windows all the time.


File: ecb.info,  Node: Back/forward navigation,  Next: ECB-window synchronizing,  Prev: Hiding the ECB windows,  Up: Usage of ECB

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 token(1) in the edit-window after

 - selecting a token 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 historylist. These commands are also available via the
menu "ECB -> Navigate".

Aside normal "location-browsing" this is usefull for example in a
scenario where `ecb-token-jump-narrow' is activated:

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 token


File: ecb.info,  Node: ECB-window synchronizing,  Next: Interactive ECB commands,  Prev: Back/forward navigation,  Up: Usage of ECB

Synchronization of the ECB-windows
==================================

Per default ECB synchronizes automatically the contents of the
ECB-windows/tree-buffers with the current active edit-window (rsp. the
current buffer of the edit window):

 * ECB-directories:

   This windows is synchronized to display the directory where the
   source-file which is displayed in the 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 tokens of the buffer in the
   edit-window, i.e. all methods, variables etc... depending of the
   major-mode.

 * ECB-history:

   Highlights the entry of the buffer displayed in the edit-window if
   this buffer is a source-file.


This feature can be customized with the option `ecb-window-sync':

If active then the synchronization takes place always a buffer changes
in the edit window, 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 belongs NOT to this list.

But in every case the synchronization takes only place if the
major-mode of the current-buffer in the 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 never a synchronization will be done!

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

*NOTE*: With the command `ecb-current-buffer-sync' you can do a
manually synchronization if the automatic one is switched off or if you
just want to do this!


File: ecb.info,  Node: Interactive ECB commands,  Prev: ECB-window synchronizing,  Up: Usage of ECB

Interactive ECB commands
========================

ECB offers the 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").

These are the interactive commands of ECB (listed in alphabetical
order):

 - Command: ecb-activate
   Activates the ECB and creates all the buffers and draws the
   ECB-screen with the actually choosen layout (see `ecb-layout-nr').
   This function raises always the ECB-frame if called from another
   frame. This is the same as calling `ecb-minor-mode' with a positive
   argument.

 - Command: ecb-add-all-buffers-to-history
   Add all current file-buffers to the history-buffer of ECB.

 - Command: ecb-clear-history &optional clearall
   Clears the ECB history-buffer. If CLEARALL is `nil' then the
   behavior is defined in the option `ecb-clear-history-behavior'
   otherwise the user is prompted what buffers should be cleared from
   the history-buffer. For further explanation see
   `ecb-clear-history-behavior'.

 - Command: ecb-current-buffer-sync &optional force
   Synchronizes the ECB buffers with the current buffer. Unless FORCE
   is non-`nil' then do this only if current-buffer differs from the
   source displayed in the ECB tree-buffers.

 - Command: ecb-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 swtich to.

   See also the option `ecb-layout-switch-to-compilation-window'!  The
   difference is that this cycling-function offers only
   compilation-buffers in the sense of `ecb-compilation-buffer-p'
   whereas the adviced version of `switch-to-buffer' offers any buffer
   but switches to `ecb-compile-window' if a compilation-buffer!

 - Command: ecb-deactivate
   Deactivates the ECB and kills all ECB buffers and windows.

 - Command: ecb-display-upgraded-options
   Display a message-buffer which options have been upgraded or reset.

 - Command: ecb-download-ecb
   Download ECB from the ECB-website and install it. For this the
   options `ecb-download-url' and `ecb-download-version' must be set
   correct, whereas the default value of the former one should always be
   correct.

   For details about downloading and what requirements must be satisfied
   see *Note Downloading new versions::!

   After sucessfull downloading the new ECB will be installed in a
   directory parallel to current ECB-directory. After adding this new
   directory tp `load-path' and restarting Emacs the new ECB version can
   be activated by `ecb-activate'.

 - Command: ecb-goto-window-compilation
   Goto the ecb compilation window `ecb-compile-window'.

 - Command: ecb-goto-window-directories
   Make the ECB-directories window the current window.

 - Command: ecb-goto-window-edit1
   Make the (first) edit-window window the current window.

 - Command: ecb-goto-window-edit2
   Make the second edit-window (if available) window the current window.

 - Command: ecb-goto-window-history
   Make the ECB-history window the current window.

 - Command: ecb-goto-window-methods
   Make the ECB-methods window the current window.

 - Command: ecb-goto-window-sources
   Make the ECB-sources window the current window.

 - Command: ecb-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: ecb-nav-goto-previous
   Go backward in the navigation historylist, *Note Back/forward
   navigation::.

 - Command: ecb-nav-goto-next
   Go forward in the navigation historylist, *Note Back/forward
   navigation::.

 - Command: ecb-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 if semantic parses not the whole buffer
   because it reaches a not parsable code. Examples when a call to this
   function is 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!

   If you change only the name of a method or a variable and you want
   the new name be shown immediately in the ECB-method buffer then you
   must call this function.

 - Command: ecb-redraw-layout
   Redraw the ECB screen. 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 drawback should be done in << 1s!

 - Command: ecb-show-help &optional format
   Shows the online help of ECB either in Info or in HTML format
   depending of 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'!

 - Command: ecb-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: ecb-toggle-ecb-windows &optional arg
   Toggle visibilty 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: ecb-toggle-enlarged-compilation-window &optional arg
   Toggle whether the `ecb-compile-window' is enlarged or not. If ARG >
   0 then enlarge to a sensefull value (see below), if ARG <= 0 then
   shrink `ecb-compile-window' to `ecb-compile-window-height' and if
   ARG is nil then toggle the enlarge-state.

   The `ecb-compile-window' is enlarged to the following value: At least
   to the value of `ecb-compile-window-height' and max. to half of the
   frame-height of the ECB-frame, best depending on the values of
   `compilation-window-height' (before ECB was started!) and the number
   of lines of current buffer in `ecb-compile-window'. If
   `compilation-window-height' is set before ECB was started then ECB
   never enlarges the `ecb-compile-window' over the value of
   `compilation-window-height'! Changing this option during activated
   ECB takes first effect after restarting ECB!

 - Command: ecb-toggle-layout
   Toggles between the layouts defined in `ecb-toggle-layout-sequence'.
   Note: This function works by changing the options `ecb-layout-nr' and
   `ecb-show-sources-in-directories-buffer' but only for current
   Emacs-session.

 - Command: ecb-update-directories-buffer
   Updates the ECB directories buffer.

 - Command: ecb-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.

Most of these functions are also available via the menu "ECB" and also
via the ECB keymap 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

Customizing ECB
***************

This chapter describes how to customize ECB for your personal taste.
The first chapter gives an overview of the most important options and
the second one lists all options of ECB.

* Menu:

* Most important options::      Which option you must know
* Customizable options::        All customizable options of ECB

*ATTENTION*: The best way you customize all the options of ECB is via
the customize-feature of (X)Emacs, i.e. means calling the commands
`customize-option' or `customize-group' etc. This is also the strongly
recommended way!

But of course you can also use `setq' or some elisp-code to change the
values of many but not all of the options. The values of the following
options *MUST NOT* be changed via `setq' or elisp-code but only with
the customize-feature!

 - `ecb-source-path'

 - `ecb-tree-RET-selects-edit-window'

 - `ecb-font-lock-tokens'

 - `ecb-bucket-token-display'

 - `ecb-token-display-function'

 - `ecb-type-token-display'

 - `ecb-show-tokens'

 - `ecb-exclude-parents-regexp'

 - `ecb-highlight-token-with-point-delay'

 - `ecb-window-sync-delay'

 - `ecb-show-node-info-in-minibuffer'

 - `ecb-key-map'

 - `ecb-layout-nr'

 - `ecb-compile-window-height'

 - `ecb-compile-window-temporally-enlarge'

 - `ecb-windows-width'

 - `ecb-windows-height'

 - `ecb-advice-window-functions'

 - `ecb-layout-window-sizes'

 - `ecb-mode-line-prefixes'

