Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
15977 lines (12957 sloc) 624 KB
\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 <klaus.berndl@sdm.de>
@c Maintainer: Klaus Berndl <klaus.berndl@sdm.de>
@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
* Makefile customization:: Customizing build using Makefile.conf
How to set up Emacs for file parsing with ECB
* General hints:: General hints for a correct setup
* Setting up CEDET/semantic:: How to setup semantic correctly
* Non-semantic files:: Setup for file types not supported by semantic
All ECB-windows of ECB
* Basic ECB-windows:: Description of the basic ECB-windows
* Add-on ECB-windows:: Description of additional ECB-windows
The basic ECB-windows of ECB
* Tree-buffer basics:: General introduction into tree-buffers
* Tree-buffer styles:: Displaying the trees with different styles
* ECB Directories-window:: Contents of the ECB Directories-window
* ECB Sources-window:: Contents of the ECB Sources-window
* ECB Methods-window:: Contents of the ECB Methods-window
* ECB History-window:: Contents of the ECB History-window
Displaying the trees with different styles
* Style basics:: Basic knowledge about the styles
* Ascii-based styles:: How to customize the ascii-styles
* Tree-buffers with images:: Which images are used for the tree
* Images for Methods-buffer:: Images for the tags in the Methods-buffer
Add-on ECB-windows of ECB
* Semantic analyser:: Analyses and displays semantic context
* Symboldefinition:: Displays definition of current symbol
Activation and Deactivation
* Standard activation:: How to manually (de)activate ECB
* Automatic activation:: Automatically (de)activating ECB
Usage of ECB
* Using the mouse:: Working with the mouse
* Using the keyboard:: Working with the keyboard
* The edit-area:: How to use the edit-area
* Temp- and compile-buffers:: Displaying temp- and compilation-buffers
* The other window:: How the ``other window'' is determined
* The Methods window:: Using and customizing the Methods-window
* Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers
* The ECB-layout:: Changing, customizing, redrawing, creating
* Hiding the ECB windows:: Hiding/Showing the ECB-windows
* Maximizing the ECB windows:: Maximizing the ECB-windows
* Back/forward navigation:: Back- and forward navigation like a browser
* ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows
* Stealthy background tasks:: Stealthy background-tasks of ECB
* Interactive ECB commands:: All interactive user-commands of ECB
Working with the keyboard in the ECB-windows
* Navigation/Selection:: Keyboard navigation/selection in a tree-buffer
* Incremental search:: Find nodes as fast as possible
* Personal tree-keybindings:: Adding personal keybindings to a tree-buffer
* Using popup-menus:: Using the popup-menus from keyboard.
Using and customizing the ECB-Methods window
* Visiting tags:: Possible actions after visiting a tag
* Expanding:: Explicit and automatic expanding
* Customizing the display:: How to customize the Methods-buffer display
* Updating Methods-window:: Updating Methods with contents of current buffer
* Updating for ind. buffers:: Updating Methods for indirect buffers
* Jumping to external tags:: Jumping to the definition of external types
Applying filters to the special ECB-tree-buffers
* Filtering Directories:: Applying filters to the Directories-buffer
* Filtering Sources:: Applying filters to the Sources--buffer
* Filtering History:: Applying filters to the History-buffer
* Filtering Methods:: Applying filters to the Methods-buffer
Changing, customizing, redrawing and creating layouts
* Changing the ECB-layout:: How to change and customize the layout
* Redrawing the ECB-layout:: How and when redrawing the layout
* Changing window sizes:: Changing sizes of the ECB-windows
* Fixing window sizes:: Fixing sizes of the ECB-windows
* Creating a new ECB-layout:: Interactively creating new layouts
Synchronization of the ECB-windows
* General synchronization aspects:: General synchronization aspects
* Synchronization of basic ECB-windows:: Synchronization of basic ECB-windows
* Add-on synchronization:: Synchronization of add-on ECB-windows
Customizing ECB
* General aspects:: General aspects for customizing ECB
* Most important options:: Which option you must know
* Customizable options:: All customizable options of ECB
General aspects for customizing ECB
* setq or customize:: Should i use setq or customize?
* Site-wide customizing:: Site-wide customizing of ECB
All customizable options of ECB
* ecb-general:: General customizing ECB
* ecb-tree-buffer:: Customizing the general tree layout
* ecb-directories:: Customizing the ECB-directories-tree
* ecb-sources:: Customizing the ECB-sources-window
* ecb-methods:: Customizing the ECB-methods-window
* ecb-history:: Customizing the ECB-history-window
* ecb-analyse:: Customizing the ECB-analyse-window
* ecb-symboldef:: Customizing the ECB-symboldef-window
* ecb-layout:: Customizing the ECB-layout
* ecb-compilation:: Customizing the compile-window
* ecb-create-layout:: Customizing options for creating layouts
* ecb-face-options:: Customizing options for faces
* ecb-faces:: Customizing the faces
* ecb-help:: Customizing the online help of ECB
* ecb-eshell:: Customizing the eshell-integration
* ecb-speedbar:: Customizing the speedbar-integration
* ecb-non-semantic:: Customizing parsing non-semantic sources
* ecb-winman:: Customizing window-manager support
* ecb-mode-line:: Customizing the tree-buffer-modelines
* ecb-version-control:: Customizing the version-control-support
Upgrading and downloading packages
* Downloading new versions:: How to download newer versions of packages
* Auto. option-upgrading:: ECB can auto. upgrade your options
Automatic upgrading of options
* User interface:: Options and commands you should know
* Background information:: Maybe some interesting informations
Handling of common use-cases
* Changing faces:: Changing faces in the ECB tree-buffers
* Small screens:: Working with small screens
* Big screens:: Working with big screens
* Simulating speedbar:: Simulating speedbar without an extra frame
* Integrating speedbar:: Integrating speedbar in the ECB-frame
* Large directories:: Working with large directories
* Remote directories:: Working with remote directories
* Version-control support:: Supporting Version control systems
* Using eshell:: Optimal using of eshell in ECB
* Grepping directories:: Grepping directories with ECB
* Working with JDEE:: Working best with ECB and JDEE
* Compile-window on demand:: Displaying the compile-window on demand
* Non-semantic sources:: Parsing and displaying non-semantic sources
* Hide-show:: Using hide-show from the methods-buffer-menu
* Window-managers and ECB:: Support of several Emacs-window-managers
* Virtual folders in History:: Simulating something like virtual folders
Supporting Version control systems
* Identifying backends:: How ECB identifies the VC-backend of a dir
* Checking the state:: How ECB checks the VC-state of a file
* Remote repositories:: What you should know about this
* Refreshing the VC-state:: How to refresh when state changed outside
* Adding new backends:: Necessary steps for adding new backends
* Known VC-problems:: Currently known problems of the VC-support
Entry points for Elisp programmers
* List of variables:: Which variables an Elisp-program can use
* List of hooks:: All available hooks
* tree-buffer:: Full description of the tree-buffer-library
* Adviced functions:: How to deal with the adviced functions
* The layout-engine:: Programming new layouts and special windows
The library tree-buffer.el
* Introduction:: General description of tree-buffers
* A new tree-buffer:: How to create a new tree-buffer
* A new tree-node:: How to add new tree-nodes to a tree-buffer
* Updating a tree-buffer:: How to update a tree-buffer after changes
* Tree-buffer keybindings:: Default and customizable keybindings
* The tree-buffer-API:: All functions for tree-buffers and -nodes
* Do not with tree-buffer:: Things which are strictly forbidden
* Tree-buffer How to:: Dealing with special situations
How to program new layouts and new special windows
* Programming a new layout:: How to program a new layout
* Programming special windows:: Aspects of programming special windows
* Possible layout-outlines:: The wide range of possible layouts
* The layout-engine API:: The complete layout-engine API
Conflicts and bugs of ECB
* Conflicts:: Conflicts with other packages
* Bugs:: Known bugs
@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
* Makefile customization:: Customizing build using Makefile.conf
@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, Makefile customization, 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.)
@file{Mekefile} can be customized using @file{Makefile.conf}
(@pxref{Makefile customization}).
@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 Makefile customization, , Standard ECB-Installation, Installation
@subsection Customizing build using Makefile.conf
Platform specific vars and programs can be customized from a
command-line or by means of @file{Makefile.conf}, for which
@file{Makefile.conf.template} is a template. It contains descriptions
of all configuration options. Copy it to @file{Makefile.conf} and
override as needed.
If settings hasn't been changed, @file{Makefile} uses platform
specific defaults.
There is a target, that prints configuration values: @code{make
printconf}.
When you use CEDET built into Emacs and don't install help, then you
don't even need the @file{Makefile.conf}.
When you use CEDET from the repo and/or want to install info files,
then set appropriate variables in @file{Makefile.conf}, for example:
@example
CEDET = ~/projects/cedet-bzr
EMACSINFOPATH = ~/.emacs.d/info
@end example
@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
<base-buffer BB>
<indirect-buffer 1 of BB>
<indirect-buffer 2 of BB>
<indirect-buffer 3 of BB>
@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
[-] <base-buffer BB>
| <indirect-buffer 1 of BB>
| <indirect-buffer 2 of BB>
`- <indirect-buffer 3 of BB>
@end example
Here the buffer with name ``<base-buffer BB>'' 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 <All actions for activation but no layout drawing>
@item @code{ecb-activate-before-layout-draw-hook}
@item @code{ecb-redraw-layout-before-hook}
@item <Drawing the layout>
@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 <All actions for deactivation of ECB>
@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 | | |
| | | |
|-------------| | |
| | | |