\input texinfo @c -*-texinfo-*- @c Copyright (C) 2000 - 2009 Jesper Nordenberg, @c Klaus Berndl, @c Kevin A. Burton, @c Free Software Foundation, Inc. @c Author: Klaus Berndl @c Maintainer: Klaus Berndl @c Keywords: browser, code, programming, tools @c Created: 2001 @c This program is free software; you can redistribute it and/or modify it under @c the terms of the GNU General Public License as published by the Free Software @c Foundation; either version 2, or (at your option) any later version. @c This program is distributed in the hope that it will be useful, but WITHOUT @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS @c FOR A PARTICULAR PURPOSE. See the GNU General Public License for more @c details. @c You should have received a copy of the GNU General Public License along with @c GNU Emacs; see the file COPYING. If not, write to the Free Software @c Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @c $Id$ @setfilename ecb.info @settitle ECB - the Emacs Code Browser @c If we want only one index for concepts, functions and variables @c @syncodeindex vr cp @c @syncodeindex fn cp @c in info we do not want paragraph indenting @ifinfo @paragraphindent 0 @end ifinfo @exampleindent 3 @footnotestyle end @c The version number is auto-frobbed from the Makefile, so you should @c edit the Makefile to change the version number. mechanism stolen @c from Tramp @macro ecbver{} 2.40 @end macro @dircategory GNU Emacs Lisp @direntry * ECB: (ecb). Emacs Code Browser @end direntry @titlepage @sp 10 @center @titlefont{ECB version @ecbver{} - User manual} @vskip 0pt plus 1 fill Copyright @copyright{} 2000 - 2009 Jesper Nordenberg, Klaus Berndl @end titlepage @node Top, Install and first steps, (dir), (dir) @comment node-name, next, previous, up @ifnottex This is the user manual for ECB version @ecbver{}. @end ifnottex ECB stands for "Emacs Code Browser". While (X)Emacs already has good @strong{editing} support for many modes, its @strong{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: @itemize @bullet @item A directory tree, @item a list of source files in the current directory (with full support and display of the VC-state), @item 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) @item a history of recently visited files (groupable by several criterias), @item helpful informations and possible completions according to the current context which is computed by the semantic-analyzer for some sort of intellisense, @item the Speedbar and @item output from compilation (the "*compilation*" window) and other modes like help, grep etc. or whatever a user defines to be displayed in this window. @end itemize As an added bonus, ECB makes sure to keep these informational windows visible, even when you use @kbd{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. @iftex @sp 1 @end iftex @strong{Please note}: Experienced ECB users find a complete alphabetical list of all commands and user-options in @ref{Interactive ECB commands} and @ref{Customizable options}. @c In the following two paragraphs we distinct between HTML-, info-, @c and tex-format concerning the display of the URLs. @ifinfo The latest version of ECB can always be found at the URL @url{http://ecb.sourceforge.net}. To send bug reports, or participate in discussions about ECB, use the mailing list @email{ecb-list@@lists.sourceforge.net} via the URL @url{http://lists.sourceforge.net/lists/listinfo/ecb-list}. @end ifinfo @iftex @sp 1 The latest version of ECB can always be found at the URL @* @url{http://ecb.sourceforge.net}. @sp 1 To send bug reports, or participate in discussions about ECB, use the mailing list @*@email{ecb-list@@lists.sourceforge.net} via the URL @* @url{http://lists.sourceforge.net/lists/listinfo/ecb-list}. @end iftex @ifhtml The latest version of ECB can always be found at @uref{http://ecb.sourceforge.net} To send bug reports, or participate in discussions about ECB, use the mailing list @email{ecb-list@@lists.sourceforge.net} via @uref{http://lists.sourceforge.net/lists/listinfo/ecb-list} @end ifhtml @strong{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 @ifhtml @uref{http://ecb.sourceforge.net} @end ifhtml @ifnothtml @url{http://ecb.sourceforge.net} @end ifnothtml 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 @comment * Index:: @detailmenu --- 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 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 @end detailmenu @end menu @node Install and first steps, Overview, Top, Top @chapter 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 @end menu @node Installation, Setting up Emacs, Install and first steps, Install and first steps @section 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 @end menu @node Requirements, ECB as XEmacs-package, Installation, Installation @subsection 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: @enumerate @item Emacs-version: ECB works only with (X)Emacs >= 21! If you have an older one, please upgrade. @item 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 @url{http://cedet.sourceforge.net}, read the setup-instructions in @url{http://cedet.sourceforge.net/setup.shtml} and read also the shipped file @file{INSTALL}. @strong{Please note}: If ECB detects an author version of CEDET (as available at @url{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 @code{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! @item 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! @item Optional for Java-coding: ECB works very well with the JDEE package ( @url{http://jdee.sourceforge.net}) but JDEE is not required by ECB. @end enumerate Do not install ECB before you have successfully installed the requirements! @node ECB as XEmacs-package, Standard ECB-Installation, Requirements, Installation @subsection 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 (@pxref{Standard ECB-Installation}). @c @strong{Recommendation}: If you are able to manually install ECB and its @c requirements as described in @ref{Standard ECB-Installation} then go on and @c proceed with that (you will see, it's easy). You will get a much more powerful @c ECB and also CEDET/semantic. @c @c If you are desperate to use the package-management-system of ECB for @c installing ECB, then here is a short guide (for details about the @c package-manager of XEmacs see the related info-manual): @c @c @strong{Caution}: If ECB is already installed and you just want @c upgrading to a newer version then it is recommended to deactivate ECB @c before proceeding with the steps below! @c @c @enumerate @c @item Choose a download-site @c @c This can be done via the menu ``Tools --> Packages --> Add Download @c Site'': Choose one of the listed sites. Or you can customize the @c option @code{package-get-remote} by hand and save it for future @c sessions. @c @c @item Activate the packages list @c @c This can be done either by the menu ``Tools --> Packages --> List and @c Install'' or via the command @code{pui-list-packages}. After that a @c special packages-buffer is displayed where you can interactively @c install or upgrade packages. At the end of this buffer there is a @c short description how to use this buffer. @c @c @item Install ECB and all required packages @c @c Mark the package named ``ecb'' for install. Do this also for the @c required packages ``semantic'', ``eieio'' and ``speedbar''. The @c package ``mail-lib'' is needed for easy submitting of problem-reports @c to the ECB-maintainers and the package ``c-support'' is needed for @c easy using hideshow within the Methods-buffer of ECB@footnote{All @c required packages can simply autom. marked by hitting @kbd{r} in the @c packages buffer. But this installs a lot of packages more (e.g. the @c Newsreader Gnus) which are really not essential for ECB. Therefore it @c is recommended to mark the required packages by hand.}. @c @c After marking all needed packages for installation hit @kbd{x} to @c install them. @c @c If you have already installed ECB and you want just upgrading to the @c latest available version then proceed as described above - same if you @c want to upgrade one of the required packages. @c @c @item Start ECB @c @c Now you can immediately start ECB via the command @code{ecb-activate}; @c there is no need to restart XEmacs! As an alternative you can first @c read the online-help via @code{ecb-show-help}. @c @c @end enumerate @c @c If you do not like the package-manager of XEmacs but you want @c installing ECB ``by hand'' direct from the ECB-website then you have @c to follow the instructions in @ref{Standard ECB-Installation}. @node Standard ECB-Installation, , ECB as XEmacs-package, Installation @subsection Standard installation of ECB for (X)Emacs Follow exatly these steps to install ECB: @enumerate @item Fulfill all requirements ECB needs (@pxref{Requirements}) ECB performs two autom checks: @itemize @minus @item At load-time: It checks if cedet is at least installed so ECB can be loaded. If not it reports an error. @item At start-time: It checks if the correct versions of cedet and semantic are installed and gives you proper feedback. @end itemize 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! @item Download and unpack the ECB archive (probably you have already done this :-) @item Add the new ECB-directory to your @code{load-path} variable. You @strong{MUST} add the ECB-install-directory to the @code{load-path} either by changing the @code{load-path} variable directly in your @file{.emacs} or @file{site-lisp/site-start.el} or by working with a file @file{subdirs.el}@footnote{This works at least for Emacs but XEmacs may have slightly different mechanisms; see the XEmacs documentation}. So for example the needed entry for your @file{.emacs}-file could be: @example (add-to-list 'load-path "/path/to/your/ecb/installation/directory") @end example @strong{ATTENTION}: ECB is NOT properly installed if it's directory is not added to @code{load-path} and for example just loaded by @example (load-file "/path/to/ecb/ecb.el") @end example Do not do this! It will not work! @item Load ECB by adding code to your @file{.emacs}: If you want to load the complete ECB at (X)Emacs-loadtime (Advantage: All ECB-options available after loading ECB. Disadvantage: Increasing loadtime@footnote{Cause of full loading of ECB itself and also the packages semantic, eieio and speedbar regardless if ECB is started.}): @example (require 'ecb) @end example If you want to load the ECB first after starting it by @code{ecb-activate} (Advantage: Fast loading@footnote{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}. Disadvantage: ECB- and semantic-options first available after starting ECB): @example (require 'ecb-autoloads) @end example This loads all available autoloads of ECB, e.g. @code{ecb-activate}, @code{ecb-minor-mode}, @code{ecb-byte-compile} and @code{ecb-show-help}. Regardless which method you prefer: In both cases the used statement must be placed @strong{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.)! @item Restart (X)Emacs. @end enumerate ECB is now ready for use and can be activated by calling @code{M-x ecb-activate} or @code{ecb-minor-mode}. Now you can either starting using ECB or you can do these optional installation steps: @enumerate 6 @item Reading the online help with @code{ecb-show-help} Maybe you are interested to read the online-help of ECB before first start. @item Bytecompiling ECB with @code{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 @file{Makefile} or by using the batch-file @file{make.bat}; just read the comments in that file you choose.) @item Installing the Info-help of ECB The ECB distribution contains a subdirectory @file{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: @itemize @minus @item Use ``install-info'' (recommended): @enumerate @item Copy the files of the subdirectory @file{info-help} into the info-directory of Emacs @item Install the file @file{info-help/ecb.info} with the command ``install-info'' (if available on your system) in the @file{dir}-file. @end enumerate The supplied @file{Makefile} offers a target @code{install-help} which does both of these steps. You have just to call @code{make install-help} with the correct EMACSINFOPATH set (see the comment in @file{Makefile}). Here is an example: @example make EMACSINFOPATH=/path/to/emacs/info install-help @end example @item Manual Installation: Copy the files of the subdirectory @file{info-help} into the info-directory of Emacs and modify the file @file{dir} manually. @end itemize But it doesn't matter if you do not execute this step (8.) because the online help of ECB is always available though, see @code{ecb-show-help} (@pxref{Interactive ECB commands}). @end enumerate @node Setting up Emacs, First steps, Installation, Install and first steps @section How to set up Emacs for file parsing with ECB @strong{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 @end menu @node General hints, Setting up CEDET/semantic, Setting up Emacs, Setting up Emacs @subsection 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@footnote{semantic supports some more ``languages'' like Phython, Makefiles and some more. But these are the most important ones.}. For this Emacs must activate the correct @code{major-mode} for the source-files and Emacs can only do this if the option @code{auto-mode-alist} is setup correctly. The correct major-modes and possible file-extensions@footnote{Especially for C++ and C you can use any extension you want but these are the most common ones!} are: @multitable @columnfractions 0.20 0.50 0.30 @item @ifnotinfo @strong{Language} @end ifnotinfo @ifinfo LANGUAGE @end ifinfo @tab @ifnotinfo @strong{Major-mode} @end ifnotinfo @ifinfo MAJOR-MODE @end ifinfo @tab @ifnotinfo @strong{Extension(s)} @end ifnotinfo @ifinfo EXTENSION(S) @end ifinfo @item Emacs Lisp @tab @code{emacs-lisp-mode} @tab .el @item C @tab @code{c-mode} @tab .h, .c @item C++ @tab @code{c++-mode} @tab .h, .hxx, .hh, .HH, .cxx, .cpp, .cc, .CC @item Java @tab @code{java-mode} or @code{jde-mode} (if you use JDEE) @tab .java @end multitable Example: If you want files with extension ``.cpp'' being c++-parsed by semantic and ECB, your @code{auto-mode-alist} must contain an entry like: @example ("\\.cpp\\'" . c++-mode) @end example After this ECB will correctly parse your ``.cpp''-sources and display all the parsing information in the ECB-methods buffer. @node Setting up CEDET/semantic, Non-semantic files, General hints, Setting up Emacs @subsection 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: @enumerate @item 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. @itemize @item 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: @lisp (semantic-mode 1) @end lisp This should be placed BEFORE the statements which activate ECB. As an alternative you can use the @code{ecb-before-activate-hook} like follows: @lisp (add-hook 'ecb-before-activate-hook (lambda () (semantic-mode 1))) @end lisp This is a smarter way when you need semantic only if ECB is active. @item Users of XEmacs or Emacs < 23.2: You should read carefully the file @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: @ifhtml @uref{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html} @end ifhtml @ifnothtml @url{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html} @end ifnothtml If CEDET is not correctly installed then ECB can not setup semantic for its needs. @end itemize @strong{Minimum setup recommendation}: It is very useful to enable the @code{global-semantic-idle-scheduler-mode} and @code{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 @code{semantic-load-enable-minimum-features} to your startup-file. Please read also the subsection ``Jumping to the definition of external types'' in @ref{ECB Methods-window}. @anchor{Checking your hooks} @item 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 @code{c++-mode} is @code{c++-mode-hook}. Semantic adds automatically during load-time a special ``semantic-setup'' to these major-mode hooks@footnote{Of course only for major-modes supported by semantic!} in form of a ``setup-function''. Example: For c and c++ modes semantic adds @code{semantic-default-c-setup} to @code{c-mode-hook} and @code{c++-mode-hook}. If your own Emacs-setup (e.g. in @file{.emacs} or @file{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 @code{setq} for adding code to a major-mode-hook. @strong{IMPORTANT}: Use @code{add-hook} instead of @code{setq}@footnote{@code{setq} replaces/overwrites the current value of a hook with the new value whereas @code{add-hook} @strong{adds} the new value to the old-value of the hook!}! @end enumerate If your source-files are ``running'' with correct @code{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! @node Non-semantic files, , Setting up CEDET/semantic, Setting up Emacs @subsection 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: @itemize @minus @item @code{speedbar-dynamic-tags-function-list} @item @code{speedbar-tag-split-minimum-length} @item @code{speedbar-tag-regroup-maximum-length} @item @code{speedbar-tag-hierarchy-method} @end itemize 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. @node First steps, , Setting up Emacs, Install and first steps @section 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: @enumerate @item Configure where ECB can find your sources: Call @code{M-x customize-option RET ecb-source-path RET}@footnote{This means first hitting the keys @kbd{M} (Meta- or Alt-key) and @kbd{x} simultaneously, inserting ``customize-option'' in the minibuffer, hitting RETURN, inserting ``ecb-source-path'' in the minibuffer and finally hitting RETURN again}. This lets you customize the option @code{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 @code{M-x kill-buffer} or clicking at the button ``Finish''. @item Take a look at the most important options of ECB Call @code{M-x ecb-customize-most-important RET} and see a list of options which you should at least know that these options exist. @item Read the online-help of ECB: The online-help of ECB is available via @itemize @minus @item calling @code{M-x ecb-show-help}, @item pressing @kbd{C-c . h} or @item using the menu ``ECB''. @end itemize (The section you are currently reading is part of the online-help of ECB) The chapter ``Common use-cases'' is also very interesting! @item Start working with ECB. @end enumerate @node Overview, Manual usage, Install and first steps, Top @chapter Overview @cindex tree-buffer @cindex ECB-windows ECB is a global minor-mode which offers a couple of @dfn{ECB-windows} for browsing your sources comfortable with the mouse and the keyboard. ECB offers some basic ECB-windows to browse your sources: @itemize @minus @item ECB-Directories for browsing directories @item ECB-Sources for browsing source-files @item ECB-Methods for browsing the contents of a source @item ECB-History for a history for open or recently opened files @end itemize See @ref{Basic ECB-windows} for a detailled description what these basic ECB-windows offer. See @ref{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: @itemize @minus @item ECB-Analyse for some intellisense stuff like possible completions or local variables @item ECB-Symboldef for displaying the documentation of current symbol under point @end itemize See @ref{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 @dfn{edit-area} where you can edit your source-files. The edit-area can be divided into several @dfn{edit-windows} - as many as you need (@pxref{The edit-area}). And at the bottom of the ECB-frame a persistent @dfn{compilation-window} (also called @dfn{compile-window}) can be displayed (optional), where all the output of Emacs-compilation (compile, grep etc.) and Emacs temp-buffers (help etc.) is shown (@pxref{Temp- and compile-buffers}). The following ``screenshot'' illustrates the typical layout of the ECB-frame@footnote{This is only one example of the layouts ECB offers, see @ref{Changing the ECB-layout}}: @example @group ------------------------------------------------------------------ | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit-area | | | (can be splitted in several edit-windows) | | Methods | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------------------ | | | Persistent Compilation-window (optional) | | | ------------------------------------------------------------------ @end group @end example @node Manual usage, ECB-windows, Overview, Top @chapter How to use this manual @strong{IMPORTANT}: You should have read the chapter @ref{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. @table @asis @item All ECB-windows of ECB (@pxref{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. @item Activation and Deactivation (@pxref{Activation and Deactivation}) Describes how to activate and deactivate ECB and which different types of activation are possible. @item Usage of ECB (@pxref{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... @item Customizing ECB (@pxref{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. @item Submitting a problem report (@pxref{Submitting problem report}) Instructions what to do if you encounters problems with ECB. @item Upgrading and downloading ECB (@pxref{Upgrading}) Gives an introduction into the automatic option-upgrading-feature of ECB. @item Common use-cases (@pxref{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... @item Entry points for Elisp programmers (@pxref{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. @item Conflicts and bugs of ECB (@pxref{Conflicts and bugs}) Lists all currently known bugs and problems and gives well working work-arounds. @item Frequently asked Questions (@pxref{FAQ}) Take a look... @item Command Index (@pxref{Command Index}) List of all interactive commands of ECB @item Option Index (@pxref{Option Index}) List of all user-customizable options of ECB @item Concept Index (@pxref{Concept Index}) List of all concepts introduced by ECB @end table @node ECB-windows, Activation and Deactivation, Manual usage, Top @chapter 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 @dfn{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 @end menu @node Basic ECB-windows, Add-on ECB-windows, ECB-windows, ECB-windows @section 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 @dfn{tree-buffer}. See @ref{Tree-buffer basics} for more details about the functionality of tree-buffers. See @ref{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 @end menu @node Tree-buffer basics, Tree-buffer styles, Basic ECB-windows, Basic ECB-windows @subsection General introduction into tree-buffers @subsubsection Content and structure of a tree-buffer ECB displays most of its informations (e.g. about directory-structures or file-contents) in so called @dfn{tree-buffers} which means the display of such a tree-buffer is structured in a tree consisting of @dfn{tree-nodes}. Every line in a tree-buffer displays exactly one tree-node. Each node can have any arbitrary number of @dfn{children}-nodes. If a tree-node has no children then it is called a @dfn{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: @example @group [+] 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] @end group @end example @subsubsection Possible actions for a tree-node In most cases an action is triggered when clicking with the mouse onto a tree-node@footnote{Of course using the keyboard is also possible, see @ref{Using the keyboard}.} (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 (@pxref{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 (@pxref{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 @ref{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 @ref{ECB Directories-window}, @ref{ECB Sources-window}, @ref{ECB Methods-window} and @ref{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. @subsubsection 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 @code{ecb-tree-make-parent-node-sticky} which enabales/disables this feature (default is enabled). There is also an option @code{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. @node Tree-buffer styles, ECB Directories-window, Tree-buffer basics, Basic ECB-windows @subsection 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 @end menu @node Style basics, Ascii-based styles, Tree-buffer styles, Tree-buffer styles @subsubsection 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: @itemize @minus @item open (``[-]''): The control-symbol displayed for an opened tree-node which has several subnodes. Clicking onto this control closes the node. @item 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. @item empty (``[x]''): The symbol displayed for an empty node. An empty node is a node which could have subnodes but has currently none. @item leaf (``*''): The symbol displayed for a node which can not have any subnodes so it is a ``leaf'' in the tree. @item guide (`` |''): The symbol used for drawing vertical ``guide-lines'' for opened nodes. See the example below. @item no-guide (`` ''): Sometimes invisible guide-lines are needed to draw the tree. @item end-guide (`` `''): The symbol used for the guide-line of the last subnode of an opened node. @item handle (``-''): The symbol displayed before every subnode. Each handle is connected to a guide-line - either a normal guide or an end-guide. @item no-handle (`` ''): An invisible handle. @end itemize A tree will be build-up with these elements like follows: @example @group [-] 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) @end group @end example @node Ascii-based styles, Tree-buffers with images, Style basics, Tree-buffer styles @subsubsection How to customize the ascii-styles The ECB-option @code{ecb-tree-buffer-style} offers two different styles completely drawn with ascii-controls and -guides. Ascii-style with guide-lines (value @code{ascii-guides})@footnote{For a better look&feel of such a tree-buffer ECB displays only the last subnode of an opened node with a handle!}: @example @group [-] 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 @end group @end example Ascii-style without guide-lines (value @code{ascii-no-guides}) - this is the style used by ECB <= 1.96: @example @group [-] 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 @end group @end example The tree-layout of both ascii-styles can be affected with the options @code{ecb-tree-indent} and @code{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 @code{ecb-tree-guide-line-face} (default is the equal-named face). @node Tree-buffers with images, Images for Methods-buffer, Ascii-based styles, Tree-buffer styles @subsubsection Which images are used for the tree Depending on the value of @code{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 @code{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 @code{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 @code{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 @code{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 @code{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 @code{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 @file{.emacs}-file (or whereever your emacs-setup is located): @lisp (setq tree-buffer-enable-xemacs-image-bug-hack nil) @end lisp 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. @node Images for Methods-buffer, ,Tree-buffers with images, Tree-buffer styles @subsubsection 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 @code{ecb-display-image-icons-for-semantic-tags}. All the special images are located in that directory where the option @code{ecb-tree-image-icons-directories} point to for methods. @node ECB Directories-window, ECB Sources-window, Tree-buffer styles, Basic ECB-windows @subsection ECB Directories-window @cindex Directories The ECB directories interactor is for browsing directories. The direct children of the invisible root-node are called @dfn{source-path} and can be defined with the option @code{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 @ref{ECB Sources-window}) but this can be changed with the option @code{ecb-show-sources-in-directories-buffer}. @subsubsection Usage of the directories ECB-window @itemize @bullet @item Select directories (and - if enabled - source files) in the @dfn{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 @ref{Usage of ECB}. IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while clicking with the primary mouse button (@pxref{Using the mouse}) or RETURN (@pxref{Using the keyboard})) on a directory node in the this buffer then the directory-contents-cache for this directory will be refreshed and actualized. @item Directory names with a ``[+]'' symbol after (or before) them can be expanded/collapsed by clicking on the symbol, pressing the TAB key (@pxref{Using the keyboard}) when the cursor is placed on the package line or clicking a mouse button on the item, see @ref{Using the mouse}. @item 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 @code{ecb-source-path}. @item Pressing F2 will open the ECB customization group (@pxref{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. @end itemize When source-files-nodes are displayed in the directories-buffer (see @code{ecb-show-sources-in-directories-buffer}) then for these nodes all descriptions of section @ref{ECB Sources-window} are valid. @subsubsection Activating/Displaying the directories ECB-window Either use one of the predefined layouts which contain the directories ECB-window (@pxref{Changing the ECB-layout}) (e.g. via @kbd{C-c . l c}) or create a new ecb-layout via the command @code{ecb-create-new-layout} and add a buffer of type ``directories'' into this new layout (@pxref{Creating a new ECB-layout}). @subsubsection Customizing the directories ECB-window See @ref{ecb-directories} for a list of all options currently available for customizing this ECB-windows to your needs. @node ECB Sources-window, ECB Methods-window, ECB Directories-window, Basic ECB-windows @subsection ECB Sources-window @cindex Sources 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 (@pxref{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. @subsubsection Usage of the ECB-Sources-window @itemize @bullet @item Source files can be selected by clicking with the primary mouse button (@pxref{Using the mouse}) or hitting RETURN (@pxref{Using the keyboard}) on the source row in the @dfn{ECB-Sources}-window. The buffer of the selected source-file will be displayed in an edit-window - which one depends on the setting in @code{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 (@pxref{Using the mouse}) or RETURN (@pxref{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 @dfn{ECB Methods}-window (@pxref{ECB Methods-window}. So you can get an overlook over the source without changing the buffer in the edit-window. @item Clicking on the source file with the secondary mouse button or C-RETURN (@pxref{Usage of ECB}) will open the source file in another edit window - which one depends on the setting in @code{ecb-mouse-click-destination}. @item 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 @end itemize @subsubsection Activating/Displaying the ECB-Sources-window Either use one of the predefined layouts which contain the sources ECB-window (@pxref{Changing the ECB-layout}) (e.g. via @kbd{C-c . l c}) or create a new ecb-layout via the command @code{ecb-create-new-layout} and add a buffer of type ``sources'' into this new layout (@pxref{Creating a new ECB-layout}). @subsubsection Customizing the ECB-Sources-window See @ref{ecb-sources} for a list of all options currently available for customizing this ECB-window to your needs. @node ECB Methods-window, ECB History-window, ECB Sources-window, Basic ECB-windows @subsection The ECB Methods-window @cindex Methods The @dfn{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 (@pxref{ECB-window synchronizing}). This and other important informations about usage of the powerful Methods-window of ECB can be found in @ref{The Methods window}. @subsubsection Usage of the methods ECB-window @itemize @bullet @item When a node (e.g. method or variable) is selected with the primary mouse button (@pxref{Using the mouse}) or RETURN (@pxref{Using the keyboard}) the buffer in the edit-window (which one depends on the setting in @code{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 (@pxref{Using the mouse}) or RETURN (@pxref{Using the keyboard})) on a node in this buffer then the edit-buffer will be narrowed to the selected tag (see also option @code{ecb-tag-visit-post-actions}). But this works only for sources parsed by semantic, not by imenu or etags! @item Clicking on a node with the secondary mouse button or C-RETURN (@pxref{Usage of ECB}) will jump to the method in another edit window - which one depends on the setting in @code{ecb-mouse-click-destination}. @item 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. @end itemize @subsubsection Activating/Displaying the methods ECB-window Either use one of the predefined layouts which contain the methods ECB-window (@pxref{Changing the ECB-layout}) (e.g. via @kbd{C-c . l c}) or create a new ecb-layout via the command @code{ecb-create-new-layout} and add a buffer of type ``methods'' into this new layout (@pxref{Creating a new ECB-layout}). @subsubsection Customizing the methods ECB-window See @ref{ecb-methods} for a list of all options currently available for customizing this ECB-window to your needs. @node ECB History-window, , ECB Methods-window, Basic ECB-windows @subsection The ECB History-window @cindex History 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 @code{clone-indirect-buffer} or @code{make-indirect-buffer} for XEmacs). @strong{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! @subsubsection Usage of the ECB-History-window @itemize @bullet @item Buffers in the history can be selected by clicking with the primary mouse button (@pxref{Using the mouse}) or hitting RETURN (@pxref{Using the keyboard}) on the buffername-node in the @dfn{ECB-History}-window. The buffer of the selected buffer-name will be displayed in an edit-window - which one depends on the setting in @code{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 (@pxref{Using the mouse}) or RETURN (@pxref{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 @dfn{ECB Methods}-window (@pxref{ECB Methods-window}. So you can get an overlook over the buffer-contents without changing the buffer in the edit-window. @item Clicking on a buffername-node with the secondary mouse button or C-RETURN (@pxref{Usage of ECB}) will open the buffer in another edit window - which one depends on the setting in @code{ecb-mouse-click-destination}. @item 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. @end itemize @subsubsection Activating/Displaying the ECB-History-window Either use one of the predefined layouts which contain the ECB-History-window (@pxref{Changing the ECB-layout}) (e.g. via @kbd{C-c . l c}) or create a new ecb-layout via the command @code{ecb-create-new-layout} and add a buffer of type ``history'' into this new layout (@pxref{Creating a new ECB-layout}). @subsubsection 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 @code{ecb-kill-buffer-clears-history}. See the documentation of this option for the possible choices. If you decide that ECB should @strong{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 @code{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''). @subsubsection 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 @code{clone-indirect-buffer} for GNU Emacs). Indirect buffers are displayed with the face @code{ecb-history-indirect-buffer-face}, default is an italic outline. There is an option @code{ecb-history-stick-indirect-buffers-to-basebuffer} which allows to customize how ECB displays indirect buffers in the history-window: If this option is @code{nil} then indirect-buffers are treated as non-indirect-buffers and sorted into the history-buffer-sequence according to the setting of @code{ecb-history-sort-method}. Then the history contains something like this: @example @end example 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: @example [-] | | `- @end example Here the buffer with name ``'' has three indirect-buffers which are display as childrens of their base-buffer. @subsubsection 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 @code{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: @example [-] [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 @end example @strong{Please note}: If @code{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. @subsubsection Customizing the ECB-History-window See @ref{ecb-history} for a list of all options currently available for customizing this ECB-windows to your needs. @node Add-on ECB-windows, , Basic ECB-windows, ECB-windows @section 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 @end menu @node Semantic analyser, Symboldefinition, Add-on ECB-windows, Add-on ECB-windows @subsection Displaying the current semantic context via analyser @cindex Analyse @cindex Analyze The CEDET-suite contains the @dfn{semantic analyzer}@footnote{Note that ECB uses analyser (with s) whereas semantic uses analyzer (with z).} 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 @code{semantic-analyze-possible-completions} for more details about completions available via the semantic-analyser). The analyser-ECB-window is of type tree-buffer. See @ref{Tree-buffer basics} for basic informations how to use such a tree-buffer. @subsubsection Usage of the analyser-ECB-window @itemize @bullet @item When a node-name in the ``Context''-bucket is selected with the primary mouse button (@pxref{Using the mouse}) or RETURN (@pxref{Using the keyboard}) the buffer in the edit-window (which one depends on the setting in @code{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. @item Clicking on a node-name in the ``Context''-bucket with the secondary mouse button or C-RETURN (@pxref{Usage of ECB}) will jump to the related entry in another edit window - which one depends on the setting in @code{ecb-mouse-click-destination}. @item 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. @item Right clicking with the mouse (or with the keyboard, see @ref{Using popup-menus}) onto a tree-node opens a popup-menu which allows to display additional (if available) informations to the current node. @end itemize @subsubsection 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 @code{ecb-analyse-buffer-sync} and most notably @code{ecb-analyse-buffer-sync-delay}) and @ref{ECB-window synchronizing}). In contrary to the sync-options of the basic ECB-windows@footnote{see @ref{Basic ECB-windows} and the options @code{ecb-basic-buffer-sync} and @code{ecb-basic-buffer-sync-delay}.} the default synchronisation delay of the ECB-analyse-window is quite high: 2 seconds (see @code{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 @example (e @end example 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: @itemize @item Automatic synchronizing with long delay Set @code{ecb-analyse-buffer-sync-delay} to a value which is suitable for your programing and typing style, default is already to seconds. @item Manually synchronizing on demand @enumerate @item Switch off the automatic synchronizing for the ECB-analyse-window by setting the option @code{ecb-analyse-buffer-sync} to nil. Use always customize for this, never setq! @item Bind the command @code{ecb-analyse-buffer-sync} to a conveniant shortcut @item 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. @end enumerate @end itemize @subsubsection Interactive commands of the analyser-ECB-window ECB offers the following commands for the analyser-ECB-window: @itemize @minus @item @code{ecb-analyse-buffer-sync} @item @code{ecb-goto-window-analyse} @item @code{ecb-maximize-window-analyse} @end itemize See @ref{Interactive ECB commands} for details about these commands. @subsubsection Activating/Displaying the analyser-ECB-window Either use one of the predefined layouts "left-analyse" or ``leftright-analyse'' (e.g. via @kbd{C-c . l c}) or create a new ecb-layout via the command @code{ecb-create-new-layout} and add a buffer of type ``other'' and name ``analyse'' into this new layout (@pxref{Creating a new ECB-layout}). @subsubsection Customizing the analyser ECB-window See @ref{ecb-analyse} for a list of all options currently available for customizing this ECB-window to your needs. @node Symboldefinition, ,Semantic analyser, Add-on ECB-windows @subsection Displaying the definition of the current symbol under point @c TODO @node Activation and Deactivation, Usage of ECB, ECB-windows, Top @chapter Activation and Deactivation @noindent 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 @end menu @strong{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! @node Standard activation, Automatic activation, Activation and Deactivation, Activation and Deactivation @section Standard activation and deactivation Call @kbd{M-x ecb-activate} and @kbd{M-x ecb-deactivate} to activate or deactivate ECB@footnote{Activation is also possible via the menu ``Tools --> Start Code Browser (ECB)''.}. If you want ECB started in a new frame see the option @code{ecb-new-ecb-frame} (default is nil). @code{ecb-activate} always raises and selects the ECB-frame even if ECB is already started. @cindex minor mode Because ECB is a global minor-mode it can also be (de)activated/toggled by @kbd{M-x ecb-minor-mode}. @cindex Activation hook-sequence @anchor{Activation hook-sequence} The following sequence of hooks is evaluated during activation of ECB: @enumerate @item @code{ecb-before-activate-hook} @item @item @code{ecb-activate-before-layout-draw-hook} @item @code{ecb-redraw-layout-before-hook} @item @item @code{ecb-redraw-layout-after-hook} @item @code{ecb-activate-hook} @end enumerate @anchor{Deactivation hook-sequence} @cindex Deactivation hook-sequence The following sequence of hooks is evaluated during deactivation of ECB: @enumerate @item @code{ecb-before-deactivate-hook} @item @item @code{ecb-deactivate-hook} @end enumerate @node Automatic activation, , Standard activation, Activation and Deactivation @section Automatic activation and deactivation @cindex Automatic activation @cindex Automatic deactivation There are two ways for auto. (de)activation ECB after Emacs-start and for different window-configurations. @table @code @item 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. @item 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 @ref{Window-managers and ECB}. @end table @node Usage of ECB, Customizing, Activation and Deactivation, Top @chapter 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 @end menu @node Using the mouse, Using the keyboard, Usage of ECB, Usage of ECB @section Working with the mouse in the ECB-windows @cindex primary button @cindex secondary button @cindex mouse button Normally you get best usage if you use ECB with a mouse. ECB distinguishes between a @dfn{primary} and a @dfn{secondary} mouse-button. With the option @code{ecb-primary-secondary-mouse-buttons} the following combinations of primary and secondary mouse-buttons are possible: @itemize @minus @item primary: mouse-2, secondary: C-mouse-2@footnote{means mouse-2 while CTRL-key is pressed.}. This is the default. @item primary: mouse-1, secondary: C-mouse-1 @item primary: mouse-1, secondary: mouse-2 @end itemize If you change this during ECB is activated you must deactivate and activate ECB again to take effect. @subsection The primary mouse-button A click with the primary button causes the main effect in each ECB-buffer: @itemize @minus @item ECB Directories: Expanding/collapsing nodes and displaying files in the ECB-Sources buffer. @item ECB sources/history: Opening the file in that edit-window specified by the option @code{ecb-mouse-click-destination}. @item ECB Methods: Jumping to the method in that edit-window specified by the option @code{ecb-mouse-click-destination}. @end itemize @subsection The POWER- or SHIFT-click @cindex SHIFT-click @cindex POWER-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): @itemize @minus @item ECB Directory: Refreshing the directory-contents-cache (see @code{ecb-cache-directory-contents}). @item 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. @item ECB Methods: Narrowing to the clicked method/variable/ect... (see @code{ecb-tag-visit-post-actions}). But this works only for sources parsed by semantic, not by imenu or etags! @end itemize 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 @code{ecb-*-show-node-info} (replace ``*'' with directories, sources, methods, history or analyse, e.g. @code{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. @subsection 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 @code{ecb-mouse-click-destination}). @subsection 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 @code{ecb-directories-menu-user-extension}, @code{ecb-sources-menu-user-extension}, @code{ecb-methods-menu-user-extension} and @code{ecb-history-menu-user-extension} you can add statically new commands to the popup-menus. See the docstring of @code{ecb-directories-menu-user-extension} for more details. With the options @code{ecb-directories-menu-user-extension-function}, @code{ecb-sources-menu-user-extension-function}, @code{ecb-methods-menu-user-extension-function} and @code{ecb-history-menu-user-extension-function} you can add new commands to the popup-menus in a dynamic manner. See the docstring of @code{ecb-directories-menu-user-extension-function} for more details. With the options @code{ecb-directories-menu-sorter}, @code{ecb-sources-menu-sorter}, @code{ecb-methods-menu-sorter} and @code{ecb-history-menu-sorter} you can even re-arrange all the entries of the popup-menus. @subsection Horizontal scrolling with the mouse In each tree-buffer of ECB you can easily scroll left and right with the mouse if the option @code{ecb-tree-easy-hor-scroll} is not @code{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 @code{scroll-left} and @code{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 @code{ecb-tree-easy-hor-scroll} is a positive integer-value S: @itemize @bullet @item In all ECB-tree-buffers the keys @kbd{M-mouse-1} and @kbd{M-mouse-3} are bound to scrolling left rsp. right with scroll-step S. @item 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. @item Additionally @kbd{C-M-mouse-1} and @code{C-M-mouse-3} are bound to scrolling left rsp. right with scroll-step @code{window-width} - 2. @end itemize 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. @node Using the keyboard, The edit-area, Using the mouse, Usage of ECB @section Working with the keyboard in the ECB-windows ECB offers the @code{ecb-mode-map} which binds the most important functions of ECB to keys so you can easily use ECB in every window@footnote{Regardless if a tree-window or an edit-window} without a mouse. IMPORTANT: Do not modify @code{ecb-mode-map} directly! The option @code{ecb-key-map} defines all ECB keybindings, including a common prefix-key (This is by default @kbd{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 @code{ecb-key-map} (@pxref{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. @end menu @node Navigation/Selection, Incremental search, Using the keyboard, Using the keyboard @subsection Navigation and Selection in a tree-buffer @cindex RETURN key @cindex TAB key @cindex expanding @cindex collapsing In the ECB-buffers RETURN and TAB are the most important keys: @itemize @bullet @item 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 @ref{Using the mouse}. See also the option @code{ecb-tree-do-not-leave-window-after-select} and the function @code{ecb-toggle-do-not-leave-window-after-select} which is bound to @kbd{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. @item TAB always expands or collapses expandable nodes. @end itemize The RETURN and TAB keys can not be (re)defined with @code{ecb-key-map}! If you set @code{ecb-tree-navigation-by-arrow} to not nil then the arrow keys work in the ECB tree-window in the following smart way: @itemize @bullet @item 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). @item 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). @item 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 @code{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 @code{ecb-tree-buffer-style}) character of a node (@pxref{Tree-buffer styles}). @end itemize @node Incremental search, Personal tree-keybindings, Navigation/Selection, Using the keyboard @subsection Incremental search for a node in current tree-buffer @cindex Incremental search Each display-able key (e.g. all keys normally bound to @code{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: @itemize @bullet @item @kbd{backspace} and @kbd{delete}: Delete the last character from the search-pattern. @item @kbd{home}: Delete the complete search-pattern @item @kbd{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 @kbd{end} jumps to the next node with this common prefix. @end itemize 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 @code{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: @itemize @minus @item any leading spaces @item expand/collapse-buttons: [+] rsp. [-] @item protection-signs (+, -, #) in the method-window if uml-notation is used @item variables types or return-types in front of variable- or method-names. @item const specifier for variables @end itemize 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 @code{case-fold-search}. Tip: The @code{ecb-minor-mode} offers you in the @code{ecb-mode-map} (customizable via @code{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 @kbd{C-c . gm}. @node Personal tree-keybindings, Using popup-menus, Incremental search, Using the keyboard @subsection Adding personal keybindings for the tree-buffers There are five hooks which can be used for adding personal keybindings to the ECB tree-buffers: @itemize @minus @item @code{ecb-common-tree-buffer-after-create-hook} @item @code{ecb-directories-buffer-after-create-hook} @item @code{ecb-sources-buffer-after-create-hook} @item @code{ecb-methods-buffer-after-create-hook} @item @code{ecb-history-buffer-after-create-hook} @end itemize These hooks are called directly after tree-buffer creation so they can be used to add personal local keybindings@footnote{To be more general: They can be used to run any arbitrary lisp code after a tree-buffer creation!} either to all tree-buffers (@code{ecb-common-tree-buffer-after-create-hook}) or just to a certain tree-buffer. Here is a list which keys MUST NOT be rebound: @itemize @bullet @item @kbd{RET} and all combinations with @kbd{Shift} and @kbd{Ctrl}: Used for selecting nodes in all tree-buffers. @item @kbd{TAB}: Used for expanding/collapsing nodes in all tree-buffers. @item @kbd{C-t}: Used for toggling ``do not leave window after selection'' in all tree-buffers, see command @code{ecb-toggle-do-not-leave-window-after-select}. @item All self-inserting characters: Used for easy and fast navigation in all tree-buffers, @xref{Incremental search}. @item @kbd{F2}, @kbd{F3}, @kbd{F4}: Used for customizing ECB, adding source-path in the directories buffer. @end itemize The following example binds @kbd{C-a} to some useful code in ALL tree-buffers and @kbd{C-d} to even more useful code ONLY in the directories buffer: @example @group (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!"))))) @end group @end example @node Using popup-menus, ,Personal tree-keybindings, Using the keyboard @subsection Using the popup-menu of a tree-buffer from keyboard. @cindex tmm A popup-menu of a tree-buffer can be activated from keyboard with the command @code{tree-buffer-show-menu-keyboard} which is bound to @kbd{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 (@kbd{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. @node The edit-area, Temp- and compile-buffers, Using the keyboard, Usage of ECB @section Working with the edit-window(s) of the edit-area @cindex edit-window 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. @cindex Adviced functions ECB advices the following user-commands so they work best with ECB: @itemize @minus @item @code{balance-windows} @item @code{delete-other-windows} @item @code{delete-window} @item @code{delete-windows-on} @item @code{display-buffer} @item @code{shrink-window-if-larger-than-buffer} @item @code{split-window} @item @code{split-window-horizontally} @item @code{split-window-vertically} @item @code{switch-to-buffer} @item @code{switch-to-buffer-other-window} @item @code{other-window} @item @code{other-window-for-scrolling} @end itemize The behavior of the adviced functions is (slightly simplified): @itemize @bullet @item 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. @item If there is a persistent compile-window (@pxref{Temp- and compile-buffers}) then all compilation-buffers in the sense of @code{ecb-compilation-buffer-p} will be displayed in the compile-window. @item If called in another frame than the ECB-frame these functions behave exactly like the not adviced original versions! @end itemize @strong{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 @code{ecb-layout-always-operate-in-edit-window}! @subsection 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 @code{describe-function} or @kbd{C-h f}. @deffn Command other-window ARG &optional ALL-FRAMES Around-advice @code{ecb}: The ECB-version of @code{other-window}. Works exactly like the original function with the following ECB-adjustment: The behavior depends on @code{ecb-other-window-behavior}. @end deffn @deffn Command delete-window &optional WINDOW Around-advice @code{ecb}: The ECB-version of @code{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 @code{ecb-toggle-compile-window}). If called in an ecb-window of the current ECB-layout there are two alternatives: @itemize @item If the function is contained in @code{ecb-layout-always-operate-in-edit-window} the right edit-window is selected (depends on the value of the option @code{ecb-mouse-click-destination}) and does then itīs job. @item Otherwise the behavior depends on the value of the option @code{ecb-advice-window-functions-signal-error}. @end itemize 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 @code{ecb-advice-window-functions-signal-error}. @end deffn @deffn Command delete-other-windows &optional WINDOW Around-advice @code{ecb}: The ECB-version of @code{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! @itemize @item If called in an unsplitted edit-window then either the compile-window will be hidden (if there is one) otherwise nothing is done. @item 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. @item If called in the compile window there are two alternatives: @itemize @minus @item If the function is contained in @code{ecb-layout-always-operate-in-edit-window} the right edit-window is selected (depends on the value of the option @code{ecb-mouse-click-destination}) and then it does itīs job. @item Otherwise the behavior depends on the value of the option @code{ecb-advice-window-functions-signal-error}. @end itemize @end itemize 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 @code{ecb-advice-window-functions-signal-error}. @end deffn @deffn Command delete-windows-on BUFFER &optional FRAME Around-advice @code{ecb}: The ECB-version of @code{delete-windows-on}. Works exactly like the original function with the following ECB-adjustment: An error is reported if @var{BUFFER} is an ECB-tree-buffer. These windows are not allowed to be deleted. @end deffn @deffn Command split-window &optional WINDOW SIZE HORFLAG Around-advice @code{ecb}: The ECB-version of @code{split-window}. Works exactly like the original function with the following ECB-adjustment: If called for a not-edit-window in the @code{ecb-frame} it stops with an error if @code{split-window} is not contained in the option @code{ecb-layout-always-operate-in-edit-window}! Besides this (e.g. called for a window in another frame than the @code{ecb-frame}) it behaves like the original version. @end deffn @deffn Command split-window-horizontally Around-advice @code{ecb}: The ECB-version of @code{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 @code{split-window-horizontally} is not contained in the option @code{ecb-layout-always-operate-in-edit-window}! @end deffn @deffn Command split-window-vertically Around-advice @code{ecb}: The ECB-version of @code{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 @code{split-window-vertically} is not contained in the option @code{ecb-layout-always-operate-in-edit-window}! @end deffn @deffn Command display-buffer BUFFER &optional NOT-THIS-WINDOW FRAME Around-advice @code{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 @code{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 (@code{ecb-compile-window-height} is nil) then it splits the edit-window if unsplitted and displays BUFFER in another edit-window but only if @code{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 @code{ecb-compilation-buffer-p} will be displayed in one of the edit-area and @code{display-buffer} behaves as if the edit-windows would be the only windows in the frame. If BUFFER is contained in @code{special-display-buffer-names} or matches @code{special-display-regexps} then @code{special-display-function} will be called (if not nil). But this behavior depends on the value of the option @code{ecb-ignore-special-display}. The values of @code{same-window-buffer-names} and @code{same-window-regexps} are supported as well. See the option @code{ecb-ignore-display-buffer-function}! If called for other frames it works like the original version. @end deffn @deffn Command switch-to-buffer BUFFER &optional NORECORD Around-advice @code{ecb}: The ECB-version of @code{switch-to-buffer}. Works exactly like the original but with the following enhancements for ECB: ``compilation-buffers'' in the sense of @code{ecb-compilation-buffer-p} will be displayed always in the compile-window of ECB (if @code{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 @code{ecb-compilation-buffer-names}, @code{ecb-compilation-major-modes} or @code{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 @code{switch-to-buffer} is contained in the option @code{ecb-layout-always-operate-in-edit-window}. Otherwise an error is reported. @end deffn @deffn Command switch-to-buffer-other-window BUFFER &optional FRAME Around-advice @code{ecb}: The ECB-version of @code{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 @code{ecb-mouse-click-destination}) and then goes on as if called from this edit-window. If a compile-window is used (i.e. @code{ecb-compile-window-height} is not nil) then ``compilation-buffers'' in the sense of @code{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). @end deffn @deffn Function other-window-for-scrolling Around-advice @code{ecb}: This function determines the window which is scrolled if any of the ``other-window-scrolling-functions'' is called (e.g. @code{scroll-other-window}): If the option @code{ecb-scroll-other-window-scrolls-compile-window} is not nil (maybe set by @code{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 @code{ecb-other-window-behavior}. @end deffn @deffn Command balance-windows Around-advice @code{ecb}: When called in the @code{ecb-frame} then only the edit-windows are balanced. @end deffn @node Temp- and compile-buffers, The other window, The edit-area, Usage of ECB @section Temp- and compile-buffers display in ECB @cindex temporary buffers @cindex help buffers @cindex compilation buffers @cindex grep buffers If you call any help in Emacs, e.g. by calling @code{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. @subsection Standard Emacs behavior @subsubsection 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 @code{temp-buffer-max-height} and @code{temp-buffer-resize-mode} (for GNU Emacs) and @code{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 @code{compile} or @code{grep}) and the variable @code{compilation-window-height}@footnote{It goes without saying that is is also true for @code{grep-window-height} and all other ``compile''-modes.}. @subsubsection 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 @code{split-width-threshold} and @code{split-height-threshold}. @strong{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 @code{split-width-threshold} and @code{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'': @subsection Using a persistent compile window With the option @code{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 @code{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 @code{ecb-compilation-buffer-names}, @code{ecb-compilation-major-modes} and @code{ecb-compilation-predicates} you can define which buffers should be displayed in the compile-window of ECB (for example if you call @code{switch-to-buffer} or @code{display-buffer} or if you run @code{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 @code{ecb-toggle-compile-window} (bound to @kbd{C-c . \}) you can toggle the visibility of the compile-window (@pxref{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 @ref{ecb-compilation}): @itemize @bullet @item With the option @code{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 @code{ecb-toggle-compile-window-height}. @item With the option @code{ecb-enlarged-compilation-window-max-height} you specify how @code{ecb-toggle-compile-window-height} should enlarge the compile-window. @item With the command @code{ecb-cycle-through-compilation-buffers} (@pxref{Interactive ECB commands}) you can cycle through all current open compilation-buffers (in the sense of @code{ecb-compilation-buffer-p}) very fast. @end itemize 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 @code{delete-other-windows} (bound to @kbd{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. @anchor{Problems with the compile window} @subsection What to do if there are problems with the compile-window Normally displaying temp- and compilation-buffers (or more general: displaying buffer for which @code{ecb-compilation-buffer-p} is not nil) should work reliable. But if there are problems which you can not handle with the options @code{ecb-compilation-buffer-names}, @code{ecb-compilation-major-modes} or @code{ecb-compilation-predicates} then please go on like follows: @enumerate @item Set the option @code{ecb-layout-debug-mode} to not nil. @item 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! @item Now send immediately a bug report with @code{ecb-submit-problem-report}. @item Set @code{ecb-layout-debug-mode} back to nil if you do not want further debugging output in the *Messages* buffer" @end enumerate @anchor{Using special-display with ECB} @cindex special-display @subsection Handling special-display-buffers Emacs offers three options for a special-display-handling of certain buffers: @code{special-display-function}, @code{special-display-buffer-names} and @code{special-display-regexps} (see the Emacs manual for a description of these options). ECB offers an option @code{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. @code{ecb-compile-window-height} is not nil). But with @code{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 @code{display-buffer} or @code{pop-to-buffer} takes always account for the values of these options - like the original behavior of Emacs. @node The other window, The Methods window, Temp- and compile-buffers, Usage of ECB @section How the ``other window'' is determined by ECB @cindex other window Normally all windows in an Emacs-frame are arranged in a cyclic order and window-selecting-commands like @code{other-window} or window-scrolling-commands like @code{scroll-other-window} choose simply the next@footnote{@code{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} window after the current window as ``other window''. @subsection ``Other window''-basics in ECB With a typical window-layout of ECB such a cyclic order of @strong{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 @code{other-window} or @code{scroll-other-window}. Therefore ECB divides the whole set of windows of the ECB-frame in several subsets: @itemize @bullet @item The edit-windows of the edit-area @item The special tree-windows for browsing-tasks @item The compile-window at the bottom (if there is one) @item The minibuffer-window of the ECB-frame (if active) @end itemize 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 @code{walk-windows} would visit the windows when the windows of a subset would be the only windows of a frame@footnote{@code{other-window} uses the same window-ordering as @code{walk-windows}}. @subsection Builtin ``other window'' behaviors of ECB ECB now offers to specify the behavior of commands like @code{other-window} or @code{scroll-other-window} within the ECB-frame. This can be done with the option @code{ecb-other-window-behavior}. This option offers several builtin behaviors: @itemize @bullet @item 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 @code{other-window} rsp. the original @code{other-window-for-scrolling}. @item 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. @item 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. @item Behave as smart and intuitive as possible This is the default behavior of ECB. ECB tries to choose the @code{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 @code{other-window}-call the @var{ARG} of @code{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 @code{other-window}-call the @var{ARG} of @code{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 @code{other-window} has been called with a prefix-argument unequal 1. @end itemize Regardless of the different behaviors above ECB handles the situation of an active minibuffer during a call to @code{other-window} or @code{scroll-other-window} like follows: If the minibuffer-window is selected then ECB always chooses the window @code{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 @code{other-window} called without prefix-arg or with prefix-arg equal 1). Otherwise the window ARG steps away is choosen (in case of @code{other-window}). If there is an active minibuffer but the minibuffer-window is not selected then @code{other-window} and @code{scroll-other-window} behave like the original version. @subsection 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 @code{ecb-other-window-behavior} too because this option can also have a function-symbol as value: Such a function gets seven arguments: @enumerate @item A canonical list of all currently visible windows of the @code{ecb-frame} @item A canonical list of all currently visible edit-windows @item A canonical list of all currently visible ecb-windows @item The window-object of the compile-window if there is any. @item The minibuffer-window of the ECB-frame if there is an active minibuffer. @item The result of the function @code{ecb-where-is-point} - see the documentation of this function for details. @item 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 @code{other-window}. @end enumerate The function has to return a window-object which is then used as ``other window'' for the command @code{other-window} or for scrolling another window (e.g. with @code{scroll-other-window}). Such a function has to handle properly all situation for itself. Here is an example for such a function: @example @group (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)))))) @end group @end example This example implements the builtin smart behavior described above. @node The Methods window, Filtering the tree-buffers, The other window, Usage of ECB @section 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: @cindex semantic-sources @anchor{Definition of semantic- and non-semantic-sources} @itemize @minus @item @dfn{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. @cindex non-semantic-sources @item @dfn{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. @end itemize 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 @end menu @node Visiting tags, Expanding, The Methods window, The Methods window @subsection Possible actions after visiting a tag You visit a tag by clicking with either the primary oder secondary mouse-button (or by hitting @kbd{RET} or @kbd{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 @code{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 @code{ecb-tag-visit-post-actions}. The following actions are currently predefined: @itemize @minus @item @code{ecb-tag-visit-highlight-tag-header} @item @code{ecb-tag-visit-smart-tag-start} @item @code{ecb-tag-visit-recenter} @item @code{ecb-tag-visit-recenter-top} @item @code{ecb-tag-visit-goto-doc-start} @item @code{ecb-tag-visit-narrow-tag} @end itemize See the documentation of these function for details what they do. Per default ECB performs the actions @code{ecb-tag-visit-smart-tag-start} and @code{ecb-tag-visit-highlight-tag-header} for all major-modes. @node Expanding, Customizing the display, Visiting tags, The Methods window @subsection Explicit and automatic expanding of the ECB-methods-buffer @subsubsection Explicit expanding all nodes to a certain expansion level With the command @code{ecb-expand-methods-nodes} (bound to @kbd{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 @code{ecb-methods-nodes-expand-spec} and @code{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. @subsubsection 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: @itemize @minus @item 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(!). @item 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. @item 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! @end itemize Expanding the current node with the popup-menu ignores the settings in the options @code{ecb-methods-nodes-expand-spec} and @code{ecb-methods-nodes-collapse-spec}! @subsubsection Automatic expansion ot tags after buffer-parsing With the option @code{ecb-show-tags} you tell ECB how to display tags of a certain tag-class (@pxref{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 @code{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 @code{type} is a class, an interface, an enumeration, a typedef etc. With the option @code{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. @subsubsection Automatic expanding the ECB-methods-buffer for current tag If the option @code{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 @code{ecb-auto-expand-tag-tree} or even easier with the command @code{ecb-toggle-auto-expand-tag-tree}. There is another option @code{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 @code{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. @node Customizing the display, Updating Methods-window, Expanding, The Methods window @subsection Customizing the display of the Methods-buffer @cindex semantic tag @cindex tag 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 @dfn{tags} to ECB which displays them in a browse-able form in its Method-buffer. See @ref{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. @table @code @item ecb-show-tags With the option @code{ecb-show-tags} you specify how ECB should display the tags returned by the semantic parser. Semantic divides its tags in several so called @dfn{tag classes}. A tag-class is always a symbol and can be for example @code{type} (tags which represent a class@footnote{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.}, a interface, an enumeration etc.), @code{function} (tags which represent function or methods), @code{variable} (variables and attributes), @code{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 @code{ecb-show-tags}. With the option @code{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 @code{X} should be displayed in an expanded bucket and all tags of a tag-class @code{Y} should be displayed in a collapsed bucket and all tags of a tag-class @code{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 @code{ecb-show-tags}. For every tag-class you can tell ECB how the tags should be sorted. @item ecb-font-lock-tags @itemx ecb-type-tag-display How to fontify the tags in the Method-buffer @item 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. @end table These are the most important options for this topic but it is recommended to have a look into the customize-group @code{ecb-methods} (@pxref{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 @node Updating Methods-window, Updating for ind. buffers, Customizing the display, The Methods window @subsection Updating the Methods-window with contents of current source-buffer First a preliminary remark: Do not confuse this chapter with that synchronizing described in @ref{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! @subsubsection The short version In almost all cases there is @strong{NO} need to manually rebuild the method-buffer, because it is always done automatically if necessary; the mechanism depends on the sources: @itemize @minus @item semantic-sources: The command @code{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. @item non-semantic-sources (imenu supported): You can switch on autom. rescanning/reparsing with the option @code{imenu-auto-rescan}. But nevertheless you have to manually rebuild the Method-buffer (with the autom. updated imenu-tags) via the command @code{ecb-rebuild-methods-buffer} (bound to @kbd{C-c . r}). @item 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! @end itemize @subsubsection 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 @code{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: @itemize @item editing a function- or method-body @item changing the name of a variable or function/method @item modifying the return-type of a function/method @item and some other... @end itemize 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. @strong{Summary}: It's strongly recommended to enable @code{semantic-idle-scheduler-mode} or @code{global-semantic-idle-scheduler-mode} (@pxref{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 @code{ecb-force-reparse-when-semantic-idle-scheduler-off}): @itemize @bullet @item 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 @code{ecb-rebuild-methods-buffer} (bound to @key{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 @code{ecb-rebuild-methods-buffer}! @item 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. @end itemize The term ``forcing a reparse by semantic'' is a simplification: ECB uses then the function @code{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 @code{semantic-idle-scheduler-mode} or @code{global-semantic-idle-scheduler-mode}! See @ref{Setting up CEDET/semantic}. This will give you in all cases the behavior you would expect of an IDE like ECB/semantic. @node Updating for ind. buffers, Jumping to external tags, Updating Methods-window, The Methods window @subsection Updating Methods for indirect buffers ECB works out of the box with indirect buffers, especially with indirect buffer clones created with the command @code{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: @strong{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 @code{ecb-rebuild-methods-buffer} with prefix arg or hit @key{C-u C-c . r} (key this command is bound to). Lets make an example: @enumerate @item 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. @item 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 (@pxref{Setting up CEDET/semantic}) then this buffer will be reparsed automatically and ECBs methods-window will be updated in turn too. @item 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. @item To update the methods-window for test.java to the new contents you have to call @code{ecb-rebuild-methods-buffer} with prefix argument (ie. clear-cache is true) or hitting @key{C-u C-c . r}. Note: Calling this command without prefix argument is not enough! @end enumerate @node Jumping to external tags, , Updating for ind. buffers, The Methods window @subsection 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: @enumerate @item 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. @item ``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 @file{*.cc} file whereas the class-definition is defined in the associated header-file. @end enumerate 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 @file{ParentClass.h}: @example @group class ParentClass @{ protected: int p; @}; @end group @end example Let's say this class is defined in a file @file{ClassWithExternals.h} @example @group #include "ParentClass.h" class ClassWithExternals : public ParentClass @{ private: int i; public: ClassWithExternals(); ~ClassWithExternals(); @}; @end group @end example Both the constructor and the destructor of the class ``ClassWithExternals'' are implemented in a file @file{ClassWithExternals.cc}: @example @group #include "test.h" ClassWithExternals::ClassWithExternals(int i, boolean b, char c) @{ return; @} void ClassWithExternals::~ClassWithExternals() @{ return; @} @end group @end example ECB displays the contents of @file{ClassWithExternals.cc} in its methods-buffer like follows: @example @group [-] [Includes] `- test.h [-] ClassWithExternals | +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals `- +~ClassWithExternals ():void @end group @end example 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 @file{ClassWithExternals.h} are then displayed like follows: @example @group [-] [Includes] `- ParentClass.h [-] ClassWithExternals:class | [-] [Parents] | `- ParentClass | [-] [Variables] | `- -i:int | +ClassWithExternals ():ClassWithExternals | +~ClassWithExternals ():void `- [+] [Misc] @end group @end example 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: @itemize @item 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 @ref{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... @strong{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: @ifhtml @uref{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html} @end ifhtml @ifnothtml @url{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html} @end ifnothtml @item Customize the related options of ECB: There is exactly one option you have to take into account: @code{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: @itemize @minus @item @code{ecb-search-type-tag-by-semantic-analyzer}: The most powerfil one, based on the semantic-analyzer @item @code{ecb-search-type-tag-by-semanticdb}: A backup for the first one @item @code{ecb-jde-show-class-source}: For major-mode @code{jde-mode} when coding in java, uses java-mechanisms - maybe for java the best choice. @end itemize See the documentation of the option and also of these function for details how they work and how to write own finding-functions. @end itemize @node Filtering the tree-buffers, The ECB-layout, The Methods window, Usage of ECB @section Applying filters to the special ECB-tree-buffers @cindex Filter 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 @end menu @node Filtering Directories, Filtering Sources, Filtering the tree-buffers, Filtering the tree-buffers @subsection Applying filters to the Directories-buffer With the option @code{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 @code{ecb-sources-exclude-cvsignore} allows to exclude source-files from the sources-tree-buffer if their name is listed in a so called @file{.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 @file{.cvsignore}-file of this directory are not displayed in the sources-tree-buffer. @node Filtering Sources, Filtering History, Filtering Directories, Filtering the tree-buffers @subsection Applying filters to the Sources-buffer @subsubsection Interactive Sources-filters The command @code{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. @subsubsection Default Sources-filters The option @code{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 @code{ecb-sources-exclude-cvsignore} (@pxref{Filtering Directories}). @node Filtering History, Filtering Methods, Filtering Sources, Filtering the tree-buffers @subsection Applying filters to the History-buffer @subsubsection Interactive History-filters The command @code{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. @subsubsection Default History-filters The option @code{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 @file{TAGS} or @file{semantic.cache} which store meta-informations used by Emacs and its tools (etags, semantic etc.). These files can be excluded via @code{ecb-history-exclude-file-regexps}. @node Filtering Methods, , Filtering History, Filtering the tree-buffers @subsection Applying filters to the Methods-buffer The commands @code{ecb-methods-filter}, @code{ecb-methods-filter-regexp}, @code{ecb-methods-filter-protection}, @code{ecb-methods-filter-tagclass}, @code{ecb-methods-filter-function}, @code{ecb-methods-filter-delete-last}, @code{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. @subsubsection Possible filter-criterias @itemize @bullet @item 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. @item Filter by regexp: Insert the filter as regular expression. @item Filter by tag-class: You can filter by tag-classes. The popup-menu contains mode-dependend tag-filter entries and the command @code{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 @code{semantic-symbol->name-assoc-list} is used to get the right tag-classes. @item 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. @item No special filter: This means to display all tags specified with the option @code{ecb-show-tokens}. If currently some of the above filters are applied they will be all removed. @item Delete the last added: This removes only the topmost filter-layer, means that filter added last. @end itemize Be aware that the tag-list specified by the option @code{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 @ref{Non-semantic sources} for further details about working with source-files not supported by the semantic-parser. @subsubsection Inverse Filters But if @code{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 @strong{NOT} match the choosen filter will be displayed in the Methods-buffer! @subsubsection 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 @code{ecb-methods-filter-replace-existing}. @subsubsection 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. @subsubsection Default filters for certain files. The new option @code{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 @code{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. @file{NEWS}) only the level-1-headings by defining a filter regexp ``^\* .*''. @node The ECB-layout, Hiding the ECB windows, Filtering the tree-buffers, Usage of ECB @section Changing, customizing, redrawing and creating layouts @cindex layout @cindex ECB-layout The term @dfn{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 @end menu @node Changing the ECB-layout, Redrawing the ECB-layout, The ECB-layout, The ECB-layout @subsection 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@footnote{The command @code{ecb-show-layout-help'} shows the outline-picture for all built-in layouts.}. In addition to these predefined layouts you can either interactively create new layouts ``by example'' (@pxref{Creating a new ECB-layout}) or program new layouts with the macro @code{ecb-layout-define} (@pxref{The layout-engine}). The former method is the recommended one! There are two ways to interactively change the layout: @itemize @bullet @item Changing permanently: Customize the option @code{ecb-layout-name} and store it for future Emacs sessions. @item Switching between several layouts at runtime: If you want to switch fast between a certain sequence of layouts see the option @code{ecb-toggle-layout-sequence} and the command @code{ecb-toggle-layout} (@pxref{Simulating speedbar}). For just selecting another layout during current Emacs-session use the command @code{ecb-change-layout}. @end itemize With the option @code{ecb-show-sources-in-directories-buffer} you can define if sources are displayed in the directory-window of a layout (@pxref{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 @code{ecb-compile-window-height} (@pxref{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 @code{ecb-tree-buffer-style} and the location of the collapse- and expand-symbols and the indentation of sub-nodes in a tree. See @code{ecb-tree-indent} and @code{ecb-tree-expand-symbol-before}. More details about the different tree-buffer-styles are described in @ref{Tree-buffer styles}. Here are all currently available layouts (for creating own new layouts see @ref{Creating a new ECB-layout}); just customize the option @code{ecb-layout-name} to the related name: @table @asis @item Layout ``left1'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | | Sour | Hist | Edit | | | | | | | | | |--------------| | | | | | Methods | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left2'' @example @group ------------------------------------------------------- | | | | | | | | | | Directories | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | Sources | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left3'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | Sources | Edit | | | | | | | |--------------| | | | | | Methods | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left4'' @example @group ------------------------------------------------------- | | | | | | | | | | Directories | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | | | | Sour | Hist | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left5'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | Sources | Edit | | | | | | | |--------------| | | | | | History | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``right1'' @example @group ------------------------------------------------------- | | | | | Directories | | | | | | | | |--------------| | | | | | | | Edit | Sources | | | | | | | | |--------------| | | | | | Methods | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left6'' @example @group ------------------------------------------------------- | Sources | | |--------------| | | | | | | | | | | | Methods | Edit | | | | | | | | | | |--------------| | | History | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``top1'' @example @group ------------------------------------------------------- | | | | | | | | | Directories | Sources | Methods | | | | | | | | | |-----------------------------------------------------| | | | | | | | | | Edit | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left7'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |--------------| Edit | | | | | History | | | | | |--------------| | | | | | Methods | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left8'' @example @group ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | | | | |--------------| | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``top2'' @example @group ------------------------------------------------------- | | | | | Methods | | | | | |-----------------------------------------------------| | | | | | | | | | Edit | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left9'' @example @group ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left10'' @example @group ------------------------------------------------------- | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | | Sou | Hist | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left11'' @example @group ------------------------------------------------------- | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left12'' @example @group ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | History | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left13'' @example @group ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | Directories | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left14'' @example @group ------------------------------------------------------- | | | | | | | | | | Directories | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left15'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | Methods | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``leftright1'' @example @group ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | |-------------| Edit | | | | | | | Sources | | | | | | | |-------------| | | | | | | | History | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``leftright2'' @example @group ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | | | Edit | | |-------------| |-------------| | | | | | Sources | | History | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``leftright3'' @example @group ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | | | Edit | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left-dir-plus-speedbar'' @example @group ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |-------------| | | | | | | | | | | | Speedbar | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left-analyse'' @example @group ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | |--------------| | | | | | Analyse | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @item Layout ``left-symboldef'' @example @group ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | |--------------| | | | | | Symbol-defs | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- @end group @end example @end table @node Redrawing the ECB-layout, Changing window sizes, Changing the ECB-layout, The ECB-layout @subsection Redrawing the ECB-layout @cindex Redraw If you have unintentionally destroyed the ECB-layout, you can always restore the layout with calling @code{ecb-redraw-layout}. This is even true, if you get messages like ``wrong-type-argument window-live-p #''. If the variable @code{ecb-redraw-layout-quickly} is not nil then the redraw is done by the @code{ecb-redraw-layout-quickly} function, otherwise by @code{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 @code{ecb-redraw-layout}! See also the hooks @code{ecb-redraw-layout-after-hook} and @code{ecb-redraw-layout-before-hook}! @node Changing window sizes, Fixing window sizes, Redrawing the ECB-layout, The ECB-layout @subsection Changing the sizes of the special ECB-windows The standard width and height of the special ECB-windows is defined with the options @code{ecb-windows-width} and @code{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 @code{ecb-layout-window-sizes} and the commands @code{ecb-store-window-sizes}, @code{ecb-restore-window-sizes} and @code{ecb-restore-default-window-sizes}. Here is an example how to resize and store the sizes of the ECB-windows of layout ``left1'': @enumerate @item Switch to layout ``left1'' via @code{ecb-change-layout} (@kbd{C-c . lc}) @item Resize the ECB-windows by dragging the window-borders with the mouse @item Call @code{ecb-store-window-sizes} @end enumerate After this layout ``left1'' will be always drawn with the new sizes until you call @code{ecb-restore-default-window-sizes} during layout ``left1'' is active. @strong{Please note}: @code{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. @node Fixing window sizes, Creating a new ECB-layout, Changing window sizes, The ECB-layout @subsection 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 @code{window-size-fixed}@footnote{Currently XEmacs does not support this feature therefore @code{ecb-fix-window-size} has no effect with XEmacs}. ECB offers an option @code{ecb-fix-window-size} for fixing the sizes of the special ECB-windows/buffers even after frame-resizing. The fix type (valid values are @code{nil}, @code{t}, @code{width} and @code{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 @code{auto} which choose autom. the senseful fix-type depending on the current layout-type: For top-layouts the fix-type @code{height} and for all other layout-types the fix-type @code{width}. Probably the most senseful value is @code{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 @code{width}, @code{height} and @code{t}. Therefore this option takes no effect (means all ecb-windows have always unfixed sizes) with Emacs < 22 if @code{ecb-compile-window-height} is not @code{nil}. @node Creating a new ECB-layout, , Fixing window sizes, The ECB-layout @subsection Interactively creating new layouts @cindex New layouts @cindex Creating new layouts If you want to create your own ECB-layout then you can do this very easy ``by example'' with the command @code{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. @code{ecb-create-new-layout} and this couple of keys are your guide during the layout-creation-process@footnote{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!}. After calling @code{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: @itemize @minus @item left: All ECB-tree-windows are located on the left side @item right: All ECB-tree-windows are located on the right side @item top: All ECB-tree-windows are located on the top side @item left-right: All ECB-tree-windows are located on the left and right side @end itemize Depending on the type you choose the window is splitted by the values of the options @code{ecb-windows-width} (types ``left'', ``right'' and ``left-right'') or @code{ecb-windows-height} (type ``top''). Afterwards you will see a frame like follows (here the layout-type is ``left-right''): @example @group ----------------------------------------------------------------- | | | | | | ECB-layout creation mode | | | | ======================== | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ----------------------------------------------------------------- | | ,--- `---| Splitted by the value of @code{ecb-windows-width}. `--- @end group @end example 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 (@kbd{C-s}). The left one contains the point. You must give every ECB-tree-window you create a type (@kbd{C-t}) which can be either @itemize @bullet @item One of the built-in types This can be either ``directories'', ``sources'', ``methods'', ``history'' or ``speedbar''. @item Any user-defined type: In this case you insert ``other'' after hitting @kbd{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 @code{ecb-set-X-buffer} whereas X is the name of the user-defined type you have specified during layout-creation. This function @code{ecb-set-X-buffer} must be defined with the macro @code{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 @code{ecb-set-example-buffer} which could be defined like follows: @example (defecb-window-dedicator-to-ecb-buffer ecb-set-example-buffer " *ECB example-buf*" (switch-to-buffer (get-buffer-create " *ECB example-buf*"))) @end example 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 @code{ecb-set-default-ecb-buffer} instead. @end itemize If you are satisfied with your new layout just hit @kbd{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 @code{ecb-create-layout-file}. The new layout is now available via the option @code{ecb-layout-name}. There is no need for you to load the file @code{ecb-create-layout-file} manually into your Emacs because it's automatically loaded by ECB! @strong{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 @ref{The layout-engine}. With the command @code{ecb-delete-new-layout} you can delete previously created layouts (TAB-completion is offered for all names of user created layouts). @node Hiding the ECB windows, Maximizing the ECB windows, The ECB-layout, Usage of ECB @section Hiding/Showing the ECB windows @cindex Hide windows @cindex Show windows With @code{ecb-toggle-ecb-windows}, @code{ecb-hide-ecb-windows} and @code{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 @code{delete-other-windows} and/or @code{delete-window}. This is most useful if you use a layout like ``top2'' (@pxref{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: @enumerate @item @code{ecb-show-ecb-windows-before-hook} @item @code{ecb-redraw-layout-before-hook} @item