forked from FG42/FG42
15946 lines
622 KiB
Plaintext
15946 lines
622 KiB
Plaintext
\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
|
||
|
||
How to set up Emacs for file parsing with ECB
|
||
|
||
* General hints:: General hints for a correct setup
|
||
* Setting up CEDET/semantic:: How to setup semantic correctly
|
||
* Non-semantic files:: Setup for file types not supported by semantic
|
||
|
||
All ECB-windows of ECB
|
||
|
||
* Basic ECB-windows:: Description of the basic ECB-windows
|
||
* Add-on ECB-windows:: Description of additional ECB-windows
|
||
|
||
The basic ECB-windows of ECB
|
||
|
||
* Tree-buffer basics:: General introduction into tree-buffers
|
||
* Tree-buffer styles:: Displaying the trees with different styles
|
||
* ECB Directories-window:: Contents of the ECB Directories-window
|
||
* ECB Sources-window:: Contents of the ECB Sources-window
|
||
* ECB Methods-window:: Contents of the ECB Methods-window
|
||
* ECB History-window:: Contents of the ECB History-window
|
||
|
||
Displaying the trees with different styles
|
||
|
||
* Style basics:: Basic knowledge about the styles
|
||
* Ascii-based styles:: How to customize the ascii-styles
|
||
* Tree-buffers with images:: Which images are used for the tree
|
||
* Images for Methods-buffer:: Images for the tags in the Methods-buffer
|
||
|
||
Add-on ECB-windows of ECB
|
||
|
||
* Semantic analyser:: Analyses and displays semantic context
|
||
* Symboldefinition:: Displays definition of current symbol
|
||
|
||
Activation and Deactivation
|
||
|
||
* Standard activation:: How to manually (de)activate ECB
|
||
* Automatic activation:: Automatically (de)activating ECB
|
||
|
||
Usage of ECB
|
||
|
||
* Using the mouse:: Working with the mouse
|
||
* Using the keyboard:: Working with the keyboard
|
||
* The edit-area:: How to use the edit-area
|
||
* Temp- and compile-buffers:: Displaying temp- and compilation-buffers
|
||
* The other window:: How the ``other window'' is determined
|
||
* The Methods window:: Using and customizing the Methods-window
|
||
* Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers
|
||
* The ECB-layout:: Changing, customizing, redrawing, creating
|
||
* Hiding the ECB windows:: Hiding/Showing the ECB-windows
|
||
* Maximizing the ECB windows:: Maximizing the ECB-windows
|
||
* Back/forward navigation:: Back- and forward navigation like a browser
|
||
* ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows
|
||
* Stealthy background tasks:: Stealthy background-tasks of ECB
|
||
* Interactive ECB commands:: All interactive user-commands of ECB
|
||
|
||
Working with the keyboard in the ECB-windows
|
||
|
||
* Navigation/Selection:: Keyboard navigation/selection in a tree-buffer
|
||
* Incremental search:: Find nodes as fast as possible
|
||
* Personal tree-keybindings:: Adding personal keybindings to a tree-buffer
|
||
* Using popup-menus:: Using the popup-menus from keyboard.
|
||
|
||
Using and customizing the ECB-Methods window
|
||
|
||
* Visiting tags:: Possible actions after visiting a tag
|
||
* Expanding:: Explicit and automatic expanding
|
||
* Customizing the display:: How to customize the Methods-buffer display
|
||
* Updating Methods-window:: Updating Methods with contents of current buffer
|
||
* Updating for ind. buffers:: Updating Methods for indirect buffers
|
||
* Jumping to external tags:: Jumping to the definition of external types
|
||
|
||
Applying filters to the special ECB-tree-buffers
|
||
|
||
* Filtering Directories:: Applying filters to the Directories-buffer
|
||
* Filtering Sources:: Applying filters to the Sources--buffer
|
||
* Filtering History:: Applying filters to the History-buffer
|
||
* Filtering Methods:: Applying filters to the Methods-buffer
|
||
|
||
Changing, customizing, redrawing and creating layouts
|
||
|
||
* Changing the ECB-layout:: How to change and customize the layout
|
||
* Redrawing the ECB-layout:: How and when redrawing the layout
|
||
* Changing window sizes:: Changing sizes of the ECB-windows
|
||
* Fixing window sizes:: Fixing sizes of the ECB-windows
|
||
* Creating a new ECB-layout:: Interactively creating new layouts
|
||
|
||
Synchronization of the ECB-windows
|
||
|
||
* General synchronization aspects:: General synchronization aspects
|
||
* Synchronization of basic ECB-windows:: Synchronization of basic ECB-windows
|
||
* Add-on synchronization:: Synchronization of add-on ECB-windows
|
||
|
||
Customizing ECB
|
||
|
||
* General aspects:: General aspects for customizing ECB
|
||
* Most important options:: Which option you must know
|
||
* Customizable options:: All customizable options of ECB
|
||
|
||
General aspects for customizing ECB
|
||
|
||
* setq or customize:: Should i use setq or customize?
|
||
* Site-wide customizing:: Site-wide customizing of ECB
|
||
|
||
All customizable options of ECB
|
||
|
||
* ecb-general:: General customizing ECB
|
||
* ecb-tree-buffer:: Customizing the general tree layout
|
||
* ecb-directories:: Customizing the ECB-directories-tree
|
||
* ecb-sources:: Customizing the ECB-sources-window
|
||
* ecb-methods:: Customizing the ECB-methods-window
|
||
* ecb-history:: Customizing the ECB-history-window
|
||
* ecb-analyse:: Customizing the ECB-analyse-window
|
||
* ecb-symboldef:: Customizing the ECB-symboldef-window
|
||
* ecb-layout:: Customizing the ECB-layout
|
||
* ecb-compilation:: Customizing the compile-window
|
||
* ecb-create-layout:: Customizing options for creating layouts
|
||
* ecb-face-options:: Customizing options for faces
|
||
* ecb-faces:: Customizing the faces
|
||
* ecb-help:: Customizing the online help of ECB
|
||
* ecb-eshell:: Customizing the eshell-integration
|
||
* ecb-speedbar:: Customizing the speedbar-integration
|
||
* ecb-non-semantic:: Customizing parsing non-semantic sources
|
||
* ecb-winman:: Customizing window-manager support
|
||
* ecb-mode-line:: Customizing the tree-buffer-modelines
|
||
* ecb-version-control:: Customizing the version-control-support
|
||
|
||
Upgrading and downloading packages
|
||
|
||
* Downloading new versions:: How to download newer versions of packages
|
||
* Auto. option-upgrading:: ECB can auto. upgrade your options
|
||
|
||
Automatic upgrading of options
|
||
|
||
* User interface:: Options and commands you should know
|
||
* Background information:: Maybe some interesting informations
|
||
|
||
Handling of common use-cases
|
||
|
||
* Changing faces:: Changing faces in the ECB tree-buffers
|
||
* Small screens:: Working with small screens
|
||
* Big screens:: Working with big screens
|
||
* Simulating speedbar:: Simulating speedbar without an extra frame
|
||
* Integrating speedbar:: Integrating speedbar in the ECB-frame
|
||
* Large directories:: Working with large directories
|
||
* Remote directories:: Working with remote directories
|
||
* Version-control support:: Supporting Version control systems
|
||
* Using eshell:: Optimal using of eshell in ECB
|
||
* Grepping directories:: Grepping directories with ECB
|
||
* Working with JDEE:: Working best with ECB and JDEE
|
||
* Compile-window on demand:: Displaying the compile-window on demand
|
||
* Non-semantic sources:: Parsing and displaying non-semantic sources
|
||
* Hide-show:: Using hide-show from the methods-buffer-menu
|
||
* Window-managers and ECB:: Support of several Emacs-window-managers
|
||
* Virtual folders in History:: Simulating something like virtual folders
|
||
|
||
Supporting Version control systems
|
||
|
||
* Identifying backends:: How ECB identifies the VC-backend of a dir
|
||
* Checking the state:: How ECB checks the VC-state of a file
|
||
* Remote repositories:: What you should know about this
|
||
* Refreshing the VC-state:: How to refresh when state changed outside
|
||
* Adding new backends:: Necessary steps for adding new backends
|
||
* Known VC-problems:: Currently known problems of the VC-support
|
||
|
||
Entry points for Elisp programmers
|
||
|
||
* List of variables:: Which variables an Elisp-program can use
|
||
* List of hooks:: All available hooks
|
||
* tree-buffer:: Full description of the tree-buffer-library
|
||
* Adviced functions:: How to deal with the adviced functions
|
||
* The layout-engine:: Programming new layouts and special windows
|
||
|
||
The library tree-buffer.el
|
||
|
||
* Introduction:: General description of tree-buffers
|
||
* A new tree-buffer:: How to create a new tree-buffer
|
||
* A new tree-node:: How to add new tree-nodes to a tree-buffer
|
||
* Updating a tree-buffer:: How to update a tree-buffer after changes
|
||
* Tree-buffer keybindings:: Default and customizable keybindings
|
||
* The tree-buffer-API:: All functions for tree-buffers and -nodes
|
||
* Do not with tree-buffer:: Things which are strictly forbidden
|
||
* Tree-buffer How to:: Dealing with special situations
|
||
|
||
How to program new layouts and new special windows
|
||
|
||
* Programming a new layout:: How to program a new layout
|
||
* Programming special windows:: Aspects of programming special windows
|
||
* Possible layout-outlines:: The wide range of possible layouts
|
||
* The layout-engine API:: The complete layout-engine API
|
||
|
||
Conflicts and bugs of ECB
|
||
|
||
* Conflicts:: Conflicts with other packages
|
||
* Bugs:: Known bugs
|
||
|
||
@end detailmenu
|
||
@end menu
|
||
|
||
@node Install and first steps, Overview, Top, Top
|
||
@chapter Installation and first steps of ECB
|
||
|
||
This chapter describes how to install ECB and setup (X)Emacs correctly
|
||
and what are the first steps after activation of ECB.
|
||
|
||
@menu
|
||
* Installation:: Installation of ECB
|
||
* Setting up Emacs:: How to set up Emacs for file parsing with ECB
|
||
* First steps:: First steps after activating ECB first time
|
||
@end menu
|
||
|
||
@node Installation, Setting up Emacs, Install and first steps, Install and first steps
|
||
@section Installation of ECB
|
||
|
||
This section describes how to install ECB.
|
||
|
||
@menu
|
||
* Requirements:: Requirements for ECB
|
||
* ECB as XEmacs-package:: Installation of ECB as a XEmacs-package
|
||
* Standard ECB-Installation:: Standard installation of ECB for (X)Emacs
|
||
@end menu
|
||
|
||
@node Requirements, ECB as XEmacs-package, Installation, Installation
|
||
@subsection Requirements
|
||
|
||
This section describes the requirements of ECB. Just ensure that these
|
||
requirements of ECB are fulfilled.
|
||
|
||
The short story: With Emacs >= 23.2 there is nothing to do. With XEmacs or
|
||
Emacs < 23.2 you have to install the CEDET-suite.
|
||
|
||
The long story:
|
||
|
||
@enumerate
|
||
|
||
@item Emacs-version:
|
||
ECB works only with (X)Emacs >= 21! If you have an older one, please upgrade.
|
||
|
||
@item CEDET-suite:
|
||
If Emacs >= 23.2 is used then CEDET is already integrated into Emacs and there
|
||
is nothing to do.
|
||
|
||
For users of any XEmacs-version, any Emacs-version < 23.2 or the latest author
|
||
CEDET version: Get it from @url{http://cedet.sourceforge.net}, read the
|
||
setup-instructions in @url{http://cedet.sourceforge.net/setup.shtml} and read
|
||
also the shipped file @file{INSTALL}.
|
||
|
||
@strong{Please note}: If ECB detects an author version of CEDET (as available
|
||
at @url{http://cedet.sourceforge.net}) then ECB will ALWAYS try to use that
|
||
one even if you use Emacs >= 23.2! This is for users who want to use latest
|
||
Emacs >= 23.2 but still prefer using the latest author version of CEDET
|
||
instead of the Emacs-integrated one.
|
||
|
||
So if you want to use the Emacs-integrated CEDET-suite of Emacs >= 23.2 you
|
||
have to ensure that no author-version of CEDET is in the @code{load-path}!
|
||
This means that the library cedet.el of the author-version MUST NOT be loaded
|
||
into Emacs (as described in the file INSTALL of CEDET)! This is a valid check:
|
||
(locate-library "semantic-ctxt") must return nil!
|
||
|
||
@item Only for XEmacs-users:
|
||
If you use XEmacs you must have installed the
|
||
package c-support (contains hideshow.el). If you want to read the online-help
|
||
of ECB in HTML-format you must have the library browse-url (part of the
|
||
mail-lib XEmacs package) installed; this package is also needed for submitting
|
||
problem-reports to the ECB-maintainers!
|
||
|
||
@item Optional for Java-coding:
|
||
ECB works very well with the JDEE package (
|
||
@url{http://jdee.sourceforge.net}) but JDEE is not required by ECB.
|
||
|
||
@end enumerate
|
||
|
||
Do not install ECB before you have successfully installed the requirements!
|
||
|
||
@node ECB as XEmacs-package, Standard ECB-Installation, Requirements, Installation
|
||
@subsection Installation of ECB as a XEmacs-package
|
||
|
||
This section is only relevant for XEmacs-users!
|
||
|
||
In previous versions of ECB XEmacs-users could use the
|
||
package-management-system of XEmacs for first-time downloading/installing ECB
|
||
or for upgrading to a newer version of ECB.
|
||
|
||
Beginning with version 2.33 ECB does no longer support the old versions of
|
||
semantic, eieio and speedbar not part of the CEDET-suite. ECB >= 2.33 requires
|
||
fully installed CEDET-suite with version >= 1.0pre6. This one is not available as
|
||
XEmacs-package. Therefore ECB can also not be run as XEmacs-package. If cedet
|
||
will become a XEmacs-package then probably ECB will come back as
|
||
XEmacs-package. But in the meanwhile you have to install ECB ``by hand'' as
|
||
described in the next section (@pxref{Standard ECB-Installation}).
|
||
|
||
@c @strong{Recommendation}: If you are able to manually install ECB and its
|
||
@c requirements as described in @ref{Standard ECB-Installation} then go on and
|
||
@c proceed with that (you will see, it's easy). You will get a much more powerful
|
||
@c ECB and also CEDET/semantic.
|
||
@c
|
||
@c If you are desperate to use the package-management-system of ECB for
|
||
@c installing ECB, then here is a short guide (for details about the
|
||
@c package-manager of XEmacs see the related info-manual):
|
||
@c
|
||
@c @strong{Caution}: If ECB is already installed and you just want
|
||
@c upgrading to a newer version then it is recommended to deactivate ECB
|
||
@c before proceeding with the steps below!
|
||
@c
|
||
@c @enumerate
|
||
@c @item Choose a download-site
|
||
@c
|
||
@c This can be done via the menu ``Tools --> Packages --> Add Download
|
||
@c Site'': Choose one of the listed sites. Or you can customize the
|
||
@c option @code{package-get-remote} by hand and save it for future
|
||
@c sessions.
|
||
@c
|
||
@c @item Activate the packages list
|
||
@c
|
||
@c This can be done either by the menu ``Tools --> Packages --> List and
|
||
@c Install'' or via the command @code{pui-list-packages}. After that a
|
||
@c special packages-buffer is displayed where you can interactively
|
||
@c install or upgrade packages. At the end of this buffer there is a
|
||
@c short description how to use this buffer.
|
||
@c
|
||
@c @item Install ECB and all required packages
|
||
@c
|
||
@c Mark the package named ``ecb'' for install. Do this also for the
|
||
@c required packages ``semantic'', ``eieio'' and ``speedbar''. The
|
||
@c package ``mail-lib'' is needed for easy submitting of problem-reports
|
||
@c to the ECB-maintainers and the package ``c-support'' is needed for
|
||
@c easy using hideshow within the Methods-buffer of ECB@footnote{All
|
||
@c required packages can simply autom. marked by hitting @kbd{r} in the
|
||
@c packages buffer. But this installs a lot of packages more (e.g. the
|
||
@c Newsreader Gnus) which are really not essential for ECB. Therefore it
|
||
@c is recommended to mark the required packages by hand.}.
|
||
@c
|
||
@c After marking all needed packages for installation hit @kbd{x} to
|
||
@c install them.
|
||
@c
|
||
@c If you have already installed ECB and you want just upgrading to the
|
||
@c latest available version then proceed as described above - same if you
|
||
@c want to upgrade one of the required packages.
|
||
@c
|
||
@c @item Start ECB
|
||
@c
|
||
@c Now you can immediately start ECB via the command @code{ecb-activate};
|
||
@c there is no need to restart XEmacs! As an alternative you can first
|
||
@c read the online-help via @code{ecb-show-help}.
|
||
@c
|
||
@c @end enumerate
|
||
@c
|
||
@c If you do not like the package-manager of XEmacs but you want
|
||
@c installing ECB ``by hand'' direct from the ECB-website then you have
|
||
@c to follow the instructions in @ref{Standard ECB-Installation}.
|
||
|
||
@node Standard ECB-Installation, , ECB as XEmacs-package, Installation
|
||
@subsection Standard installation of ECB for (X)Emacs
|
||
|
||
Follow exatly these steps to install ECB:
|
||
|
||
@enumerate
|
||
|
||
@item
|
||
Fulfill all requirements ECB needs (@pxref{Requirements})
|
||
|
||
ECB performs two autom checks:
|
||
|
||
@itemize @minus
|
||
@item At load-time:
|
||
It checks if cedet is at least installed so ECB can be loaded. If not it
|
||
reports an error.
|
||
|
||
@item At start-time:
|
||
It checks if the correct versions of cedet and semantic are installed and
|
||
gives you proper feedback.
|
||
@end itemize
|
||
|
||
So if you are not sure if you have installed the required packages at
|
||
all or if you have installed the correct versions of these packages
|
||
then do not worry about this, just go on with the following
|
||
installation steps: If ECB is missing something it will give you
|
||
proper feedback and support not later than at load-time or start-time!
|
||
|
||
@item
|
||
Download and unpack the ECB archive (probably you have already done
|
||
this :-)
|
||
|
||
@item
|
||
Add the new ECB-directory to your @code{load-path} variable.
|
||
|
||
You @strong{MUST} add the ECB-install-directory to the @code{load-path} either
|
||
by changing the @code{load-path} variable directly in your @file{.emacs} or
|
||
@file{site-lisp/site-start.el} or by working with a file
|
||
@file{subdirs.el}@footnote{This works at least for Emacs but XEmacs may have
|
||
slightly different mechanisms; see the XEmacs documentation}.
|
||
|
||
So for example the needed entry for your @file{.emacs}-file could be:
|
||
|
||
@example
|
||
(add-to-list 'load-path
|
||
"/path/to/your/ecb/installation/directory")
|
||
@end example
|
||
|
||
@strong{ATTENTION}:
|
||
ECB is NOT properly installed if it's directory is not added to
|
||
@code{load-path} and for example just loaded by
|
||
|
||
@example
|
||
(load-file "/path/to/ecb/ecb.el")
|
||
@end example
|
||
|
||
Do not do this! It will not work!
|
||
|
||
@item
|
||
Load ECB by adding code to your @file{.emacs}:
|
||
|
||
If you want to load the complete ECB at (X)Emacs-loadtime (Advantage:
|
||
All ECB-options available after loading ECB. Disadvantage: Increasing
|
||
loadtime@footnote{Cause of full loading of ECB itself and also the
|
||
packages semantic, eieio and speedbar regardless if ECB is started.}):
|
||
|
||
@example
|
||
(require 'ecb)
|
||
@end example
|
||
|
||
If you want to load the ECB first after starting it by
|
||
@code{ecb-activate} (Advantage: Fast loading@footnote{ECB, semantic,
|
||
eieio and speedbar are first loaded after starting ECB or with other
|
||
words: ECB and semantic are not loaded if you do not use/need them}.
|
||
Disadvantage: ECB- and semantic-options first available after starting
|
||
ECB):
|
||
|
||
@example
|
||
(require 'ecb-autoloads)
|
||
@end example
|
||
|
||
This loads all available autoloads of ECB, e.g. @code{ecb-activate},
|
||
@code{ecb-minor-mode}, @code{ecb-byte-compile} and
|
||
@code{ecb-show-help}.
|
||
|
||
Regardless which method you prefer: In both cases the used statement
|
||
must be placed @strong{after} the statement of step 3!
|
||
|
||
Only for users of a manually installed author version of the CEDET-suite (not
|
||
that one integrated into Emacs >= 23.2): Instructions for loading CEDET into
|
||
Emacs must be placed somewhere before the statements needed for loading ECB
|
||
(s.a.)!
|
||
|
||
@item Restart (X)Emacs.
|
||
@end enumerate
|
||
|
||
ECB is now ready for use and can be activated by calling @code{M-x
|
||
ecb-activate} or @code{ecb-minor-mode}. Now you can either starting
|
||
using ECB or you can do these optional installation steps:
|
||
|
||
@enumerate 6
|
||
|
||
@item Reading the online help with @code{ecb-show-help}
|
||
|
||
Maybe you are interested to read the online-help of ECB before first
|
||
start.
|
||
|
||
@item Bytecompiling ECB with @code{ecb-byte-compile}
|
||
|
||
This byte compiles ECB. You can safely ignore all messages if there
|
||
are any. (You can also bytecompile ECB from the command-line either by
|
||
using the @file{Makefile} or by using the batch-file @file{make.bat};
|
||
just read the comments in that file you choose.)
|
||
|
||
@item Installing the Info-help of ECB
|
||
|
||
The ECB distribution contains a subdirectory @file{info-help} which
|
||
contains the online-help of ECB in Info-format. You can install this
|
||
online help so it's available in the Top-directory of Info. There are
|
||
two ways to do this:
|
||
|
||
@itemize @minus
|
||
@item Use ``install-info'' (recommended):
|
||
|
||
@enumerate
|
||
@item
|
||
Copy the files of the subdirectory @file{info-help} into the
|
||
info-directory of Emacs
|
||
|
||
@item
|
||
Install the file @file{info-help/ecb.info} with the command
|
||
``install-info'' (if available on your system) in the @file{dir}-file.
|
||
@end enumerate
|
||
|
||
The supplied @file{Makefile} offers a target @code{install-help} which
|
||
does both of these steps. You have just to call @code{make
|
||
install-help} with the correct EMACSINFOPATH set (see the comment in
|
||
@file{Makefile}). Here is an example:
|
||
|
||
@example
|
||
make EMACSINFOPATH=/path/to/emacs/info install-help
|
||
@end example
|
||
|
||
@item Manual Installation:
|
||
|
||
Copy the files of the subdirectory @file{info-help} into the
|
||
info-directory of Emacs and modify the file @file{dir} manually.
|
||
@end itemize
|
||
|
||
But it doesn't matter if you do not execute this step (8.) because the
|
||
online help of ECB is always available though, see
|
||
@code{ecb-show-help} (@pxref{Interactive ECB commands}).
|
||
|
||
@end enumerate
|
||
|
||
@node Setting up Emacs, First steps, Installation, Install and first steps
|
||
@section How to set up Emacs for file parsing with ECB
|
||
|
||
@strong{Please note}: Normally it should not necessary for you to
|
||
bother with the following stuff unless you have problems getting ECB
|
||
working correctly for you.
|
||
|
||
@menu
|
||
* General hints:: General hints for a correct setup
|
||
* Setting up CEDET/semantic:: How to setup semantic correctly
|
||
* Non-semantic files:: Setup for file types not supported by semantic
|
||
@end menu
|
||
|
||
@node General hints, Setting up CEDET/semantic, Setting up Emacs, Setting up Emacs
|
||
@subsection General hints for a correct setup
|
||
|
||
ECB is for browsing files and therefore you have to setup your
|
||
Emacs-configuration properly so the file-parsing engines like semantic, imenu
|
||
or etags can be activated automatically for parsing your Emacs-Lisp, C, C++ or
|
||
Java buffers@footnote{semantic supports some more ``languages'' like Phython,
|
||
Makefiles and some more. But these are the most important ones.}. For this
|
||
Emacs must activate the correct @code{major-mode} for the source-files and
|
||
Emacs can only do this if the option @code{auto-mode-alist} is setup
|
||
correctly. The correct major-modes and possible
|
||
file-extensions@footnote{Especially for C++ and C you can use any extension
|
||
you want but these are the most common ones!} are:
|
||
|
||
@multitable @columnfractions 0.20 0.50 0.30
|
||
|
||
@item
|
||
@ifnotinfo
|
||
@strong{Language}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
LANGUAGE
|
||
@end ifinfo
|
||
@tab
|
||
@ifnotinfo
|
||
@strong{Major-mode}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
MAJOR-MODE
|
||
@end ifinfo
|
||
@tab
|
||
@ifnotinfo
|
||
@strong{Extension(s)}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
EXTENSION(S)
|
||
@end ifinfo
|
||
|
||
@item Emacs Lisp @tab @code{emacs-lisp-mode} @tab .el
|
||
|
||
@item C @tab @code{c-mode} @tab .h, .c
|
||
|
||
@item C++ @tab @code{c++-mode} @tab .h, .hxx, .hh, .HH, .cxx, .cpp,
|
||
.cc, .CC
|
||
|
||
@item Java @tab @code{java-mode} or @code{jde-mode} (if you use JDEE)
|
||
@tab .java
|
||
@end multitable
|
||
|
||
Example: If you want files with extension ``.cpp'' being c++-parsed by
|
||
semantic and ECB, your @code{auto-mode-alist} must contain an entry
|
||
like:
|
||
|
||
@example
|
||
("\\.cpp\\'" . c++-mode)
|
||
@end example
|
||
|
||
After this ECB will correctly parse your ``.cpp''-sources and display
|
||
all the parsing information in the ECB-methods buffer.
|
||
|
||
@node Setting up CEDET/semantic, Non-semantic files, General hints, Setting up Emacs
|
||
@subsection Setting up CEDET/semantic
|
||
|
||
To ensure ECB and semantic are working correctly for all by semantic
|
||
supported languages you have to pay attention to the following aspects
|
||
concerning your Emacs-setup:
|
||
|
||
@enumerate
|
||
@item Setting up CEDET/semantic itself
|
||
|
||
This section implies that you either use Emacs >= 23.2 or that you have
|
||
already successfully installed the CEDET-suite.
|
||
|
||
For all semantic-supported file-types parsing files is done completely
|
||
by semantic. ECB just displays the parsing results.
|
||
|
||
@itemize
|
||
@item Users of Emacs >= 23.2:
|
||
You just have to enable semantic by activating the semantic-mode. This can be
|
||
done by adding code to your initialization-file (e.g. .emacs) like
|
||
this:
|
||
|
||
@lisp
|
||
(semantic-mode 1)
|
||
@end lisp
|
||
|
||
This should be placed BEFORE the statements which activate ECB.
|
||
|
||
As an alternative you can use the @code{ecb-before-activate-hook} like
|
||
follows:
|
||
|
||
@lisp
|
||
(add-hook 'ecb-before-activate-hook
|
||
(lambda () (semantic-mode 1)))
|
||
@end lisp
|
||
|
||
This is a smarter way when you need semantic only if ECB is active.
|
||
|
||
@item Users of XEmacs or Emacs < 23.2:
|
||
You should read carefully the file @file{INSTALL} shipped with the
|
||
cedet-suite. In addition the CEDET-website offers a link to a ``Gentle
|
||
introduction to Cedet''. It's worth to read it! You find it here:
|
||
@ifhtml
|
||
@uref{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html}
|
||
@end ifnothtml
|
||
If CEDET is not correctly installed then ECB can not setup semantic for its
|
||
needs.
|
||
|
||
@end itemize
|
||
|
||
@strong{Minimum setup recommendation}: It is very useful to enable the
|
||
@code{global-semantic-idle-scheduler-mode} and
|
||
@code{global-semanticdb-minor-mode}. Read the manual of Emacs 23.2 or the
|
||
manual of cedet/semantic how to do this. With CEDET-versions >= 1.0pre6 this
|
||
can be done by adding @code{semantic-load-enable-minimum-features} to your
|
||
startup-file. Please read also the subsection ``Jumping to the definition of
|
||
external types'' in @ref{ECB Methods-window}.
|
||
|
||
@anchor{Checking your hooks}
|
||
@item Checking your hooks (Only for XEmacs and Emacs < 23.2!)
|
||
|
||
If you use Emacs > 23.2 you can ignore the following paragraphs.
|
||
|
||
If you have already checked point (1.) and if you have still problems
|
||
getting ECB/semantic working properly for your sources you should
|
||
check the related major-mode hook. Every major-mode X has a hook with
|
||
name ``X-hook'' which is evaluated after activating the major-mode
|
||
(see above, 2.), e.g. the hook for the major-mode @code{c++-mode} is
|
||
@code{c++-mode-hook}.
|
||
|
||
Semantic adds automatically during load-time a special
|
||
``semantic-setup'' to these major-mode hooks@footnote{Of course only
|
||
for major-modes supported by semantic!} in form of a
|
||
``setup-function''. Example: For c and c++ modes semantic adds
|
||
@code{semantic-default-c-setup} to @code{c-mode-hook} and
|
||
@code{c++-mode-hook}.
|
||
|
||
If your own Emacs-setup (e.g. in @file{.emacs} or
|
||
@file{site-lisp/site-start.el}) overwrites such a major-mode-hook then
|
||
semantic can not be activated for this major-mode and in consequence
|
||
ECB can not work properly too!
|
||
|
||
Check if your Emacs-setup uses somewhere @code{setq} for adding code
|
||
to a major-mode-hook. @strong{IMPORTANT}: Use @code{add-hook} instead of
|
||
@code{setq}@footnote{@code{setq} replaces/overwrites the current
|
||
value of a hook with the new value whereas @code{add-hook}
|
||
@strong{adds} the new value to the old-value of the hook!}!
|
||
|
||
@end enumerate
|
||
|
||
If your source-files are ``running'' with correct @code{major-mode} and - in
|
||
case of XEmacs or Emacs < 23.2 - correct major-mode hooks ECB and semantic
|
||
will do what you expect them doing!
|
||
|
||
@node Non-semantic files, , Setting up CEDET/semantic, Setting up Emacs
|
||
@subsection Setup for file types not supported by semantic
|
||
|
||
From version 1.94 on ECB supports also parsing and displaying
|
||
file-contents for file-types not supported by semantic (i.e. there is
|
||
no semantic-grammar available for such file-types).
|
||
|
||
Such non-semantic file-types can often be parsed by imenu and/or
|
||
etags. Both of these parsing methods are now supported: ECB can
|
||
display the results of imenu and/or etags in its Method-buffer. ECB
|
||
uses for this speedbar-logic. Therefore the following speedbar options
|
||
takes effect for this feature:
|
||
|
||
@itemize @minus
|
||
@item @code{speedbar-dynamic-tags-function-list}
|
||
@item @code{speedbar-tag-split-minimum-length}
|
||
@item @code{speedbar-tag-regroup-maximum-length}
|
||
@item @code{speedbar-tag-hierarchy-method}
|
||
@end itemize
|
||
|
||
Normally there should be no need for you to bother with these options,
|
||
because the default values are suitable for most situations! But if
|
||
you are not satisfied with the parsing/display results then you can
|
||
change some of these options.
|
||
|
||
@node First steps, , Setting up Emacs, Install and first steps
|
||
@section First steps after activating ECB first time
|
||
|
||
This section of the ECB online-help is displayed automatically by ECB
|
||
after activating ECB first time and describes what are the first basic
|
||
steps:
|
||
|
||
@enumerate
|
||
|
||
@item Configure where ECB can find your sources:
|
||
|
||
Call @code{M-x customize-option RET ecb-source-path RET}@footnote{This
|
||
means first hitting the keys @kbd{M} (Meta- or Alt-key) and @kbd{x}
|
||
simultaneously, inserting ``customize-option'' in the minibuffer,
|
||
hitting RETURN, inserting ``ecb-source-path'' in the minibuffer and
|
||
finally hitting RETURN again}. This lets you customize the option
|
||
@code{ecb-source-path} with the customize-feature of Emacs. This opens
|
||
a customize-buffer where you can insert all the directories where ECB
|
||
can find your source-files. Save your changes with the button ``Save
|
||
for future sessions'' and then throw away this customize-buffer either
|
||
by killing it with @code{M-x kill-buffer} or clicking at the button
|
||
``Finish''.
|
||
|
||
@item Take a look at the most important options of ECB
|
||
Call @code{M-x ecb-customize-most-important RET} and see a list of
|
||
options which you should at least know that these options exist.
|
||
|
||
@item Read the online-help of ECB:
|
||
|
||
The online-help of ECB is available via
|
||
|
||
@itemize @minus
|
||
@item calling @code{M-x ecb-show-help},
|
||
@item pressing @kbd{C-c . h} or
|
||
@item using the menu ``ECB''.
|
||
@end itemize
|
||
|
||
(The section you are currently reading is part of the online-help of
|
||
ECB)
|
||
|
||
The chapter ``Common use-cases'' is also very interesting!
|
||
|
||
@item Start working with ECB.
|
||
@end enumerate
|
||
|
||
@node Overview, Manual usage, Install and first steps, Top
|
||
@chapter Overview
|
||
|
||
@cindex tree-buffer
|
||
@cindex ECB-windows
|
||
ECB is a global minor-mode which offers a couple of @dfn{ECB-windows}
|
||
for browsing your sources comfortable with the mouse and the keyboard.
|
||
|
||
ECB offers some basic ECB-windows to browse your sources:
|
||
@itemize @minus
|
||
@item ECB-Directories for browsing directories
|
||
@item ECB-Sources for browsing source-files
|
||
@item ECB-Methods for browsing the contents of a source
|
||
@item ECB-History for a history for open or recently opened files
|
||
@end itemize
|
||
|
||
See @ref{Basic ECB-windows} for a detailled description what these
|
||
basic ECB-windows offer. See @ref{ECB-windows} for a general
|
||
introduction in the ECB-window-concept of ECB.
|
||
|
||
In addition ECB offers some add-on ECB-window for special purposes:
|
||
@itemize @minus
|
||
@item ECB-Analyse for some intellisense stuff like possible completions or
|
||
local variables
|
||
@item ECB-Symboldef for displaying the documentation of current symbol under
|
||
point
|
||
@end itemize
|
||
|
||
See @ref{Add-on ECB-windows} for a detailled description what these
|
||
add-on ECB-windows offer.
|
||
|
||
In addition to these ``special'' ECB-windows you have always an
|
||
@dfn{edit-area} where you can edit your source-files. The edit-area can be
|
||
divided into several @dfn{edit-windows} - as many as you need (@pxref{The
|
||
edit-area}). And at the bottom of the ECB-frame a persistent
|
||
@dfn{compilation-window} (also called @dfn{compile-window}) can be displayed
|
||
(optional), where all the output of Emacs-compilation (compile, grep etc.) and
|
||
Emacs temp-buffers (help etc.) is shown (@pxref{Temp- and compile-buffers}).
|
||
|
||
The following ``screenshot'' illustrates the typical layout of the
|
||
ECB-frame@footnote{This is only one example of the layouts ECB offers,
|
||
see @ref{Changing the ECB-layout}}:
|
||
|
||
@example
|
||
@group
|
||
------------------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | |
|
||
| | |
|
||
|--------------| Edit-area |
|
||
| | (can be splitted in several edit-windows) |
|
||
| Methods | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
------------------------------------------------------------------
|
||
| |
|
||
| Persistent Compilation-window (optional) |
|
||
| |
|
||
------------------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@node Manual usage, ECB-windows, Overview, Top
|
||
@chapter How to use this manual
|
||
|
||
@strong{IMPORTANT}: You should have read the chapter @ref{Overview}
|
||
before going on reading the current chapter.
|
||
|
||
This chapter describes shortly the contents of the following chapters
|
||
of this manual so maybe you can find faster what you are searching
|
||
for.
|
||
|
||
@table @asis
|
||
|
||
@item All ECB-windows of ECB (@pxref{ECB-windows})
|
||
Gives an introduction into the concept of ECB-windows of ECB, what
|
||
they are, which different types exist, how they look, how they can be
|
||
used and last but not least what they do in detail, i.e. explains
|
||
every ECB-window of ECB in detail.
|
||
|
||
@item Activation and Deactivation (@pxref{Activation and Deactivation})
|
||
Describes how to activate and deactivate ECB and which different types
|
||
of activation are possible.
|
||
|
||
@item Usage of ECB (@pxref{Usage of ECB})
|
||
Describes in detail how to use ECB with mouse and keyboard, explains
|
||
the concept of the edit-area and the persistent compile-window,
|
||
describe how to change the window-layout and hide and show special
|
||
windows, which stealthy background-tasks ECB performs and so on...
|
||
|
||
@item Customizing ECB (@pxref{Customizing})
|
||
Gives an overview of the most important options of ECB and tell you
|
||
something about do's and don'ts concerning customization of ECB. Lists
|
||
all options of ECB and describe exactly the purpose of them.
|
||
|
||
@item Submitting a problem report (@pxref{Submitting problem report})
|
||
Instructions what to do if you encounters problems with ECB.
|
||
|
||
@item Upgrading and downloading ECB (@pxref{Upgrading})
|
||
Gives an introduction into the automatic option-upgrading-feature of
|
||
ECB.
|
||
|
||
@item Common use-cases (@pxref{Common use-cases})
|
||
How to deal with common (and also some special) situations and circumstances,
|
||
so e.g. working with big and small screens, working with large directories,
|
||
using the builtin version-control-support of ECB, parsing
|
||
non-semantic-supported sources like perl, using hide-show, working best with
|
||
eshell and JDEE and some window-managers of Emacs (like escreen or winring)
|
||
and many more...
|
||
|
||
@item Entry points for Elisp programmers (@pxref{Elisp programming})
|
||
All informations needed by programmers when using some ECB-concepts
|
||
from within other elisp-libraries. This includes a full description
|
||
how to use the ECB-independent library tree-buffer.el. Lists also all
|
||
available hooks and describes with full working example how to program
|
||
own layouts.
|
||
|
||
@item Conflicts and bugs of ECB (@pxref{Conflicts and bugs})
|
||
Lists all currently known bugs and problems and gives well working
|
||
work-arounds.
|
||
|
||
@item Frequently asked Questions (@pxref{FAQ})
|
||
Take a look...
|
||
|
||
@item Command Index (@pxref{Command Index})
|
||
List of all interactive commands of ECB
|
||
|
||
@item Option Index (@pxref{Option Index})
|
||
List of all user-customizable options of ECB
|
||
|
||
@item Concept Index (@pxref{Concept Index})
|
||
List of all concepts introduced by ECB
|
||
|
||
@end table
|
||
|
||
|
||
|
||
@node ECB-windows, Activation and Deactivation, Manual usage, Top
|
||
@chapter All ECB-windows of ECB
|
||
|
||
ECB displays a number of informational windows that allow for easy
|
||
source code navigation and overview. These informational windows are
|
||
called @dfn{ECB-windows}. Each ECB-window is displayed in its own
|
||
special window/buffer which is dedicated and read-only.
|
||
|
||
There are some ``basic'' ECB-windows (e.g. for browsing directories
|
||
and sources) and some ``add-on'' ECB-windows for special purposes like
|
||
displaying the definition of the current symbol under point. This
|
||
chapter describes all ECB-windows of ECB in detail.
|
||
|
||
@menu
|
||
* Basic ECB-windows:: Description of the basic ECB-windows
|
||
* Add-on ECB-windows:: Description of additional ECB-windows
|
||
@end menu
|
||
|
||
@node Basic ECB-windows, Add-on ECB-windows, ECB-windows, ECB-windows
|
||
@section The basic ECB-windows of ECB
|
||
|
||
ECB offers basic ECB-windows for browsing directory-structures, files
|
||
of a directory and contents of source-files (e.g. methods and
|
||
variables). These basic ECB-windows are build from a special class of
|
||
ECB-windows, called @dfn{tree-buffer}. See @ref{Tree-buffer basics}
|
||
for more details about the functionality of tree-buffers. See
|
||
@ref{Tree-buffer styles} to get an impression about the look&feel of
|
||
these tree-buffers.
|
||
|
||
In the following subsections these basic ECB-windows of ECB will be
|
||
explained in detail.
|
||
|
||
@menu
|
||
* Tree-buffer basics:: General introduction into tree-buffers
|
||
* Tree-buffer styles:: Displaying the trees with different styles
|
||
* ECB Directories-window:: Contents of the ECB Directories-window
|
||
* ECB Sources-window:: Contents of the ECB Sources-window
|
||
* ECB Methods-window:: Contents of the ECB Methods-window
|
||
* ECB History-window:: Contents of the ECB History-window
|
||
@end menu
|
||
|
||
@node Tree-buffer basics, Tree-buffer styles, Basic ECB-windows, Basic ECB-windows
|
||
@subsection General introduction into tree-buffers
|
||
|
||
|
||
@subsubsection Content and structure of a tree-buffer
|
||
|
||
ECB displays most of its informations (e.g. about directory-structures
|
||
or file-contents) in so called @dfn{tree-buffers} which means the
|
||
display of such a tree-buffer is structured in a tree consisting of
|
||
@dfn{tree-nodes}. Every line in a tree-buffer displays exactly one
|
||
tree-node. Each node can have any arbitrary number of
|
||
@dfn{children}-nodes. If a tree-node has no children then it is called
|
||
a @dfn{leaf}.
|
||
|
||
Each tree-buffer of ECB is displayed in an own special
|
||
ECB-window/buffer which is read-only ie. not editable.
|
||
|
||
The difference between a natural tree like a fir and an ECB-tree is
|
||
that the root(-node) of a tree-buffer is not visible but only its
|
||
children. In the example below the nodes parent-node-1 and
|
||
parent-node-2 are the children of the invisible root-node.
|
||
|
||
If a tree-node contains at least one child it is displayed with a
|
||
special expand/collapse-symbol (see the example below). This symbol
|
||
allows expanding (rsp. collapsing) the tree-node wheras expanding
|
||
means to display the children-nodes and collapsing means to hide the
|
||
childrens of a tree-node.
|
||
|
||
Here is an example of a tree-buffer:
|
||
|
||
@example
|
||
@group
|
||
[+] parent-node-1 -------.
|
||
[-] parent-node-2 -------|
|
||
[-] expanded --------|
|
||
leaf-node-1 -----|
|
||
leaf-node-2 -----|-----[tree-nodes]
|
||
leaf-node-3 -----|
|
||
leaf-node-4 -----|
|
||
[+] collapsed -------<2D>
|
||
|
|
||
`-----------------[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<6C>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<69>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<69>s job.
|
||
|
||
@item
|
||
Otherwise the behavior depends on the value of the option
|
||
@code{ecb-advice-window-functions-signal-error}.
|
||
@end itemize
|
||
@end itemize
|
||
|
||
If optional argument WINDOW is a living window (i.e. called from
|
||
program): If WINDOW is an edit-window then this window is maximized
|
||
(i.e. the other edit-window is deleted) if there are more at least 2
|
||
edit-windows otherwise the compile-window is deleted (if there is
|
||
one). If WINDOW is an ecb-window then only the other ecb-windows are
|
||
deleted and in all other cases the behavior depends on
|
||
@code{ecb-advice-window-functions-signal-error}.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command delete-windows-on BUFFER &optional FRAME
|
||
Around-advice @code{ecb}: The ECB-version of @code{delete-windows-on}.
|
||
Works exactly like the original function with the following
|
||
ECB-adjustment:
|
||
|
||
An error is reported if @var{BUFFER} is an ECB-tree-buffer. These
|
||
windows are not allowed to be deleted.
|
||
@end deffn
|
||
|
||
@deffn Command split-window &optional WINDOW SIZE HORFLAG
|
||
Around-advice @code{ecb}: The ECB-version of @code{split-window}.
|
||
Works exactly like the original function with the following
|
||
ECB-adjustment:
|
||
|
||
If called for a not-edit-window in the @code{ecb-frame} it stops with
|
||
an error if @code{split-window} is not contained in the option
|
||
@code{ecb-layout-always-operate-in-edit-window}! Besides this (e.g.
|
||
called for a window in another frame than the @code{ecb-frame}) it
|
||
behaves like the original version.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command split-window-horizontally
|
||
Around-advice @code{ecb}: The ECB-version of
|
||
@code{split-window-horizontally}. Works exactly like the original
|
||
function with the following ECB-adjustment:
|
||
|
||
If called in any other window of the current ECB-layout it stops with
|
||
an error if this @code{split-window-horizontally} is not contained in
|
||
the option @code{ecb-layout-always-operate-in-edit-window}!
|
||
@end deffn
|
||
|
||
@deffn Command split-window-vertically
|
||
Around-advice @code{ecb}: The ECB-version of
|
||
@code{split-window-vertically}. Works exactly like the original
|
||
function with the following ECB-adjustment:
|
||
|
||
If called in any other window of the current ECB-layout it stops with
|
||
an error if this @code{split-window-vertically} is not contained in
|
||
the option @code{ecb-layout-always-operate-in-edit-window}!
|
||
@end deffn
|
||
|
||
|
||
@deffn Command display-buffer BUFFER &optional NOT-THIS-WINDOW FRAME
|
||
Around-advice @code{ecb}: Makes this function compatible with ECB if
|
||
called in or for the ecb-frame. It displays all buffers which are
|
||
``compilation-buffers'' in the sense of
|
||
@code{ecb-compilation-buffer-p} in the compile-window of ECB. If the
|
||
compile-window is temporally hidden then it will be displayed first.
|
||
|
||
If there is no compile-window (@code{ecb-compile-window-height} is
|
||
nil) then it splits the edit-window if unsplitted and displays BUFFER
|
||
in another edit-window but only if @code{pop-up-windows} is not nil
|
||
(otherwise the edit-window will not be splitted).
|
||
|
||
All buffers which are not ``compilation-buffers'' in the sense of
|
||
@code{ecb-compilation-buffer-p} will be displayed in one of the
|
||
edit-area and @code{display-buffer} behaves as if the edit-windows
|
||
would be the only windows in the frame.
|
||
|
||
If BUFFER is contained in @code{special-display-buffer-names} or
|
||
matches @code{special-display-regexps} then
|
||
@code{special-display-function} will be called (if not nil). But this
|
||
behavior depends on the value of the option
|
||
@code{ecb-ignore-special-display}. The values of
|
||
@code{same-window-buffer-names} and @code{same-window-regexps} are
|
||
supported as well.
|
||
|
||
See the option @code{ecb-ignore-display-buffer-function}!
|
||
|
||
If called for other frames it works like the original version.
|
||
@end deffn
|
||
|
||
@deffn Command switch-to-buffer BUFFER &optional NORECORD
|
||
Around-advice @code{ecb}: The ECB-version of @code{switch-to-buffer}.
|
||
Works exactly like the original but with the following enhancements
|
||
for ECB:
|
||
|
||
``compilation-buffers'' in the sense of
|
||
@code{ecb-compilation-buffer-p} will be displayed always in the
|
||
compile-window of ECB (if @code{ecb-compile-window-height} is not nil)
|
||
- if the compile-window is temporally hidden then it will be displayed
|
||
first. If you do not want this you have to modify the options
|
||
@code{ecb-compilation-buffer-names},
|
||
@code{ecb-compilation-major-modes} or
|
||
@code{ecb-compilation-predicates}.
|
||
|
||
If called for non ``compilation-buffers'' (s.a.) from outside the
|
||
edit-area of ECB it behaves as if called from an edit-window if
|
||
@code{switch-to-buffer} is contained in the option
|
||
@code{ecb-layout-always-operate-in-edit-window}. Otherwise an error is
|
||
reported.
|
||
@end deffn
|
||
|
||
@deffn Command switch-to-buffer-other-window BUFFER &optional FRAME
|
||
Around-advice @code{ecb}: The ECB-version of
|
||
@code{switch-to-buffer-other-window}. Works exactly like the original
|
||
but with some adaptions for ECB so this function works in a
|
||
``natural'' way:
|
||
|
||
If called in any special ecb-window of the current ECB-layout then it
|
||
goes always to an edit-window (which one depends on the setting in
|
||
@code{ecb-mouse-click-destination}) and then goes on as if called from
|
||
this edit-window.
|
||
|
||
If a compile-window is used (i.e. @code{ecb-compile-window-height} is
|
||
not nil) then ``compilation-buffers'' in the sense of
|
||
@code{ecb-compilation-buffer-p} are always displayed in the
|
||
compile-window. If the compile-window is temporally hidden then it
|
||
will be displayed first. If no compile-window is used it behaves like
|
||
the original.
|
||
|
||
If called from within the compile-window then ``compilation-buffers''
|
||
will be displayed still there and all other buffers are displayed in
|
||
one of the edit-windows - if the destination-buffer is already
|
||
displayed in one of the edit-windows then this one is used otherwise
|
||
it behaves like the original.
|
||
|
||
If called within an edit-window it behaves like the original function
|
||
except for compilation-buffers (if a compile-window is used, see
|
||
above).
|
||
@end deffn
|
||
|
||
|
||
@deffn Function other-window-for-scrolling
|
||
Around-advice @code{ecb}: This function determines the window which is
|
||
scrolled if any of the ``other-window-scrolling-functions'' is called
|
||
(e.g. @code{scroll-other-window}):
|
||
|
||
If the option @code{ecb-scroll-other-window-scrolls-compile-window} is
|
||
not nil (maybe set by
|
||
@code{ecb-toggle-scroll-other-window-scrolls-compile}) and a
|
||
compile-window is visible then always the current buffer in the
|
||
compile-window is scrolled!
|
||
|
||
Otherwise it depends completely on the setting in
|
||
@code{ecb-other-window-behavior}.
|
||
@end deffn
|
||
|
||
@deffn Command balance-windows
|
||
Around-advice @code{ecb}: When called in the @code{ecb-frame} then
|
||
only the edit-windows are balanced.
|
||
@end deffn
|
||
|
||
@node Temp- and compile-buffers, The other window, The edit-area, Usage of ECB
|
||
@section Temp- and compile-buffers display in ECB
|
||
|
||
@cindex temporary buffers
|
||
@cindex help buffers
|
||
@cindex compilation buffers
|
||
@cindex grep buffers
|
||
If you call any help in Emacs, e.g. by calling @code{describe-function}, or
|
||
if you do a completion in the minibuffer, then Emacs displays the
|
||
result-buffer in another window. This behavior you have also in ECB.
|
||
|
||
@subsection Standard Emacs behavior
|
||
|
||
@subsubsection Gnu Emacs 21.x, 22.x and XEmacs 21.4:
|
||
|
||
If the edit-area is already splitted into at least two edit-windows then the
|
||
temp-buffer is displayed in another edit-window otherwise the edit-area will
|
||
be splitted first vertically into two edit-windows, one above the other. The
|
||
variables @code{temp-buffer-max-height} and @code{temp-buffer-resize-mode}
|
||
(for GNU Emacs) and @code{temp-buffer-shrink-to-fit} (for XEmacs) work also
|
||
correctly with ECB.
|
||
|
||
Same for all completion-buffer and ``compile''-like output-buffers (e.g. after
|
||
a @code{compile} or @code{grep}) and the variable
|
||
@code{compilation-window-height}@footnote{It goes without saying that is is
|
||
also true for @code{grep-window-height} and all other ``compile''-modes.}.
|
||
|
||
@subsubsection Gnu Emacs 23.x
|
||
|
||
Gnu Emacs 23 has a much smarter window-manager for displaying temporary
|
||
buffers (like help-buffers) and ``compile''-buffers (like real compilation
|
||
outputs but also grep-outputs, completions etc.). Therefore ECB uses
|
||
completely the logic of Emacs 23 and does exactly what Emacs 23 would do
|
||
without activated ECB: This means mainly that the split-behavior depends on
|
||
the settings of the options @code{split-width-threshold} and
|
||
@code{split-height-threshold}.
|
||
|
||
@strong{Please note}: If you are wondering why displaying temporary-buffers
|
||
(like help, compile, grep, completion etc.) shows different behavior compared
|
||
to deactivated ECB, then you probably have to adjust the values of the options
|
||
@code{split-width-threshold} and @code{split-height-threshold} to the sizes of
|
||
the edit-area of ECB (at least nearly).
|
||
|
||
|
||
This is default behavior of ECB. But there is also another way to
|
||
display such buffers: Using a persistent extra window at the bottom of
|
||
the ECB-frame, named the ``compile-window'':
|
||
|
||
@subsection Using a persistent compile window
|
||
|
||
With the option @code{ecb-compile-window-height} you can define if the
|
||
ECB layout should contain per default a compile-window at the
|
||
bottom (just specify the number of lines which should be used for the
|
||
compile-window at the bottom of the frame). If ``yes'' ECB displays
|
||
all buffers for which the function @code{ecb-compilation-buffer-p}
|
||
returns not nil (e.g. all output of compilation-mode (compile, grep
|
||
etc.) or all temp-buffers like *Help*-buffers) in this special
|
||
window.
|
||
|
||
In general: With the options @code{ecb-compilation-buffer-names},
|
||
@code{ecb-compilation-major-modes} and
|
||
@code{ecb-compilation-predicates} you can define which buffers should
|
||
be displayed in the compile-window of ECB (for example if you call
|
||
@code{switch-to-buffer} or @code{display-buffer} or if you run
|
||
@code{compile} or if you display *Help*-buffers). Per default these
|
||
are all temp-buffers like *Help*-buffers, all compile- and grep
|
||
buffers, *Occur*-buffers etc. See the default values of these options.
|
||
|
||
With the command @code{ecb-toggle-compile-window} (bound to @kbd{C-c .
|
||
\}) you can toggle the visibility of the compile-window
|
||
(@pxref{Interactive ECB commands}).
|
||
|
||
There are some more useful options and commands related to the
|
||
compile-window of ECB (to see all options for the compile-window see
|
||
the customization group @ref{ecb-compilation}):
|
||
|
||
@itemize @bullet
|
||
@item
|
||
With the option @code{ecb-compile-window-temporally-enlarge} you can
|
||
allow Emacs to enlarge temporally the ECB-compile-window in some
|
||
situations. Please read the comment of this option. See also the
|
||
description of the command
|
||
@code{ecb-toggle-compile-window-height}.
|
||
|
||
@item
|
||
With the option @code{ecb-enlarged-compilation-window-max-height} you
|
||
specify how @code{ecb-toggle-compile-window-height} should
|
||
enlarge the compile-window.
|
||
|
||
@item
|
||
With the command @code{ecb-cycle-through-compilation-buffers}
|
||
(@pxref{Interactive ECB commands}) you can cycle through all current
|
||
open compilation-buffers (in the sense of
|
||
@code{ecb-compilation-buffer-p}) very fast.
|
||
@end itemize
|
||
|
||
ECB offers the same compile-window functionality regardless if the
|
||
ECB-window are hidden or not. The state of the compile-window will be
|
||
preserved when toggling the ecb-windows or when maximizing one
|
||
ecb-windows! So you have the advantage of one special window for all
|
||
help-, grep or compile-output (see above) also when the ecb-windows
|
||
are hidden - a window which will not be deleted if you call
|
||
@code{delete-other-windows} (bound to @kbd{C-x 1}) for one of the
|
||
edit-windows. In general: All features of the compile-window work with
|
||
hidden ecb-windows exactly as when the ecb-windows are visible.
|
||
|
||
|
||
@anchor{Problems with the compile window}
|
||
@subsection What to do if there are problems with the compile-window
|
||
|
||
Normally displaying temp- and compilation-buffers (or more general:
|
||
displaying buffer for which @code{ecb-compilation-buffer-p} is not
|
||
nil) should work reliable. But if there are problems which you can not
|
||
handle with the options @code{ecb-compilation-buffer-names},
|
||
@code{ecb-compilation-major-modes} or
|
||
@code{ecb-compilation-predicates} then please go on like follows:
|
||
|
||
@enumerate
|
||
@item
|
||
Set the option @code{ecb-layout-debug-mode} to not nil.
|
||
|
||
@item
|
||
Reproduce the wrong behavior exactly by repeating all the operations
|
||
which lead to the problem. If possible then restart Emacs before
|
||
reproducing the problem so you can begin from the beginning!
|
||
|
||
@item
|
||
Now send immediately a bug report with
|
||
@code{ecb-submit-problem-report}.
|
||
|
||
@item
|
||
Set @code{ecb-layout-debug-mode} back to nil if you do not want
|
||
further debugging output in the *Messages* buffer"
|
||
@end enumerate
|
||
|
||
@anchor{Using special-display with ECB}
|
||
@cindex special-display
|
||
@subsection Handling special-display-buffers
|
||
|
||
Emacs offers three options for a special-display-handling of certain
|
||
buffers: @code{special-display-function},
|
||
@code{special-display-buffer-names} and
|
||
@code{special-display-regexps} (see the Emacs manual for a description
|
||
of these options). ECB offers an option
|
||
@code{ecb-ignore-special-display} for specification in which
|
||
situations ECB should take account for the values of these
|
||
special-display-options.
|
||
|
||
Default-behavior of ECB is to ignore these special-display-options
|
||
when a persistent compile-window is active (i.e.
|
||
@code{ecb-compile-window-height} is not nil). But with
|
||
@code{ecb-ignore-special-display} you can tell ECB, that either always
|
||
the special-display-options should be ignored as long as ECB is active
|
||
or that they should be never igored regardless if a persistent
|
||
compile-window is set or not. In the latter case using
|
||
@code{display-buffer} or @code{pop-to-buffer} takes always account for
|
||
the values of these options - like the original behavior of Emacs.
|
||
|
||
@node The other window, The Methods window, Temp- and compile-buffers, Usage of ECB
|
||
@section How the ``other window'' is determined by ECB
|
||
|
||
@cindex other window
|
||
Normally all windows in an Emacs-frame are arranged in a cyclic order
|
||
and window-selecting-commands like @code{other-window} or
|
||
window-scrolling-commands like @code{scroll-other-window} choose
|
||
simply the next@footnote{@code{other-window} allows to select ARG'th
|
||
different window, i.e. the window ARG steps away from current window
|
||
in the cyclic order of the windows} window after the current window as
|
||
``other window''.
|
||
|
||
@subsection ``Other window''-basics in ECB
|
||
|
||
With a typical window-layout of ECB such a cyclic order of
|
||
@strong{all} windows in the ECB-frame does not make sense because it
|
||
would be not very intuitive and against that what the user wants to
|
||
``say'' when calling @code{other-window} or
|
||
@code{scroll-other-window}.
|
||
|
||
Therefore ECB divides the whole set of windows of the ECB-frame in
|
||
several subsets:
|
||
|
||
@itemize @bullet
|
||
@item The edit-windows of the edit-area
|
||
@item The special tree-windows for browsing-tasks
|
||
@item The compile-window at the bottom (if there is one)
|
||
@item The minibuffer-window of the ECB-frame (if active)
|
||
@end itemize
|
||
|
||
Each of these subsets will be treated as a cyclic ordered subset, i.e.
|
||
all windows in each of these subsets are ordered as the function
|
||
@code{walk-windows} would visit the windows when the windows of a
|
||
subset would be the only windows of a
|
||
frame@footnote{@code{other-window} uses the same window-ordering as
|
||
@code{walk-windows}}.
|
||
|
||
@subsection Builtin ``other window'' behaviors of ECB
|
||
|
||
ECB now offers to specify the behavior of commands like
|
||
@code{other-window} or @code{scroll-other-window} within the
|
||
ECB-frame. This can be done with the option
|
||
@code{ecb-other-window-behavior}. This option offers several builtin
|
||
behaviors:
|
||
|
||
@itemize @bullet
|
||
@item All windows of the ECB-frame are considered
|
||
|
||
ECB will cycle through all windows of the ECB-frame or scroll simply
|
||
the next window in the ECB-frame, means it behaves like the original
|
||
@code{other-window} rsp. the original
|
||
@code{other-window-for-scrolling}.
|
||
|
||
@item Only the windows of the edit-area are considered
|
||
|
||
ECB will only cycle through the edit-windows of ECB or only scroll
|
||
another edit-window. If the selected window is not an edit-window then
|
||
all windows are taken into account.
|
||
|
||
@item The edit-windows and the compile-window are considered
|
||
|
||
Like above but the compile-window will be added to the subset of the
|
||
edit-windows.
|
||
|
||
@item Behave as smart and intuitive as possible
|
||
|
||
This is the default behavior of ECB. ECB tries to choose the
|
||
@code{other-window}-destination or the ``other window'' to scroll in a
|
||
smart and intuitive way: If point is in one of the edit-windows and if
|
||
the edit-area is splitted then always the ``next'' edit-window is
|
||
choosen (whereas the next edit-window of the last edit-window is the
|
||
first edit-window)- if the edit-area is unsplitted then the
|
||
compile-window is used if there is one. In the context of an
|
||
@code{other-window}-call the @var{ARG} of @code{other-window} will be
|
||
taken into account.
|
||
|
||
If one of the special ecb-windows is selected then always the ``next''
|
||
ecb-window is choosen (whereas the next ecb-window of the last
|
||
ecb-window is the first ecb-window). In the context of an
|
||
@code{other-window}-call the @var{ARG} of @code{other-window} will be
|
||
taken into account. If there is only one ecb-window then ECB considers
|
||
also the edit-windows.
|
||
|
||
If the compile-window is selected then always the last edit-window
|
||
which had the point will be used unless @code{other-window} has been
|
||
called with a prefix-argument unequal 1.
|
||
@end itemize
|
||
|
||
Regardless of the different behaviors above ECB handles the situation
|
||
of an active minibuffer during a call to @code{other-window} or
|
||
@code{scroll-other-window} like follows:
|
||
|
||
If the minibuffer-window is selected then ECB always chooses the
|
||
window @code{minibuffer-scroll-window} points to (when this variable
|
||
is set, otherwise the compile-window or the last selected edit-window
|
||
is choosen) when the called command is called to choose the 1. next
|
||
window (always true for scrolling another window or true when
|
||
@code{other-window} called without prefix-arg or with prefix-arg equal
|
||
1). Otherwise the window ARG steps away is choosen (in case of
|
||
@code{other-window}).
|
||
|
||
If there is an active minibuffer but the minibuffer-window is not
|
||
selected then @code{other-window} and @code{scroll-other-window}
|
||
behave like the original version.
|
||
|
||
@subsection User-defined ``other window'' behavior
|
||
|
||
In addition to the builtin ``other window'' behaviors ECB offers a
|
||
user to completely define for himself how ECB should choose another
|
||
window for scrolling it or selecting it. This can be done with the
|
||
option @code{ecb-other-window-behavior} too because this option can
|
||
also have a function-symbol as value:
|
||
|
||
Such a function gets seven arguments:
|
||
@enumerate
|
||
@item
|
||
A canonical list of all currently visible windows of the
|
||
@code{ecb-frame}
|
||
@item
|
||
A canonical list of all currently visible edit-windows
|
||
@item
|
||
A canonical list of all currently visible ecb-windows
|
||
@item
|
||
The window-object of the compile-window if there is any.
|
||
@item
|
||
The minibuffer-window of the ECB-frame if there is an active
|
||
minibuffer.
|
||
@item
|
||
The result of the function @code{ecb-where-is-point} - see the
|
||
documentation of this function for details.
|
||
@item
|
||
An integer which indicates how many steps away from the current
|
||
selected window the ``other-window'' is. Is nil when this function is
|
||
called in another context than for @code{other-window}.
|
||
@end enumerate
|
||
|
||
The function has to return a window-object which is then used as
|
||
``other window'' for the command @code{other-window} or for scrolling
|
||
another window (e.g. with @code{scroll-other-window}). Such a function
|
||
has to handle properly all situation for itself.
|
||
|
||
Here is an example for such a function:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-get-other-window-smart (win-list
|
||
edit-win-list
|
||
ecb-win-list
|
||
comp-win
|
||
minibuf-win
|
||
point-loc
|
||
nth-window)
|
||
"Implements the smart-setting of `ecb-other-window-behavior'."
|
||
(if minibuf-win
|
||
;; if we have an active mini-buffer we delegate this to
|
||
;; `ecb-get-other-window-minibuf-active'
|
||
(ecb-get-other-window-minibuf-active win-list
|
||
edit-win-list
|
||
ecb-win-list
|
||
comp-win
|
||
minibuf-win
|
||
point-loc
|
||
nth-window)
|
||
;; here we have no active minibuffer!
|
||
(let ((nth-win (or nth-window 1)))
|
||
(cond ((equal point-loc 'ecb)
|
||
(ecb-next-listelem ecb-win-list (selected-window) nth-win))
|
||
((equal point-loc 'compile)
|
||
(if (= nth-win 1)
|
||
(or (and ecb-last-edit-window-with-point
|
||
(window-live-p ecb-last-edit-window-with-point)
|
||
ecb-last-edit-window-with-point)
|
||
(car edit-win-list))
|
||
(ecb-next-listelem (append edit-win-list
|
||
(list (selected-window)))
|
||
(selected-window)
|
||
nth-win)))
|
||
(t ;; must be an edit-window
|
||
(ecb-next-listelem (append edit-win-list
|
||
(if (and comp-win
|
||
(= (length edit-win-list)
|
||
1))
|
||
(list comp-win)))
|
||
(selected-window)
|
||
nth-win))))))
|
||
@end group
|
||
@end example
|
||
|
||
This example implements the builtin smart behavior described above.
|
||
|
||
@node The Methods window, Filtering the tree-buffers, The other window, Usage of ECB
|
||
@section Using and customizing the ECB-Methods window
|
||
|
||
ECB is mostly designed to display parsing information for files
|
||
supported by semantic. But beginning with version 1.94 it also
|
||
supports other parsing engines like imenu and etags, so also files not
|
||
supported by semantic but by imenu/etags can be displayed in the
|
||
Method-buffer of ECB. Therefore we have to introduce some terminology:
|
||
|
||
@cindex semantic-sources
|
||
@anchor{Definition of semantic- and non-semantic-sources}
|
||
@itemize @minus
|
||
@item @dfn{semantic-sources}:
|
||
These are file-types for which a semantic grammar is available, so the
|
||
files are parse-able by semantic. These sources are supported best by
|
||
ECB and most of the following options and descriptions are related to
|
||
these file-types. Examples are programming-sources like C++, C, Java,
|
||
Emacs-Lisp and Texinfo-file and some more.
|
||
|
||
@cindex non-semantic-sources
|
||
@item @dfn{non-semantic-sources}:
|
||
For these files there is no semantic-grammar available so they can not
|
||
be parsed by semantic. Examples are Perl-, LaTeX- and TeX-files. But
|
||
for many of these files imenu and/or etags parsers exist. ECB supports
|
||
now parsing and displaying these file-types too and it uses for this
|
||
some speedbar-logic.
|
||
@end itemize
|
||
|
||
This chapter describes how to use and customize the Methods-buffer of
|
||
ECB.
|
||
|
||
@menu
|
||
* Visiting tags:: Possible actions after visiting a tag
|
||
* Expanding:: Explicit and automatic expanding
|
||
* Customizing the display:: How to customize the Methods-buffer display
|
||
* Updating Methods-window:: Updating Methods with contents of current buffer
|
||
* Updating for ind. buffers:: Updating Methods for indirect buffers
|
||
* Jumping to external tags:: Jumping to the definition of external types
|
||
@end menu
|
||
|
||
@node Visiting tags, Expanding, The Methods window, The Methods window
|
||
@subsection Possible actions after visiting a tag
|
||
|
||
You visit a tag by clicking with either the primary oder secondary
|
||
mouse-button (or by hitting @kbd{RET} or @kbd{C-RET} if using the
|
||
keyboard) onto a node in the Methods-tree-buffer of ECB. This simply
|
||
selects the ``right'' edit-window (depends if clicked with the primary
|
||
or secondary button, in how many windows the edit-area is splitted and
|
||
the value of @code{ecb-mouse-click-destination}) and puts the point
|
||
onto the first line of the clicked tag.
|
||
|
||
But you can define if after this ``basic'' tag-visit-action more
|
||
additional actions should be performed by ECB. You can either use some
|
||
of the predefined actions (e.g. highlighting the header-line of the
|
||
tag) or define own actions. You can set different actions for
|
||
different major-modes. All this is done via the option
|
||
@code{ecb-tag-visit-post-actions}.
|
||
|
||
The following actions are currently predefined:
|
||
@itemize @minus
|
||
@item @code{ecb-tag-visit-highlight-tag-header}
|
||
@item @code{ecb-tag-visit-smart-tag-start}
|
||
@item @code{ecb-tag-visit-recenter}
|
||
@item @code{ecb-tag-visit-recenter-top}
|
||
@item @code{ecb-tag-visit-goto-doc-start}
|
||
@item @code{ecb-tag-visit-narrow-tag}
|
||
@end itemize
|
||
|
||
See the documentation of these function for details what they do.
|
||
|
||
Per default ECB performs the actions
|
||
@code{ecb-tag-visit-smart-tag-start} and
|
||
@code{ecb-tag-visit-highlight-tag-header} for all major-modes.
|
||
|
||
|
||
@node Expanding, Customizing the display, Visiting tags, The Methods window
|
||
@subsection Explicit and automatic expanding of the ECB-methods-buffer
|
||
|
||
@subsubsection Explicit expanding all nodes to a certain expansion level
|
||
|
||
With the command @code{ecb-expand-methods-nodes} (bound to @kbd{C-c .
|
||
x}) you can get a fast overlook of the contents of the source-buffer,
|
||
because this command allows precisely expanding all tags with a
|
||
certain indentation-level. So you can either expand no tags (or with
|
||
other words collapse all tags) or expand all tags so see the contents
|
||
of a buffer at one glance. Or you can expand exactly that tags of a
|
||
certain indentation level.
|
||
|
||
Which node-types are expanded (rsp. collapsed) by this command
|
||
depends for semantic-sources on the options
|
||
@code{ecb-methods-nodes-expand-spec} and
|
||
@code{ecb-methods-nodes-collapse-spec}! For non-semantic-sources always
|
||
all node-types are expanded/collapsed, i.e. the two options above
|
||
takes no effect for these files.
|
||
|
||
@subsubsection Explicit expanding of the current node to a certain level
|
||
|
||
With the popup-menu of the methods-buffer an even more precise
|
||
expansion is possible because it allows not only expanding all tags
|
||
(see above) but offers in addition expanding only the current-node
|
||
(for which the menu was activated) to an exact level of expansion:
|
||
|
||
All menu-entries are label with an expansion-``level'' whereas level
|
||
specifies precisely which level of nodes should be expanded. level
|
||
means the indentation-level of the NODE itself and its (recursive)
|
||
subnodes relative to the NODE itself.
|
||
|
||
So a level value X means that all (sub)nodes with an indentation-level
|
||
<= X relative to NODE are expanded and all other are collapsed.
|
||
|
||
Examples:
|
||
|
||
@itemize @minus
|
||
@item Expand this node to level 0:
|
||
Expand only the NODE itself because it is the only node which has
|
||
indentation 0 to itself. All deeper indented nodes will be collapsed.
|
||
This is also the important difference between using this menu compared
|
||
to clicking onto the expand-symbol of the node: The latter one expands
|
||
the NODE to that expansion-state it has before the last collapsing (so
|
||
when deeper nodes has been expanded they will be expanded now to). The
|
||
former one expands exactly(!) to level 0, means expand only the node
|
||
itself and collapse all(!) its subnodes recursively(!).
|
||
|
||
@item Expand this node to level 1:
|
||
Expand the NODE itself and all of its direct subnodes - because only
|
||
the direct subnodes of NODE have indentation-level 1 relativ to NODE.
|
||
All deeper nodes will be collapsed.
|
||
|
||
@item Collapse this node completely:
|
||
Collapses the current node recursively, means collapse not only the
|
||
node itself but also its subnodes, the subnodes of the subnodes and so
|
||
on! This is very differnt from clicking onto the collapse symbol
|
||
because this action only collapses the node itself but preserves the
|
||
expansion-state of all its subnodes!
|
||
|
||
@end itemize
|
||
|
||
Expanding the current node with the popup-menu ignores the settings in
|
||
the options @code{ecb-methods-nodes-expand-spec} and
|
||
@code{ecb-methods-nodes-collapse-spec}!
|
||
|
||
@subsubsection Automatic expansion ot tags after buffer-parsing
|
||
|
||
With the option @code{ecb-show-tags} you tell ECB how to display tags
|
||
of a certain tag-class (@pxref{Customizing the display}). Among other
|
||
things you can tell ECB that a certain tag-class should be combined
|
||
under an expanded or collapsed bucket-node. But such a setting defines
|
||
the expansion-state of such a bucket-node only direct afterwards the
|
||
buffer has been (re)parsed, which can occur after opening a file,
|
||
after autom. reparsing the buffer via semantic or after manually
|
||
rebuilding the methods-buffer of ECB.
|
||
|
||
The tag-class @code{type} (classes, interfaces, enumerations etc.) is
|
||
divided into several subtypes by semantic. The subtypes are strings
|
||
which names exactly if the tag with tag-class @code{type} is a class,
|
||
an interface, an enumeration, a typedef etc. With the option
|
||
@code{ecb-type-tag-expansion} you can tell ECB if these type-tags
|
||
should be autom. expanded after (reparsing) a buffer (see above) or if
|
||
they should be displayed collapsed - so all its members (methods,
|
||
variables etc.) are hidden.
|
||
|
||
@subsubsection Automatic expanding the ECB-methods-buffer for current tag
|
||
|
||
If the option @code{ecb-highlight-tag-with-point} is switched on, then
|
||
always that node in the method-buffer is highlighted which belongs to
|
||
the current semantic-tag under point in the current active
|
||
edit-window. But if this node is invisible (probably because its
|
||
parent node is collapsed) then no node is highlighted if the auto.
|
||
expanding feature is switched off.
|
||
|
||
You can either switch on this feature with the option
|
||
@code{ecb-auto-expand-tag-tree} or even easier with the command
|
||
@code{ecb-toggle-auto-expand-tag-tree}.
|
||
|
||
There is another option
|
||
@code{ecb-expand-methods-switch-off-auto-expand} which makes both
|
||
explicit and auto. expanding best working together. See the
|
||
documentation of this option to get the details.
|
||
|
||
The autom. expanding feature is only available for semantic-sources!
|
||
|
||
Previous versions of ECB have always fully expanded the whole tree in
|
||
the Methods-buffer if the current tag in the source-buffer was not
|
||
visible in the current tree - e.g. because the variables-bucket was
|
||
collapsed or the containing type of a tag (e.g. the class of a method)
|
||
was collapsed. So in most cases much more was expanded as needed to
|
||
make the current tag visible.
|
||
|
||
The mechanism of ECB 2.22 and higher only expands the needed parts of
|
||
the tree-buffer to make the related node visible: First we try to
|
||
highlight the current tag with current expansion-state of the
|
||
Methods-buffer. If the node is not visible so the tag can not be
|
||
highlighted then we go upstairs the ladder of type-tags the current
|
||
tag belongs to (e.g. we expand successive the nodes of the whole
|
||
class-hierachy of the current method-tag until the related node
|
||
becomes visible). If there is no containing type for the current tag
|
||
then the node of the tag is probably contained in a toplevel-bucket
|
||
which is currently collapsed; in this case we expand only this
|
||
bucket-node and try highlighting again. Only if this has still no
|
||
success then we expand the full tree-buffer and try to highlight the
|
||
current tag.
|
||
|
||
There is another option
|
||
@code{ecb-auto-expand-tag-tree-collapse-other}: If this option is set
|
||
then auto. expanding the tag-tree collapses all not related nodes.
|
||
This means that all nodes which have no relevance for the currently
|
||
highlighted node will be collapsed, because they are not necessary to
|
||
make the highlighted node visible. This feature is switched off by
|
||
default because if always collapses the complete Methods-tree before
|
||
the following highlighting of the node for the current tag expands the
|
||
needed parts of the tree-buffer.
|
||
|
||
|
||
@node Customizing the display, Updating Methods-window, Expanding, The Methods window
|
||
@subsection Customizing the display of the Methods-buffer
|
||
|
||
@cindex semantic tag
|
||
@cindex tag
|
||
The ECB-Methods buffer is probably the most important browsing window
|
||
offered by ECB. It displays all parsing informations of the current
|
||
source-buffer (the buffer displayed in the current active
|
||
edit-window).
|
||
|
||
Normally ECB gets all informations displayed in this Methods-buffer from the
|
||
semantic-library - at least for semantic-sources. This library parses auto.
|
||
the current source-buffer in the edit-window of ECB and returns all
|
||
information in form of @dfn{tags} to ECB which displays them in a browse-able
|
||
form in its Method-buffer. See @ref{ECB Methods-window} for information how to
|
||
use the Methods-buffer.
|
||
|
||
There are several options to customize which tags ECB should display
|
||
in general, if the tags should be collapsed or expanded, how to
|
||
fontify them (i.e. syntax-highlighting) and something more.
|
||
|
||
@table @code
|
||
@item ecb-show-tags
|
||
With the option @code{ecb-show-tags} you specify how ECB should
|
||
display the tags returned by the semantic parser. Semantic divides its
|
||
tags in several so called @dfn{tag classes}. A tag-class is always a
|
||
symbol and can be for example @code{type} (tags which represent a
|
||
class@footnote{Do not confuse the term ``class'' in the context of a
|
||
tag, which means the class of the tag and which is a semantic-term and
|
||
a ``class'' in the context of an object oriented language like Java or
|
||
C++! Normally the surrounding context sould be sufficient to
|
||
understand which type of ``class'' is meant whenever the term
|
||
``class'' is used in this manual.}, a interface, an enumeration etc.),
|
||
@code{function} (tags which represent function or methods),
|
||
@code{variable} (variables and attributes), @code{include}
|
||
(import-statements) etc. There is no predefined superset of allowed
|
||
tag-class-symbols because each language-parser can define its own
|
||
tag-classes. But to get an overview of the most common tag-classes see
|
||
the default value of the option @code{ecb-show-tags}.
|
||
|
||
With the option @code{ecb-show-tags} you can now specify how ECB
|
||
should display tags of a certain tag-class in a certain major-mode.
|
||
You can tell ECB that all tags of a tag-class @code{X} should be
|
||
displayed in an expanded bucket and all tags of a tag-class @code{Y}
|
||
should be displayed in a collapsed bucket and all tags of a tag-class
|
||
@code{Z} should be displayed flattened (means not contained in a
|
||
expandable/collapsable bucket-node). These settings can be made
|
||
separately for each major-mode but you can also define a
|
||
default-display which takes effect when for a major-mode no special
|
||
setting can be found in @code{ecb-show-tags}.
|
||
|
||
For every tag-class you can tell ECB how the tags should be sorted.
|
||
|
||
@item ecb-font-lock-tags
|
||
@itemx ecb-type-tag-display
|
||
How to fontify the tags in the Method-buffer
|
||
|
||
@item ecb-tag-display-function
|
||
ECB and semantic offer several predefined functions for displaying the
|
||
tags. Here you can customize, what informations tags should
|
||
contain (only the method-name or the whole signature or something
|
||
else) and what notation should be used, e.g. UML or not.
|
||
|
||
@end table
|
||
|
||
These are the most important options for this topic but it is
|
||
recommended to have a look into the customize-group @code{ecb-methods}
|
||
(@pxref{ecb-methods}) and check all the options offered there!
|
||
|
||
All these options are only relevant for semantic-sources and take no
|
||
effect for non-semantic-sources!
|
||
|
||
XXXXX
|
||
|
||
@node Updating Methods-window, Updating for ind. buffers, Customizing the display, The Methods window
|
||
@subsection Updating the Methods-window with contents of current source-buffer
|
||
|
||
First a preliminary remark: Do not confuse this chapter with that
|
||
synchronizing described in @ref{ECB-window synchronizing}. The latter one
|
||
describes the mechanism for synchronizing the ECB-windows when the
|
||
current-buffer in the edit-area has been changed. This chapter describes how
|
||
to update the ECB-methods-window with the contents of the current-buffer
|
||
if the buffer has been modified!
|
||
|
||
@subsubsection The short version
|
||
|
||
In almost all cases there is @strong{NO} need to manually rebuild the
|
||
method-buffer, because it is always done automatically if necessary;
|
||
the mechanism depends on the sources:
|
||
|
||
@itemize @minus
|
||
@item semantic-sources:
|
||
The command @code{global-semantic-idle-scheduler-mode} switches on autom.
|
||
reparsing of semantic-sources. All the rest will be done by semantic and ECB
|
||
automatically. ECB and semantic always try to reparse and update as less as
|
||
possible of the sourcecode-buffer.
|
||
|
||
@item non-semantic-sources (imenu supported):
|
||
You can switch on autom. rescanning/reparsing with the option
|
||
@code{imenu-auto-rescan}. But nevertheless you have to manually
|
||
rebuild the Method-buffer (with the autom. updated imenu-tags) via the
|
||
command @code{ecb-rebuild-methods-buffer} (bound to @kbd{C-c . r}).
|
||
|
||
@item non-semantic-sources (etags supported):
|
||
For these sources there is no built-in auto-rescan mechanism, because
|
||
etags is an external tool it can only operate on the saved
|
||
file-contents. So rescanning the buffer contents would need to save
|
||
the buffer before. Therefore there is no built-in auto-rescan mechanism
|
||
because this would always result in saving the buffer and running an
|
||
external tool. But of course you can program such a an
|
||
etags-auto-rescan mechanism for yourself!
|
||
@end itemize
|
||
|
||
@subsubsection The full and long story
|
||
|
||
Generally ECB calls semantic to get the list of tags for current source-file
|
||
of current edit-window. Per default ECB does never automatically force a
|
||
reparse of the source-file after this has been changed - this is only done on
|
||
demand by calling the command @code{ecb-rebuild-methods-buffer}. So per
|
||
default the idle-scheduler of semantic is responsible for reparsing the
|
||
source-file when this is necessary (see `semantic-idle-scheduler-mode' for
|
||
further details). So this scheduler is also responsible when
|
||
updating/sychronizing the methods-window with current buffer-contents. This is
|
||
the most user-resonsible and therefore the recommended approach.
|
||
|
||
ECB is responsible to update the methods-window after the idle scheduler of
|
||
semantic has triggered either a full or partial reparse of the source-buffer.
|
||
Semantic always tries to reparse as less tags of the buffer as possible, often
|
||
just the edited section (if it has no sideeffect to tags outside the edited
|
||
parts). ECB handles this partial reparse output smoothly and updates only
|
||
these nodes which are releated to the reparsed tags.
|
||
|
||
The main effect a user will notice is that edit actions which trigger just a
|
||
partial reparse will just update the related node in the methods-window and
|
||
not the whole methods-window. One of the main advantages is that this
|
||
preserves the expand/collapse state of the methods-window.
|
||
|
||
Editing examples which trigger only a partial reparse:
|
||
@itemize
|
||
@item editing a function- or method-body
|
||
@item changing the name of a variable or function/method
|
||
@item modifying the return-type of a function/method
|
||
@item and some other...
|
||
@end itemize
|
||
|
||
In these cases only the related node in the methods-window will change
|
||
nothing else, ie. the expand/collapse-states of all other nodes in the
|
||
methods-window will not be changed.
|
||
|
||
@strong{Summary}: It's strongly recommended to enable
|
||
@code{semantic-idle-scheduler-mode} or
|
||
@code{global-semantic-idle-scheduler-mode} (@pxref{Setting up CEDET/semantic})
|
||
because then reparsing is always done during idle-time of Emacs and - maybe
|
||
even more important - it is also interruptable.
|
||
|
||
But if this idle-scheduler is switched off then ECB offers now two
|
||
possibilities (via @code{ecb-force-reparse-when-semantic-idle-scheduler-off}):
|
||
|
||
@itemize @bullet
|
||
|
||
@item
|
||
|
||
Not forcing itself a reparse when tags are needed by ECB: then a user declines
|
||
knowingly Emacs/semantic-driven parsing of code when he/she switches off the
|
||
idle-mode of semantic. This is the default behavior of ECB and the default
|
||
value of this option. But this has also the consequence that the
|
||
methods-buffer is only filed on demand via @code{ecb-rebuild-methods-buffer}
|
||
(bound to @key{C-c . r})!
|
||
|
||
This means also in consequence that the methods-buffer is not
|
||
automatically filled when a source-file is opened but first on demand
|
||
after calling the command @code{ecb-rebuild-methods-buffer}!
|
||
|
||
@item
|
||
|
||
Forcing a reparse when tags are needed: Then ECB forces semantic to parse
|
||
the source-file when ECB needs tags to display. For this behavior this
|
||
option has to be set to not nil.
|
||
@end itemize
|
||
|
||
The term ``forcing a reparse by semantic'' is a simplification: ECB uses then
|
||
the function @code{semantic-fetch-tags} which can decide that the cached tags
|
||
are up-to-date so no real reparsing is necessary - but it can also run a full
|
||
reparse and this reparse is not being done when Emacs is idle but immediatelly
|
||
and not interruptable (as with the idle-scheduler of semantic), which can be
|
||
quite annoying with big source-files.
|
||
|
||
To make a long story short: It is strongly recommended to enable the
|
||
@code{semantic-idle-scheduler-mode} or
|
||
@code{global-semantic-idle-scheduler-mode}! See @ref{Setting up
|
||
CEDET/semantic}. This will give you in all cases the behavior you would expect
|
||
of an IDE like ECB/semantic.
|
||
|
||
@node Updating for ind. buffers, Jumping to external tags, Updating Methods-window, The Methods window
|
||
@subsection Updating Methods for indirect buffers
|
||
|
||
ECB works out of the box with indirect buffers, especially with indirect
|
||
buffer clones created with the command @code{clone-indirect-buffer} (only
|
||
available with GNU Emacs >= 21). They will be handled as all other buffers and
|
||
you can work with them with no difference to ``normal'' buffers. With one
|
||
exception:
|
||
|
||
@strong{Please note}: Cause of a bug in Emacs 22 (and maybe also in Emacs 23)
|
||
the propagation of parsing informations from one buffer to all others which are
|
||
in an indirect-buffer relation to the same base-buffer does currently not
|
||
work.
|
||
|
||
What does this mean: If you modify a buffer then Emacs propagates this change
|
||
to all buffers with the same base-buffer. ECB/semantic recognize this change
|
||
and do all necessary to automatically reparse the changed buffer (at least if
|
||
you have customized semantic/ECB to do this). So far so good, but: If you
|
||
switch to another buffer with the same base-buffer then you will notice that
|
||
the methods-window of ECB still displays the contents before the change, ie.
|
||
the need for a reparse has not been propagated to these other buffers. This is
|
||
a bug in Emacs.
|
||
|
||
What can you do: As long as this bug is not fixed there is no chance that all
|
||
other affected ``indirect-related'' buffers will be reparsed automatically
|
||
after modifying one of them. So you have to do this reparse ``by hand'' after
|
||
switching to such an indirect-related buffer, but this is very simple: Just
|
||
call the command @code{ecb-rebuild-methods-buffer} with prefix arg or hit
|
||
@key{C-u C-c . r} (key this command is bound to).
|
||
|
||
Lets make an example:
|
||
|
||
@enumerate
|
||
|
||
@item
|
||
|
||
Suppose we have a sourcefile test.java loaded as a buffer into Emacs and
|
||
suppose further we have created two indirect-buffer clones test-clone1.java and
|
||
test-clone2.java - all of these buffers point to the same file: test.java.
|
||
|
||
@item
|
||
|
||
Now lets be the buffer test-clone1.java the current buffer and let us modify
|
||
it (e.g. adding a new method). If you have enabled the idle-reparse mechanism
|
||
of semantic (@pxref{Setting up CEDET/semantic}) then this buffer will be
|
||
reparsed automatically and ECBs methods-window will be updated in turn too.
|
||
|
||
@item
|
||
|
||
So far so good. But if you now switch to one of the two other buffers, lets
|
||
say to test.java, then you will notice that the change done in
|
||
test-clone1.java is also visible in the buffer test.java but the
|
||
ECB-methods-window for test.java will display the contents before the change.
|
||
This is cause of the Emacs-bug described above.
|
||
|
||
@item
|
||
|
||
To update the methods-window for test.java to the new contents you have to call
|
||
@code{ecb-rebuild-methods-buffer} with prefix argument (ie. clear-cache is
|
||
true) or hitting @key{C-u C-c . r}. Note: Calling this command without prefix
|
||
argument is not enough!
|
||
|
||
@end enumerate
|
||
|
||
@node Jumping to external tags, , Updating for ind. buffers, The Methods window
|
||
@subsection Jumping to the definition of external types
|
||
|
||
There are two common types of ``external'' tags displayed in the
|
||
method-window, mostly with object oriented programing-languages:
|
||
|
||
@enumerate
|
||
|
||
@item parent-types
|
||
|
||
Tags which represent the type of a parent-class (which can be defined in the
|
||
same file but which is more often defined in another file). All parents
|
||
(regardless if defined internaly or externaly) of a type will be displayed
|
||
under a bucket ``[Parents]'' in the methods-window of ECB.
|
||
|
||
@item ``virtual'' types
|
||
|
||
In OO-languages like CLOS, eieio and C++ there can be nodes with type-tags in
|
||
the method-buffer which are somehow virtual because there is no definition in
|
||
the current source-file. But such a virtual type collects all its outside
|
||
defined members like methods in C++ which are defined in the @file{*.cc} file
|
||
whereas the class-definition is defined in the associated header-file.
|
||
|
||
@end enumerate
|
||
|
||
In both cases the user wants to jump to the definition of the type if he clicks
|
||
onto the related node in the methods-window of ECB.
|
||
|
||
Here is a C++-example for ``virtual'' types (2) and parent types (1) which
|
||
explains this in detail:
|
||
|
||
Let's say this class is defined in a file @file{ParentClass.h}:
|
||
|
||
@example
|
||
@group
|
||
class ParentClass
|
||
@{
|
||
protected:
|
||
int p;
|
||
@};
|
||
@end group
|
||
@end example
|
||
|
||
Let's say this class is defined in a file @file{ClassWithExternals.h}
|
||
|
||
@example
|
||
@group
|
||
#include "ParentClass.h"
|
||
|
||
class ClassWithExternals : public ParentClass
|
||
@{
|
||
private:
|
||
int i;
|
||
|
||
public:
|
||
ClassWithExternals();
|
||
~ClassWithExternals();
|
||
@};
|
||
@end group
|
||
@end example
|
||
|
||
Both the constructor and the destructor of the class
|
||
``ClassWithExternals'' are implemented in a file
|
||
@file{ClassWithExternals.cc}:
|
||
|
||
@example
|
||
@group
|
||
#include "test.h"
|
||
|
||
ClassWithExternals::ClassWithExternals(int i,
|
||
boolean b,
|
||
char c)
|
||
@{
|
||
return;
|
||
@}
|
||
|
||
void
|
||
ClassWithExternals::~ClassWithExternals()
|
||
@{
|
||
return;
|
||
@}
|
||
@end group
|
||
@end example
|
||
|
||
ECB displays the contents of @file{ClassWithExternals.cc} in its methods-buffer like
|
||
follows:
|
||
|
||
@example
|
||
@group
|
||
[-] [Includes]
|
||
`- test.h
|
||
[-] ClassWithExternals
|
||
| +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals
|
||
`- +~ClassWithExternals ():void
|
||
@end group
|
||
@end example
|
||
|
||
Both the constructor and the destructor of the class
|
||
``ClassWithExternals'' are grouped under their class-type. But this class-type
|
||
``ClassWithExternals'' is represented by a so called ``virtual'' or ``faux''
|
||
node-tag, i.e. there is no real tag in the current source-buffer for this tag.
|
||
|
||
If a user now clicks onto the node of ``ClassWithExternals'' then he wants to
|
||
jump to the right location in the right file where ``ClassWithExternals'' is
|
||
defined. ECB now uses now some smart mechanisms (see below) to do this. In
|
||
case of success (means ECB has found the definition) it opens the right file
|
||
and point will stay at beginning of the definition of the type
|
||
``ClassWithExternals''.
|
||
|
||
The contents of @file{ClassWithExternals.h} are then displayed like
|
||
follows:
|
||
|
||
@example
|
||
@group
|
||
[-] [Includes]
|
||
`- ParentClass.h
|
||
[-] ClassWithExternals:class
|
||
| [-] [Parents]
|
||
| `- ParentClass
|
||
| [-] [Variables]
|
||
| `- -i:int
|
||
| +ClassWithExternals ():ClassWithExternals
|
||
| +~ClassWithExternals ():void
|
||
`- [+] [Misc]
|
||
@end group
|
||
@end example
|
||
|
||
Now let's play it again: Now we want to go to the definition of the
|
||
parent-type ``ParentClass'' when we click onto the related node under the
|
||
bucket ``[Parents]''. Again ECB uses its smartness to jump to the definition
|
||
of the class ``ParentClass'' when you click onto the node ``ParentClass''.
|
||
|
||
Now lets explain the precondition which must be fulfilled so ECB can do its
|
||
job:
|
||
|
||
@itemize
|
||
@item Customizing the semantic analyzer for your needs
|
||
|
||
ECB itself is quite stupid concerning finding external tags. But it can use
|
||
the semantic-analyzer of the CEDET-suite (remember: The CEDET-suite is a
|
||
must-requirement of ECB, see @ref{Requirements}). But this in turn means that the
|
||
semantic-analyzer must be customized in the right way for the needs of your
|
||
programing projects. Mainly this means activating semanticdb and setting the
|
||
correct include-path etc...
|
||
|
||
@strong{Please note}: Read the related manuals of semantic and - strongly
|
||
recommended - read in addition the article ``Gentle introduction to Cedet''.
|
||
It's worth to read it! The website of CEDET contains a link, you find it here:
|
||
@ifhtml
|
||
@uref{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html}
|
||
@end ifnothtml
|
||
|
||
@item Customize the related options of ECB:
|
||
|
||
There is exactly one option you have to take into account:
|
||
@code{ecb-find-external-tag-functions}. This defines the method ECB uses to
|
||
find these external tags.
|
||
|
||
Mostly there is nothing to do because the default values should do a good job.
|
||
But if things are running bad then maybe this is the right screw for you.
|
||
|
||
Finding such external types can be very complex and there are several roads to
|
||
success. ECB uses per default methods based on the semantic-analyzer. But this
|
||
option allows to define own find-functions and tell ECB to uses them.
|
||
|
||
This functionality is set on a major-mode base, i.e. for every major-mode a
|
||
different setting can be used. ECB first performs all find-functions defined
|
||
for current major-mode (if any) anf then all find-functions defined for the
|
||
special symbol 'default (if any).
|
||
|
||
ECB offers some predefined senseful finding-functions. Currently there are:
|
||
|
||
@itemize @minus
|
||
@item @code{ecb-search-type-tag-by-semantic-analyzer}: The most powerfil one, based
|
||
on the semantic-analyzer
|
||
@item @code{ecb-search-type-tag-by-semanticdb}: A backup for the first one
|
||
@item @code{ecb-jde-show-class-source}: For major-mode @code{jde-mode} when
|
||
coding in java, uses java-mechanisms - maybe for java the best choice.
|
||
@end itemize
|
||
|
||
See the documentation of the option and also of these function for details how
|
||
they work and how to write own finding-functions.
|
||
|
||
@end itemize
|
||
|
||
@node Filtering the tree-buffers, The ECB-layout, The Methods window, Usage of ECB
|
||
@section Applying filters to the special ECB-tree-buffers
|
||
|
||
@cindex Filter
|
||
To get a fast and good overlook of the contents of a tree-buffer ECB
|
||
offers a filter-mechanism for the Directories-, Sources-, the History-
|
||
and the Methods-buffer.
|
||
|
||
@menu
|
||
* Filtering Directories:: Applying filters to the Directories-buffer
|
||
* Filtering Sources:: Applying filters to the Sources--buffer
|
||
* Filtering History:: Applying filters to the History-buffer
|
||
* Filtering Methods:: Applying filters to the Methods-buffer
|
||
@end menu
|
||
|
||
@node Filtering Directories, Filtering Sources, Filtering the tree-buffers, Filtering the tree-buffers
|
||
@subsection Applying filters to the Directories-buffer
|
||
|
||
With the option @code{ecb-excluded-directories-regexps} certain
|
||
directories can be excluded from being displayed in the
|
||
directories-browser of ECB. This can be done by defining regular
|
||
expressions. If the name of a directory matches at least one of the
|
||
regexps of this option the directory is not displayed in the
|
||
directories-tree-buffer.
|
||
|
||
The option @code{ecb-sources-exclude-cvsignore} allows to exclude
|
||
source-files from the sources-tree-buffer if their name is listed in a
|
||
so called @file{.cvsignore}-file. This option is a list of regular
|
||
expressions and if a directory-name matches at least one of these
|
||
regexps then all files listed in the @file{.cvsignore}-file of this
|
||
directory are not displayed in the sources-tree-buffer.
|
||
|
||
@node Filtering Sources, Filtering History, Filtering Directories, Filtering the tree-buffers
|
||
@subsection Applying filters to the Sources-buffer
|
||
|
||
@subsubsection Interactive Sources-filters
|
||
|
||
The command @code{ecb-sources-filter} allows to filter these
|
||
tree-buffer either by a regular expression or by an extension (e.g.
|
||
java, cc, el for java-, c++- rsp elisp-sources). This functionality is
|
||
also available via the popup-menu of the Sources-tree-buffer.
|
||
|
||
The currently applied filter is indicated in the modeline of the
|
||
related tree-buffer. Applying a new filter replaces an eventually
|
||
already applied filter.
|
||
|
||
@subsubsection Default Sources-filters
|
||
|
||
The option @code{ecb-source-file-regexps} allow to specify which
|
||
source-files should be displayed and which not. This is done on a
|
||
directory-basis, ie. for each directory-regexp the files to display
|
||
can be specified. See the documentation of this option for all
|
||
details.
|
||
|
||
In addition to this option you should also know the option
|
||
@code{ecb-sources-exclude-cvsignore} (@pxref{Filtering Directories}).
|
||
|
||
@node Filtering History, Filtering Methods, Filtering Sources, Filtering the tree-buffers
|
||
@subsection Applying filters to the History-buffer
|
||
|
||
@subsubsection Interactive History-filters
|
||
|
||
The command @code{ecb-history-filter} allows to filter these
|
||
tree-buffer either by a regular expression or by an extension (e.g.
|
||
java, cc, el for java-, c++- rsp elisp-sources). This functionality is
|
||
also available via the popup-menu of the History-tree-buffer.
|
||
|
||
The currently applied filter is indicated in the modeline of the
|
||
related tree-buffer. Applying a new filter replaces an eventually
|
||
already applied filter.
|
||
|
||
@subsubsection Default History-filters
|
||
|
||
The option @code{ecb-history-exclude-file-regexps} allows to exclude
|
||
source-files from being historized (ie. displayed in the
|
||
History-buffer). Despite the fact that the History-buffer already
|
||
excludes all non-file-buffers there can be still buffers which name
|
||
you do not wat to be displayed in the history. These are file-buffer
|
||
like @file{TAGS} or @file{semantic.cache} which store
|
||
meta-informations used by Emacs and its tools (etags, semantic etc.).
|
||
These files can be excluded via
|
||
@code{ecb-history-exclude-file-regexps}.
|
||
|
||
@node Filtering Methods, , Filtering History, Filtering the tree-buffers
|
||
@subsection Applying filters to the Methods-buffer
|
||
|
||
The commands @code{ecb-methods-filter},
|
||
@code{ecb-methods-filter-regexp},
|
||
@code{ecb-methods-filter-protection},
|
||
@code{ecb-methods-filter-tagclass},
|
||
@code{ecb-methods-filter-function},
|
||
@code{ecb-methods-filter-delete-last},
|
||
@code{ecb-methods-filter-nofilter} allows to filter the tags/nodes of
|
||
the Methods-buffer by several criterias. As for the Sources- and the
|
||
History-buffer the same functionality is also available via the
|
||
popup-menu of the Methods-buffer.
|
||
|
||
@subsubsection Possible filter-criterias
|
||
|
||
@itemize @bullet
|
||
@item Filter by protection:
|
||
Just insert the protection you want the Methods-buffer being filtered:
|
||
private, protected or public! For sources not supported by semantic
|
||
the protection filter will not be offered because these informations
|
||
are not available for such sources.
|
||
|
||
@item Filter by regexp:
|
||
Insert the filter as regular expression.
|
||
|
||
@item Filter by tag-class:
|
||
You can filter by tag-classes. The popup-menu contains mode-dependend
|
||
tag-filter entries and the command @code{ecb-methods-filter} offers
|
||
only the tag-classes of the current mode. This means for sources not
|
||
supported by semantic the tag-class filter will not be offered. And
|
||
for semantic-supported sources exactly these tag-classes are offered
|
||
the semantic-parser for the current major-mode offers. For example
|
||
texi-sources can only be filtered by the tag-classes ``Definitions''
|
||
and ``Sections'' and java-sources can be filtered by ``Methods'',
|
||
``Variables'', ``Classes'' etc. In general the semantic-variable
|
||
@code{semantic-symbol->name-assoc-list} is used to get the right
|
||
tag-classes.
|
||
|
||
@item Filter by a filter-function:
|
||
Such a function gets two arguments: a tag and the source-buffer of
|
||
this tag. If the tag should be displayed (i.e. not being filtered out)
|
||
then the function has to return not nil otherwise nil.
|
||
|
||
@item No special filter:
|
||
This means to display all tags specified with the option
|
||
@code{ecb-show-tokens}. If currently some of the above filters are
|
||
applied they will be all removed.
|
||
|
||
@item Delete the last added:
|
||
This removes only the topmost filter-layer, means that filter added
|
||
last.
|
||
@end itemize
|
||
|
||
Be aware that the tag-list specified by the option
|
||
@code{ecb-show-tags} is the basis of all filters, i.e. tags which are
|
||
excluded by that option will never be shown regardless of the filter
|
||
type here!
|
||
|
||
All tags which match the applied filter(s) will be displayed in the
|
||
Methods-buffer. Such a filter is only applied to the current
|
||
source-buffer, i.e. each source-buffer can have its own tag-filters.
|
||
|
||
These tag-filters can also applied to sources which are not supported
|
||
by the semantic-parser but ``only'' by imenu or etags. But because for
|
||
these sources not all information are avaiable the protection- and
|
||
tag-class filter are not offered with such ``non-semantic''-sources.
|
||
See @ref{Non-semantic sources} for further details about working with
|
||
source-files not supported by the semantic-parser.
|
||
|
||
|
||
@subsubsection Inverse Filters
|
||
|
||
But if @code{ecb-methods-filter} is called with a prefix-argument then
|
||
an inverse filter is applied to the Methods-buffer, i.e. all tags
|
||
which do @strong{NOT} match the choosen filter will be displayed in
|
||
the Methods-buffer!
|
||
|
||
@subsubsection Layered filters
|
||
|
||
Per default the choosen filter will be applied on top of already
|
||
existing filters. This means that filters applied before are combined
|
||
with the new filter. This behavior can changed via the option
|
||
@code{ecb-methods-filter-replace-existing}.
|
||
|
||
@subsubsection Display of currently applied filters
|
||
|
||
The current active filter will be displayed in the modeline of the
|
||
Methods-buffer [regexp, prot (= protection), tag-class, function (=
|
||
filter-function)]. If an inverse filter has been applied then this is
|
||
signalized by a preceding caret ^. If currently more than 1 filter is
|
||
applied then always the top-most filter is displayed in the modeline
|
||
but the fact of more than 1 filter is visualized by the number of the
|
||
filters - included in parens. You can see all currently applied
|
||
filters by moving the mouse over the filter-string in modeline of the
|
||
Methods-buffer: They will displayed as help-echo.
|
||
|
||
@subsubsection Default filters for certain files.
|
||
|
||
The new option @code{ecb-default-tag-filter} allow to define default
|
||
tag-filters for certain files which are applied automatically after
|
||
loading such a file into a buffer. The possible filters are the same
|
||
as offered by the command @code{ecb-methods-filter} and they are
|
||
applied in the same manner - the only difference is they are applied
|
||
automatically. The files can be specified on a combined major-mode-
|
||
and filename-regexp-basis.
|
||
|
||
Usage-example: This can be used to display in outline-mode files (e.g.
|
||
@file{NEWS}) only the level-1-headings by defining a filter regexp
|
||
``^\* .*''.
|
||
|
||
@node The ECB-layout, Hiding the ECB windows, Filtering the tree-buffers, Usage of ECB
|
||
@section Changing, customizing, redrawing and creating layouts
|
||
|
||
@cindex layout
|
||
@cindex ECB-layout
|
||
The term @dfn{ECB-layout} means in which windows the ECB-frame is
|
||
divided. This chapter describes all aspects concerning this layout,
|
||
especially changing, customizing, redrawing and also creating new
|
||
layouts.
|
||
|
||
@menu
|
||
* Changing the ECB-layout:: How to change and customize the layout
|
||
* Redrawing the ECB-layout:: How and when redrawing the layout
|
||
* Changing window sizes:: Changing sizes of the ECB-windows
|
||
* Fixing window sizes:: Fixing sizes of the ECB-windows
|
||
* Creating a new ECB-layout:: Interactively creating new layouts
|
||
@end menu
|
||
|
||
@node Changing the ECB-layout, Redrawing the ECB-layout, The ECB-layout, The ECB-layout
|
||
@subsection Changing and customizing the ECB-layout
|
||
|
||
ECB offers several predefined layouts with different sets and also
|
||
different locations of ECB-windows. See below the ``ascii-screenshot''
|
||
of all currently built-in layouts@footnote{The command
|
||
@code{ecb-show-layout-help'} shows the outline-picture for all built-in
|
||
layouts.}.
|
||
|
||
In addition to these predefined layouts you can either interactively
|
||
create new layouts ``by example'' (@pxref{Creating a new ECB-layout})
|
||
or program new layouts with the macro @code{ecb-layout-define}
|
||
(@pxref{The layout-engine}). The former method is the recommended
|
||
one!
|
||
|
||
There are two ways to interactively change the layout:
|
||
@itemize @bullet
|
||
@item Changing permanently:
|
||
Customize the option @code{ecb-layout-name} and store it for future
|
||
Emacs sessions.
|
||
|
||
@item Switching between several layouts at runtime:
|
||
If you want to switch fast between a certain sequence of layouts see
|
||
the option @code{ecb-toggle-layout-sequence} and the command
|
||
@code{ecb-toggle-layout} (@pxref{Simulating speedbar}). For just
|
||
selecting another layout during current Emacs-session use the command
|
||
@code{ecb-change-layout}.
|
||
@end itemize
|
||
|
||
With the option @code{ecb-show-sources-in-directories-buffer} you can
|
||
define if sources are displayed in the directory-window of a layout
|
||
(@pxref{ECB Directories-window}).
|
||
|
||
In addition to the general layout you can specify if the layout should
|
||
contain a persistent compilation-window at the bottom of the frame, see
|
||
@code{ecb-compile-window-height} (@pxref{Temp- and compile-buffers}).
|
||
|
||
Maybe you want also change the look&feel of the tree-buffers. Then you
|
||
can change the general style of the tree-buffers with the option
|
||
@code{ecb-tree-buffer-style} and the location of the collapse- and
|
||
expand-symbols and the indentation of sub-nodes in a tree. See
|
||
@code{ecb-tree-indent} and @code{ecb-tree-expand-symbol-before}. More
|
||
details about the different tree-buffer-styles are described in
|
||
@ref{Tree-buffer styles}.
|
||
|
||
Here are all currently available layouts (for creating own new layouts
|
||
see @ref{Creating a new ECB-layout}); just customize the option
|
||
@code{ecb-layout-name} to the related name:
|
||
|
||
@table @asis
|
||
@item Layout ``left1''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | | |
|
||
| Sour | Hist | Edit |
|
||
| | | |
|
||
| | | |
|
||
|--------------| |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left2''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Sources | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left3''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | Edit |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left4''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| Sour | Hist | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left5''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | Edit |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``right1''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | Directories |
|
||
| | |
|
||
| | |
|
||
| |--------------|
|
||
| | |
|
||
| | |
|
||
| Edit | Sources |
|
||
| | |
|
||
| | |
|
||
| |--------------|
|
||
| | |
|
||
| | Methods |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left6''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| Sources | |
|
||
|--------------| |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| History | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``top1''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | | |
|
||
| | | |
|
||
| Directories | Sources | Methods |
|
||
| | | |
|
||
| | | |
|
||
|-----------------------------------------------------|
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| Edit |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left7''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left8''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| History | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``top2''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| |
|
||
| |
|
||
| Methods |
|
||
| |
|
||
| |
|
||
|-----------------------------------------------------|
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| Edit |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left9''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left10''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | | |
|
||
| Sou | Hist | |
|
||
| | | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left11''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left12''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| History | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left13''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Directories | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left14''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Directories | Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left15''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``leftright1''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | | |
|
||
| Directories | | Methods |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
|-------------| Edit | |
|
||
| | | |
|
||
| Sources | | |
|
||
| | | |
|
||
|-------------| | |
|
||
| | | |
|
||
| History | | |
|
||
| | | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``leftright2''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | | |
|
||
| Directories | | Methods |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | Edit | |
|
||
|-------------| |-------------|
|
||
| | | |
|
||
| Sources | | History |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``leftright3''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | | |
|
||
| Directories | | Methods |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | Edit | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@item Layout ``left-dir-plus-speedbar''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
|-------------| |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Speedbar | |
|
||
| | |
|
||
| | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
|
||
@item Layout ``left-analyse''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Analyse | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
|
||
@item Layout ``left-symboldef''
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Sources | |
|
||
| | |
|
||
|--------------| Edit |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| Symbol-defs | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@end table
|
||
|
||
@node Redrawing the ECB-layout, Changing window sizes, Changing the ECB-layout, The ECB-layout
|
||
@subsection Redrawing the ECB-layout
|
||
|
||
@cindex Redraw
|
||
If you have unintentionally destroyed the ECB-layout, you can always
|
||
restore the layout with calling @code{ecb-redraw-layout}. This is even
|
||
true, if you get messages like ``wrong-type-argument window-live-p
|
||
#<window 222>''.
|
||
|
||
If the variable @code{ecb-redraw-layout-quickly} is not nil then the redraw
|
||
is done by the @code{ecb-redraw-layout-quickly} function, otherwise by
|
||
@code{ecb-redraw-layout-full}. But it's strongly recommended to use the
|
||
quick redraw only if you have really slow machines where a full redraw
|
||
takes several seconds because the quick redraw is not really safe and
|
||
may have some drawbacks! On normal machines the full redraw should be
|
||
done in << 1s!
|
||
|
||
Please read the documentation of the command @code{ecb-redraw-layout}!
|
||
|
||
See also the hooks @code{ecb-redraw-layout-after-hook} and
|
||
@code{ecb-redraw-layout-before-hook}!
|
||
|
||
@node Changing window sizes, Fixing window sizes, Redrawing the ECB-layout, The ECB-layout
|
||
@subsection Changing the sizes of the special ECB-windows
|
||
|
||
The standard width and height of the special ECB-windows is defined
|
||
with the options @code{ecb-windows-width} and
|
||
@code{ecb-windows-height}. But changing these options always
|
||
influences all layouts which is not always desired.
|
||
|
||
ECB offers to re-adjust the width and height of the ECB-windows (e.g. by
|
||
dragging the windows-borders via the mouse) and then saving exactly
|
||
these current window-sizes for the current layout so after activating
|
||
this layout all windows have autom. the stored sizes.
|
||
|
||
This is done via the option @code{ecb-layout-window-sizes} and the
|
||
commands @code{ecb-store-window-sizes},
|
||
@code{ecb-restore-window-sizes} and
|
||
@code{ecb-restore-default-window-sizes}.
|
||
|
||
Here is an example how to resize and store the sizes of the
|
||
ECB-windows of layout ``left1'':
|
||
|
||
@enumerate
|
||
@item
|
||
Switch to layout ``left1'' via @code{ecb-change-layout} (@kbd{C-c . lc})
|
||
@item
|
||
Resize the ECB-windows by dragging the window-borders with the mouse
|
||
@item
|
||
Call @code{ecb-store-window-sizes}
|
||
@end enumerate
|
||
|
||
After this layout ``left1'' will be always drawn with the new sizes
|
||
until you call @code{ecb-restore-default-window-sizes} during layout
|
||
``left1'' is active.
|
||
|
||
@strong{Please note}: @code{ecb-store-window-sizes} stores the width
|
||
and height of the windows per default as fractions of the width (rsp.
|
||
height) of the ECB-frame, so the stored sizes are always correct
|
||
regardless of the current frame-size! But if called with a prefix
|
||
argument then fixed sizes are stored.
|
||
|
||
@node Fixing window sizes, Creating a new ECB-layout, Changing window sizes, The ECB-layout
|
||
@subsection Fixing the sizes of the special ECB-windows
|
||
|
||
GNU Emacs 21 introduced a new feature which can fix the sizes of a
|
||
window displaying a certain buffer even after resizing the frame. This
|
||
new feature is driven by the new buffer-local variable
|
||
@code{window-size-fixed}@footnote{Currently XEmacs does not support
|
||
this feature therefore @code{ecb-fix-window-size} has no effect with
|
||
XEmacs}.
|
||
|
||
ECB offers an option @code{ecb-fix-window-size} for fixing the sizes
|
||
of the special ECB-windows/buffers even after frame-resizing. The fix
|
||
type (valid values are @code{nil}, @code{t}, @code{width} and
|
||
@code{height}) can either be set on a layout-basis (means a different
|
||
value for each layout) or one value can be set for all layouts. In the
|
||
latter case there is an additional value @code{auto} which choose
|
||
autom. the senseful fix-type depending on the current layout-type: For
|
||
top-layouts the fix-type @code{height} and for all other layout-types
|
||
the fix-type @code{width}.
|
||
|
||
Probably the most senseful value is @code{auto} for all layouts
|
||
because it makes less sense to fix the height of the ecb-windows in a
|
||
left-, right- or leftright-layout. Same for fixing the width in a
|
||
top-layout.
|
||
|
||
Note: With Emacs < 22 there seems to be no distinction between
|
||
@code{width}, @code{height} and @code{t}. Therefore this option takes
|
||
no effect (means all ecb-windows have always unfixed sizes) with Emacs
|
||
< 22 if @code{ecb-compile-window-height} is not @code{nil}.
|
||
|
||
@node Creating a new ECB-layout, , Fixing window sizes, The ECB-layout
|
||
@subsection Interactively creating new layouts
|
||
|
||
@cindex New layouts
|
||
@cindex Creating new layouts
|
||
|
||
If you want to create your own ECB-layout then you can do this very
|
||
easy ``by example'' with the command @code{ecb-create-new-layout}.
|
||
This command creates a new empty frame and offers a small set of keys
|
||
to create the new layout by splitting windows.
|
||
@code{ecb-create-new-layout} and this couple of keys are your guide
|
||
during the layout-creation-process@footnote{During the creation
|
||
process you will be asked in the minibuffer for several options; here
|
||
you can use TAB-completion and an ``empty'' RET chooses always the
|
||
first option!}.
|
||
|
||
After calling @code{ecb-create-new-layout} you will be asked which
|
||
type of layout you want to create: ``left'', ``right'', ``top'' or
|
||
``left-right''. Here you specify where the ECB-tree-windows/buffers
|
||
should be located in the ECB-frame:
|
||
|
||
@itemize @minus
|
||
@item left: All ECB-tree-windows are located on the left side
|
||
@item right: All ECB-tree-windows are located on the right side
|
||
@item top: All ECB-tree-windows are located on the top side
|
||
@item left-right: All ECB-tree-windows are located on the left and
|
||
right side
|
||
@end itemize
|
||
|
||
Depending on the type you choose the window is splitted by the values
|
||
of the options @code{ecb-windows-width} (types ``left'', ``right'' and
|
||
``left-right'') or @code{ecb-windows-height} (type ``top'').
|
||
|
||
Afterwards you will see a frame like follows (here the layout-type is
|
||
``left-right''):
|
||
|
||
@example
|
||
@group
|
||
-----------------------------------------------------------------
|
||
|<point> | | |
|
||
| | ECB-layout creation mode | |
|
||
| | ======================== | |
|
||
| | | |
|
||
| | <This is a persistent help-screen>| |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
| | | |
|
||
-----------------------------------------------------------------
|
||
|
|
||
| ,---
|
||
`---| Splitted by the value of @code{ecb-windows-width}.
|
||
`---
|
||
@end group
|
||
@end example
|
||
|
||
The big window (here the middle window) will be the edit-area of the
|
||
new layout and can not be selected, deleted or splitted during the
|
||
creation process. It displays the help-screen for the layout-creation
|
||
mode. Here all the available commands are displayed.
|
||
|
||
The small window(s) (here the left and right windows) can be splitted
|
||
by you wherever you want (@kbd{C-s}). The left one contains the point.
|
||
You must give every ECB-tree-window you create a type (@kbd{C-t})
|
||
which can be either
|
||
|
||
@itemize @bullet
|
||
@item One of the built-in types
|
||
|
||
This can be either ``directories'', ``sources'', ``methods'',
|
||
``history'' or ``speedbar''.
|
||
|
||
@item Any user-defined type:
|
||
|
||
In this case you insert ``other'' after hitting @kbd{C-t} and you will
|
||
then be asked for the name of the user-defined type. You can insert
|
||
any arbitrary type name X. But to get this layout working you have to
|
||
define a function with name @code{ecb-set-X-buffer} whereas X is the
|
||
name of the user-defined type you have specified during
|
||
layout-creation.
|
||
|
||
This function @code{ecb-set-X-buffer} must be defined with the macro
|
||
@code{defecb-window-dedicator-to-ecb-buffer} and has to switch to the buffer you
|
||
want to display in this window. This macro automatically ensures that
|
||
this window is dedicated to that buffer.
|
||
|
||
Here is an example: Suppose you have inserted as type name ``example''
|
||
then you have to define and load a function
|
||
@code{ecb-set-example-buffer} which could be defined like follows:
|
||
|
||
@example
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-set-example-buffer " *ECB example-buf*"
|
||
(switch-to-buffer (get-buffer-create " *ECB example-buf*")))
|
||
@end example
|
||
|
||
If you forget to define such a function for the user-defined type then
|
||
nevertheless ECB will draw this layout but it will use the
|
||
default-function @code{ecb-set-default-ecb-buffer} instead.
|
||
@end itemize
|
||
|
||
If you are satisfied with your new layout just hit @kbd{C-q}. You will
|
||
be asked for a new layout-name (TAB-completion is offered to get a
|
||
list of all names already in use) and after inserting a new(!) name
|
||
the new layout is saved in the file defined by the option
|
||
@code{ecb-create-layout-file}. The new layout is now available via the
|
||
option @code{ecb-layout-name}.
|
||
|
||
There is no need for you to load the file
|
||
@code{ecb-create-layout-file} manually into your Emacs because it's
|
||
automatically loaded by ECB!
|
||
|
||
@strong{Please note}: During the layout-creation process only the
|
||
commands displayed in the help-screen are available. ALL other
|
||
commands are temporally disabled (even the mouse-commands).
|
||
|
||
For programming new layouts with emacs-lisp see @ref{The layout-engine}.
|
||
|
||
With the command @code{ecb-delete-new-layout} you can delete
|
||
previously created layouts (TAB-completion is offered for all names of
|
||
user created layouts).
|
||
|
||
@node Hiding the ECB windows, Maximizing the ECB windows, The ECB-layout, Usage of ECB
|
||
@section Hiding/Showing the ECB windows
|
||
|
||
@cindex Hide windows
|
||
@cindex Show windows
|
||
With @code{ecb-toggle-ecb-windows}, @code{ecb-hide-ecb-windows} and
|
||
@code{ecb-show-ecb-windows} you can hide/show all the ECB windows
|
||
without changing the activation state of ECB and also without
|
||
deactivating the advices for @code{delete-other-windows} and/or
|
||
@code{delete-window}. This is most useful if you use a layout like
|
||
``top2'' (@pxref{Common use-cases}) or if you want to have maximum space
|
||
for editing and you don't need the browsing windows all the time.
|
||
|
||
The following sequence of hooks is evaluated during showing again the
|
||
hidden ECB-windows:
|
||
@enumerate
|
||
@item @code{ecb-show-ecb-windows-before-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item <Redrawing the layout to show the hidden ECB-windows>
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-show-ecb-windows-after-hook}
|
||
@end enumerate
|
||
|
||
The following sequence of hooks is evaluated during hiding the
|
||
ECB-windows:
|
||
@enumerate
|
||
@item @code{ecb-hide-ecb-windows-before-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item <Hiding the ECB-windows>
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-hide-ecb-windows-after-hook}
|
||
@end enumerate
|
||
|
||
If the special ECB-windows are hidden (e.g. by
|
||
`ecb-toggle-ecb-windows') all adviced functions behave as their
|
||
originals. So the frame can be used as if ECB would not be active but
|
||
ECB IS still active in the ``background'' and all ECB-commands and all
|
||
ECB-keybindings can be used. Of course some of them doesn't make much
|
||
sense but nevertheless they can be called. Toggling the visibility of
|
||
the ECB-windows preserves the splitting-state of the edit-area: If you
|
||
hide the ECB-windows then the frame will be divided in the same
|
||
window-layout the edit-area had before the hiding and if you show the
|
||
ECB-windows again the edit-area will be divided into all the
|
||
edit-windows the ECB-frame had before the showing.
|
||
|
||
Therefore it should be enough to hide the ECB-windows to run other
|
||
Emacs-applications which have their own window-layout-managing. There
|
||
should be no conflicts. But nevertheless the most recommended method
|
||
for running ECB and other applications (e.g. xrefactory, Gnus etc.) in
|
||
the same frame is to use a window-manager like winring.el or
|
||
escreen.el (@pxref{Window-managers and ECB}).
|
||
|
||
|
||
@node Maximizing the ECB windows, Back/forward navigation, Hiding the ECB windows, Usage of ECB
|
||
@section Maximizing the ECB windows
|
||
|
||
@subsection How to maximize and minimize special ecb-tree-windows
|
||
|
||
To get a better overlook about the contents of a certain ECB-window
|
||
every ECB-window can be ``maximized'', means all other ECB-windows are
|
||
deleted so only the edit-window(s) and this maximized ECB-window are
|
||
visible (and maybe a compile-window if active). There are several ways
|
||
to do this:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Via the node-popup-menus of the ECB-windows
|
||
|
||
@item
|
||
Via the main ``ECB''-menu and here ``Display window maximized''
|
||
|
||
@item
|
||
Via calling the adviced version of
|
||
@code{delete-other-windows}@footnote{This command is adviced per
|
||
default, see @ref{The edit-area}.} (bound to @kbd{C-x 1}) in one of
|
||
the ECB windows.
|
||
|
||
@item
|
||
Via one of the commands @code{ecb-maximize-window-directories},
|
||
@code{ecb-maximize-window-sources}, @code{ecb-maximize-window-methods},
|
||
@code{ecb-maximize-window-history} or
|
||
@code{ecb-maximize-window-speedbar} or the bound short-cuts for those
|
||
commands.
|
||
|
||
@item
|
||
Via the new command @code{ecb-cycle-maximized-ecb-buffers} which
|
||
cycles through all ecb-buffers of current layout by maximizing exactly
|
||
one of the ecb-windows after every cycle-step.
|
||
|
||
@item
|
||
Via the option @code{ecb-maximize-ecb-window-after-selection} and then
|
||
just by selecting an ECB-window. ``Deselecting'' an ECB-window brings
|
||
back all ECB-windows of current layout.
|
||
|
||
@item
|
||
Via the default modeline-mechanisms for deleting other windows. GNU
|
||
Emacs binds @kbd{mouse-2} in its modeline to
|
||
@code{delete-other-window}. XEmacs binds a popup-menu with some window
|
||
commands to @kbd{button-3} in its modeline.
|
||
|
||
ECB combines the best of both worlds by supporting both of these
|
||
mechanisms for both Xemacs and Emacs: ECB binds a toggle-command to
|
||
@kbd{mouse-2} in the modeline of each tree-buffer which maximizes the
|
||
current tree-window if all ECB-windows are visible and displays all
|
||
ECB-windows if current tree-window is maximized. In addition ECB binds
|
||
a popup-menu to @kbd{mouse-3} which offers exactly 2 commands:
|
||
Maximizing current tree-window and displaying all ECB-windows.
|
||
@end itemize
|
||
|
||
``Minimizing'' such a maximized ECB-window, i.e. bringing back to its
|
||
original size and displays all ecb-windows of current layout, can
|
||
simply be done by redrawing the layout via the command
|
||
@code{ecb-redraw-layout} (bound to @kbd{C-c . lr}).
|
||
|
||
@subsection Selecting a node in a maximized ecb-tree-window
|
||
|
||
When you select a node (either via mouse or RET) in a maximized
|
||
tree-window the default behavior of ECB is the following:
|
||
|
||
Maximized directories-window: When selecting a directory then first
|
||
automatically the maximized directories-window will be ``minimized''
|
||
(i.e. all ecb-windows of current layout are displayed) if the current
|
||
layout contains a sources-buffer and no sources are shown in the
|
||
directories-window - see @code{ecb-show-sources-in-directories-buffer}.
|
||
So the source-files can be displayed in the sources-window.
|
||
|
||
Maximized sources- or history-window: When selecting a source-file in
|
||
one of these buffers then first automatically the maximized window
|
||
will be ``minimized'' (i.e. all ecb-windows of current layout are
|
||
displayed) if the current layout contains a methods-buffer. So the
|
||
tag-contents of the selected source-file can be displayed in the
|
||
methods-window.
|
||
|
||
For a even smarter behavior ECB offers the option
|
||
@code{ecb-maximize-next-after-maximized-select} which automatically
|
||
maximizes the next logical tree-window after a node selection. The
|
||
definition of ``next logical is'': Directories --> sources,
|
||
sources/history --> methods. But if the current maximized tree-buffer
|
||
is also contained in the option
|
||
@code{ecb-tree-do-not-leave-window-after-select} (see also the
|
||
tree-buffer-command @code{ecb-toggle-do-not-leave-window-after-select}
|
||
which is bound to @key{C-t} in each tree-buffer) then ECB does *not*
|
||
maximize the next logical tree-window but point stays in the currently
|
||
maximized tree-buffer so for example the user can select more than one
|
||
source-file from the sources-buffer.
|
||
|
||
@node Back/forward navigation, ECB-window synchronizing, Maximizing the ECB windows, Usage of ECB
|
||
@section Back- and forward navigation like a browser
|
||
|
||
With ECB you can ``browse'' in your source-files like with a
|
||
web-browser. This means ECB stores the current buffer- and
|
||
window-position relative to the current tag@footnote{e.g. a method,
|
||
a variable or any other semantic tag} in the edit-window after
|
||
|
||
@itemize @minus
|
||
@item selecting a tag in the ECB-methods buffer or
|
||
@item selecting a source-file in the ECB-sources/history-buffer.
|
||
@end itemize
|
||
|
||
ECB offers two commands @code{ecb-nav-goto-next} (@kbd{C-c . n}) and
|
||
@code{ecb-nav-goto-previous} (@kbd{C-c . p}) to go forward and
|
||
backward within this navigation history-list. These commands are also
|
||
available via the menu ``ECB --> Navigate''.
|
||
|
||
Aside normal ``location-browsing'' this is useful for example in a
|
||
scenario where the buffer is narrowed to a tag (see
|
||
@code{ecb-tag-visit-post-actions}):
|
||
|
||
@enumerate
|
||
@item You edit a function
|
||
@item Goto another function above the current in the same file
|
||
@item Add a few lines
|
||
@item Call ecb-nav-goto-previous
|
||
|
||
Now you will edit at the same place in the function.
|
||
@end enumerate
|
||
|
||
@node ECB-window synchronizing, Stealthy background tasks, Back/forward navigation, Usage of ECB
|
||
@section Synchronization of the ECB-windows
|
||
|
||
Per default ECB synchronizes automatically the contents of the
|
||
ECB-windows (e.g. tree-buffers) with the current active edit-window
|
||
(rsp. the current buffer of the edit window).
|
||
|
||
ECB distinguishes between the so called ``basic'' ECB-windows (for a general
|
||
description see @ref{Basic ECB-windows}) and add-on
|
||
ECB-windows (@pxref{Add-on ECB-windows}). This distinction is also important
|
||
concerning synchronization:
|
||
|
||
The basic ECB-windows are always synchronized together whereas for each add-on
|
||
ECB-window a separate synchronization option is offered.
|
||
|
||
This section describes at beginning some general synchronization aspects
|
||
(common for all ECB-windows, basic ones as well as add-ons), then the
|
||
synchronization of the basic-ECB-windows and finally the synchronization of
|
||
the add-on ECB-windows.
|
||
|
||
|
||
|
||
@menu
|
||
* General synchronization aspects:: General synchronization aspects
|
||
* Synchronization of basic ECB-windows:: Synchronization of basic ECB-windows
|
||
* Add-on synchronization:: Synchronization of add-on ECB-windows
|
||
@end menu
|
||
|
||
@node General synchronization aspects, Synchronization of basic ECB-windows, ECB-window synchronizing, ECB-window synchronizing
|
||
@subsection General synchronization aspects
|
||
|
||
For each separate ECB-window-synchronization (remember: One common for the basic
|
||
ECB-windows, one for each add-on ECB-window) ECB offers the following
|
||
option-triple (demonstrated for the basic ECB-windows):
|
||
|
||
@itemize
|
||
|
||
@item @code{ecb-basic-buffer-sync}:
|
||
|
||
Enables or disables the synchronization in general.
|
||
|
||
If active then the synchronization for the related ECB-window-buffers/windows
|
||
takes place whenever a buffer changes in an edit window or if another
|
||
edit-window with another buffer will be selected, if deactivated then never.
|
||
But you can also set this option to a list of major-modes and then the sync.
|
||
will only be done if the major-mode of the current buffer does NOT belong to
|
||
this list.
|
||
|
||
But in every case the synchronization only takes place if the
|
||
major-mode of the current-buffer in the current selected edit-window
|
||
has a relation to files or directories. Examples for the former one
|
||
are all programming-language-modes like @code{c++-mode} or
|
||
@code{java-mode}, @code{Info-mode} too, an example for the latter one
|
||
is @code{dired-mode}. For all major-modes related to
|
||
non-file/directory-buffers like @code{help-mode},
|
||
@code{customize-mode} and others a synchronization will never be done!
|
||
|
||
It's recommended to exclude at least @code{Info-mode} because it makes
|
||
no sense to synchronize the ECB-windows after calling the Info help.
|
||
Per default also @code{dired-mode} is excluded but it can also making
|
||
sense to synchronize the ECB-directories/sources windows with the
|
||
current directory of the dired-buffer in the edit-window.
|
||
|
||
@item @code{ecb-basic-buffer-sync-delay}:
|
||
|
||
This option takes only effect if the synchronization is switched on via
|
||
@code{ecb-basic-buffer-sync} and determines when ECB synchronizes.
|
||
|
||
This option sets the time in seconds (fractions allowed) Emacs must be idle
|
||
before the related ECB-window(s) are synchronized. If nil then there is no
|
||
delay, means synchronization takes place immediately. A small value of about
|
||
0.25 seconds saves CPU resources and you get even though almost the same
|
||
effect as if you set no delay.
|
||
|
||
Per default ECB always synchronizes on idle-basis and it is strongly
|
||
recommened not to change this (ie. not setting the delay-option to nil)
|
||
because this can be very performance consuming (e.g. at least the check if a
|
||
synchronization must be performed is done after @strong{every} key- or
|
||
mouse-button press!
|
||
|
||
Some fraction of a second is probably always the best choice, because it does
|
||
not cost cpu-power and nonetheless the synchronization takes place quite
|
||
immediately. So in most cases there is no need to bother with this option,
|
||
just use the default value.
|
||
|
||
@item @code{ecb-basic-buffer-sync-hook}:
|
||
|
||
For each separate synchronization a hook variable is offered where you can
|
||
hook in with some elisp code if you need some tasks performed afterwards the
|
||
synchronization has been finished.
|
||
|
||
In most cases no hook will be needed.
|
||
|
||
@end itemize
|
||
|
||
Analogous to the shown options for the basic ECB-windows each add-on
|
||
ECB-window has its own separate triple of these options, named congruent to
|
||
the name of the buffer-name of the add-on ECB-window (e.g. for the analyse
|
||
ECB-window with the buffer-name hold in @code{ecb-analyse-buffer-name} these
|
||
three options are named @code{ecb-analyse-buffer-sync},
|
||
@code{ecb-analyse-buffer-sync-delay} and @code{ecb-analyse-buffer-sync-hook}.
|
||
For some specialities see @ref{Add-on synchronization}.
|
||
|
||
@strong{Please note}: With the command @code{ecb-window-sync} you can
|
||
do a manual synchronization if the automatic one is switched off or
|
||
if you just want to do this! See the documantation of this command.
|
||
|
||
@node Synchronization of basic ECB-windows, Add-on synchronization, General synchronization aspects, ECB-window synchronizing
|
||
@subsection Synchronization of the basic ECB-windows
|
||
|
||
This section describes some special aspects of the synchronizing of the basic
|
||
ECB-windows:
|
||
|
||
@itemize @bullet
|
||
|
||
@item ECB-directories:
|
||
|
||
This windows is synchronized to display the directory where the
|
||
source-file which is displayed in the current active edit-window is
|
||
located. If the source-path (i.e. an element of the option
|
||
@code{ecb-source-path}) containing this directory is not expanded it
|
||
will be auto. expanded according to the value of the option
|
||
@code{ecb-auto-expand-directory-tree} (@pxref{ecb-directories}).
|
||
|
||
@item ECB-sources:
|
||
|
||
The ECB-sources-buffer contains after synchronizing all the sources of
|
||
the directory of the ``current'' source-file displayed in the
|
||
edit-window. The entry of the ``current'' source-file is highlighted.
|
||
|
||
@item ECB-methods:
|
||
|
||
Contains after synchronizing all the tags of the buffer in the current
|
||
selected edit-window, i.e. all methods, variables etc... depending on
|
||
the major-mode.
|
||
|
||
@item ECB-history:
|
||
|
||
Highlights the entry of the buffer displayed in the current active
|
||
edit-window if this buffer is a source-file.
|
||
|
||
@end itemize
|
||
|
||
The synchronization can be customized via the option triple
|
||
@code{ecb-basic-buffer-sync}, @code{ecb-basic-buffer-sync-delay} and
|
||
@code{ecb-basic-buffer-sync-hook}. The four basic ECB-windows of ECB are
|
||
always synchonized together, never separate!
|
||
|
||
@node Add-on synchronization, , Synchronization of basic ECB-windows, ECB-window synchronizing
|
||
@subsection Synchronization of add-on ECB-windows
|
||
|
||
Currently ECB has a separate synchronization for the add-on ECB-windows
|
||
ECB-analyse and ECB-symboldef and also for the eshell and
|
||
speedbar-integration. Customizing can be done via:
|
||
|
||
@itemize
|
||
|
||
@item ECB-analyse:
|
||
@code{ecb-analyse-buffer-sync}, @code{ecb-analyse-buffer-sync-delay} and
|
||
@code{ecb-analyse-buffer-sync-hook}
|
||
|
||
@item ECB-symboldef:
|
||
@code{ecb-symboldef-buffer-sync}, @code{ecb-symboldef-buffer-sync-delay} and
|
||
@code{ecb-symboldef-buffer-sync-hook}
|
||
|
||
@item ECB-eshell:
|
||
@code{ecb-eshell-buffer-sync}, @code{ecb-eshell-buffer-sync-delay} and
|
||
@code{ecb-eshell-buffer-sync-hook}
|
||
|
||
@item ECB-speedbar:
|
||
@code{ecb-speedbar-buffer-sync}, @code{ecb-speedbar-buffer-sync-delay} and
|
||
@code{ecb-speedbar-buffer-sync-hook}
|
||
|
||
@end itemize
|
||
|
||
Each enabling- and delay-option has an additonal special value 'basic which is
|
||
the default for all these options because it allows to use the current setting
|
||
of @code{ecb-basic-buffer-sync} rsp. @code{ecb-basic-buffer-sync-delay} for
|
||
the add-on synchronization too. Example: If @code{ecb-basic-buffer-sync} is
|
||
set to the value @code{(Info-mode dired-mode)} then a setting of 'basic for
|
||
@code{ecb-analyse-buffer-sync} means that synchronization is always done
|
||
unless the current major-mode is Info-mode or dired-mode. Per default all
|
||
add-on synchronization enabling- and delay-options are set to 'basic with one
|
||
exeption: @code{ecb-analyse-buffer-sync-delay}: See the documentation of this
|
||
option for a detailed description.
|
||
|
||
In general it is recommended to read the documentation of all these options.
|
||
|
||
@node Stealthy background tasks, Interactive ECB commands, ECB-window synchronizing, Usage of ECB
|
||
@section Stealthy background-tasks of ECB
|
||
|
||
ECB performs some tasks stealthily in the background and also
|
||
interruptable by the user because these tasks can be time-consuming
|
||
and could otherwise block ECB. Currently the following tasks are
|
||
performed stealthily and in the background by ECB:
|
||
|
||
@table @asis
|
||
@item Prescann directories for emptyness
|
||
Prescann directories and display them as empty or not-empty in the
|
||
directories-buffer. See the documentation of the option
|
||
@code{ecb-prescan-directories-for-emptyness} for a description.
|
||
|
||
@item File is read only
|
||
Check if sourcefile-items of the directories- or sources-buffer are
|
||
read-only or not. See documentation of the option
|
||
@code{ecb-sources-perform-read-only-check}.
|
||
|
||
@item Version-control-state
|
||
Checks the version-control-state of files in directories which are
|
||
managed by a VC-backend. See the option @code{ecb-vc-enable-support}.
|
||
|
||
@end table
|
||
|
||
All of these tasks (e.g. checking if a directory is empty or not)
|
||
perform a certain action for all directories or sources displayed in
|
||
the current visible tree-buffers of ECB. Normally there should be no
|
||
annoying delay for the user because each of these tasks will be only
|
||
performed when Emacs is idle and will be interrupted immediatelly when
|
||
a user hits a key or clicks the mouse but especially for
|
||
remote-directories one single action (e.g. checking if a certain
|
||
directory is empty or checking the VC-state of a sourcefile in such a
|
||
remote directory) can be very time-consuming and such a single action
|
||
is not interruptable (an interrupt can only occur between the
|
||
single-actions for two directories or sources) For a further
|
||
discussion how to deal best with remote directories see @ref{Remote
|
||
directories}.!
|
||
|
||
ECB offers for all stealthy tasks three steps of activation:
|
||
@itemize @bullet
|
||
@item @code{t}:
|
||
Switch on this feature.
|
||
|
||
@item @code{unless-remote}:
|
||
Switch on this feature but not for remote directories. The term
|
||
``remote'' means here directories which are used via tramp, ange-ftp
|
||
or efs. So mounted directories are counted not as remote directories
|
||
here even if such a directory is maybe hosted on a remote machine. But
|
||
normally only directories in a LAN are mounted so there should be no
|
||
performance-problems with such mounted directories.
|
||
|
||
@item @code{nil}:
|
||
Switch off this feature completely.
|
||
@end itemize
|
||
|
||
In combination with the option @code{ecb-stealthy-tasks-delay} these
|
||
three choices already allow adapting the stealthy tasks to most
|
||
needs. But to offer finest granularity for which directories a certain
|
||
stealthy task should be switched on and for which not ECB offers for
|
||
every stealthy task an additional option which allows a finer
|
||
adjustment:
|
||
|
||
@itemize @bullet
|
||
@item Prescanning directories for emptyness:
|
||
@code{ecb-prescan-directories-exclude-regexps}.
|
||
|
||
@item Checking the read-only-state of a sourcefile:
|
||
@code{ecb-read-only-check-exclude-regexps}
|
||
|
||
@item Checking the VC-state of sourcefiles:
|
||
@code{ecb-vc-directory-exclude-regexps}
|
||
@end itemize
|
||
|
||
These options take only effect when the related task is not completely
|
||
switched off. If this is the case they allow excluding certain
|
||
directories (or the sources of directories) from being processed by a
|
||
certain stealthy task.
|
||
|
||
|
||
@node Interactive ECB commands, ,Stealthy background tasks, Usage of ECB
|
||
@section Interactive ECB commands
|
||
|
||
@noindent
|
||
ECB offers a lot of interactive commands. Some of these commands
|
||
prompt the user in the minibuffer if called with a prefix argument.
|
||
|
||
Example: If @code{ecb-clear-history} is called with a prefix argument
|
||
then you will be prompted in the minibuffer with:
|
||
|
||
@example
|
||
Clear from history: [all, not-existing-buffers, existing-buffers]
|
||
@end example
|
||
|
||
You can choose one of the options enclosed in brackets with
|
||
TAB-completion; hitting RET direct after the prompt chooses auto. the
|
||
first offered option (in the example above ``all'').
|
||
|
||
@strong{Please note}: The following interactive commands of ECB are
|
||
listed without the prefix ``ecb-'' (e.g. the command
|
||
@code{ecb-activate} is listed with name ``activate''). This has been
|
||
done for a better readable command index. @xref{Command Index}.
|
||
|
||
@deffn Command activate
|
||
Activates ECB and creates the special buffers for the choosen layout.
|
||
For the layout see @code{ecb-layout-name}. This function always raises
|
||
the ECB-frame if called from another frame. This is the same as
|
||
calling @code{ecb-minor-mode} with a positive argument.
|
||
@end deffn
|
||
|
||
@deffn Command add-all-buffers-to-history
|
||
Add all current file-buffers to the history-buffer of ECB.
|
||
Dependend on the values of @code{ecb-history-make-buckets} and
|
||
@code{ecb-history-sort-method} afterwards the history is bucketized or
|
||
not and sorted either by name or by extension (if bucketized
|
||
then the sorting is only within each bucket). If
|
||
@code{ecb-history-sort-method} is nil the most recently used buffers
|
||
are on the top of the history and the seldom used buffers at the
|
||
bottom (again: when bucketized then this holds only within each
|
||
bucket).
|
||
@end deffn
|
||
|
||
@deffn Command analyse-buffer-sync
|
||
Synchronize the analyse buffer with the current buffer and point. This
|
||
means in fact display the current analysis for current point.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command change-layout &optional preselect-type
|
||
Select a layout-name from all current available layouts
|
||
(TAB-completion is offered) and change the layout to the selected
|
||
layout-name. If optional argument PRESELECT-TYPE is not nil then you
|
||
can preselect a layout-type \(TAB-completion is offered too) and then
|
||
you will be asked only for layouts of that preselected type. Note:
|
||
This function works by changing the option @code{ecb-layout-name} but
|
||
only for current Emacs-session.
|
||
@end deffn
|
||
|
||
@deffn Command clear-history
|
||
Clears the history-buffer.
|
||
@end deffn
|
||
|
||
@deffn Command customize
|
||
Open a customize-buffer for all customize-groups of ECB.
|
||
@end deffn
|
||
|
||
@deffn Command customize-most-important
|
||
Open a customize-buffer for the most important options of ECB.
|
||
@end deffn
|
||
|
||
@deffn Command create-new-layout
|
||
Start process for interactively creating a new ECB-layout
|
||
(@pxref{Creating a new ECB-layout}).
|
||
@end deffn
|
||
|
||
@deffn Command cycle-maximized-ecb-buffers
|
||
Cycles through all ecb-buffers of current layout by maximizing exactly
|
||
one of the ecb-windows after every cycle-step.
|
||
@end deffn
|
||
|
||
@deffn Command cycle-through-compilation-buffers &optional choose-buffer
|
||
Cycle through all compilation buffers currently open and display them
|
||
within the compilation window @code{ecb-compile-window}. If the
|
||
currently opened buffer within the compilation window is not a
|
||
compilation buffer, we jump to the first compilation buffer. If not we
|
||
try to loop through all compilation buffers. If we hit the end we go
|
||
back to the beginning.
|
||
|
||
If @var{CHOOSE-BUFFER} is not @code{nil} then the user will be
|
||
prompted for the compilation-buffer to switch to.
|
||
@end deffn
|
||
|
||
@deffn Command deactivate
|
||
Deactivates the ECB and kills all ECB buffers and windows.
|
||
@end deffn
|
||
|
||
@deffn Command delete-new-layout
|
||
Select a layout-name for a layout created by
|
||
@code{ecb-create-new-layout} and delete this layout. This means the
|
||
layout-definition is removed from the file
|
||
@code{ecb-create-layout-file} and the layout-function and associated
|
||
aliases are unbound.
|
||
@end deffn
|
||
|
||
@deffn Command display-news-for-upgrade &optional FULL-NEWS
|
||
Display the most important NEWS after an ECB-upgrade. If you call this
|
||
function but no ECB-upgrade has been performed before starting ECB
|
||
then nothing is display unless @var{FULL-NEWS} is not nil.
|
||
|
||
If @var{FULL-NEWS} is not nil then the NEWS-file is displayed in
|
||
another window.
|
||
@end deffn
|
||
|
||
@deffn Command display-upgraded-options
|
||
Display a information-buffer which options have been upgraded or
|
||
reset. Offers two buttons where the user can decide if the upgraded
|
||
options should also being saved by ECB for future settings or if the
|
||
buffer should be killed.
|
||
|
||
If saving is possible this command display where the options would be
|
||
saved. It is that file Emacs uses to save customize-settings. This
|
||
file is ``computed'' from the settings in @code{custom-file} and
|
||
@code{user-init-file} (see the documentation of these variables).
|
||
|
||
ECB automatically makes a backup-file of that file which will be
|
||
modified by storing the upgraded rsp. renamed ECB-options. This backup
|
||
file gets a unique name by adding a suffix ``.before_ecb_<version>''
|
||
to the name of the modified file. If such a file already exists ECB
|
||
adds a unique number to the end of the filename to make the filename
|
||
unique. This is a safety mechanism if something fails during storing
|
||
the upgraded options, so you never lose the contents of your
|
||
customization-file!
|
||
@end deffn
|
||
|
||
@deffn Command expand-methods-nodes &optional force-all
|
||
Set the expand level of the nodes in the ECB-methods-buffer.
|
||
|
||
This command asks in the minibuffer for an indentation level LEVEL. With this
|
||
LEVEL you can precisely specify which level of nodes should be expanded. LEVEL
|
||
means the indentation-level of the nodes.
|
||
|
||
A LEVEL value X means that all nodes with an indentation-level <= X are
|
||
expanded and all other are collapsed. A negative LEVEL value means all visible
|
||
nodes are collapsed.
|
||
|
||
Nodes which are not indented have indentation-level 0!
|
||
|
||
Which node-types are expanded (rsp. collapsed) by this command
|
||
depends on the options @code{ecb-methods-nodes-expand-spec} and
|
||
@code{ecb-methods-nodes-collapse-spec}! With optional argument
|
||
@var{FORCE-ALL} all tags will be expanded/collapsed regardless of
|
||
the values of these options.
|
||
|
||
Examples:
|
||
@itemize @minus
|
||
@item LEVEL = 0
|
||
expands only nodes which have no indentation itself.
|
||
@item LEVEL = 2
|
||
expands nodes which are either not indented or indented indented once
|
||
or twice
|
||
@item LEVEL ~ 10
|
||
should normally expand all nodes expect there are nodes which are
|
||
indented deeper than 10.
|
||
@end itemize
|
||
|
||
Note 1: This command switches off auto. expanding of the method-buffer
|
||
if @code{ecb-expand-methods-switch-off-auto-expand} is not nil. But it
|
||
can be switched on again quickly with
|
||
@code{ecb-toggle-auto-expand-tag-tree} or @kbd{[C-c . a]}.
|
||
|
||
Note 2: All this is only valid for file-types parsed by semantic. For
|
||
other file types which are parsed by imenu or etags (see
|
||
@code{ecb-process-non-semantic-files}) @var{FORCE-ALL} is always true!
|
||
@end deffn
|
||
|
||
@deffn Command dump-semantic-toplevel
|
||
Dump the current semantic-tags in special buffer and display them.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command eshell-current-buffer-sync
|
||
Synchronize the eshell with the directory of current source-buffer.
|
||
This is only done if the eshell is currently visible in the
|
||
compile-window of ECB and if either this function is called
|
||
interactively or @code{ecb-eshell-buffer-sync} is not nil.
|
||
@end deffn
|
||
|
||
@deffn Command eshell-recenter
|
||
Recenter the eshell window so that the prompt is at the buffer-end.
|
||
@end deffn
|
||
|
||
@deffn Command expand-directory-nodes
|
||
Set the expand level of the nodes in the ECB-directories-buffer. For
|
||
argument LEVEL see @code{ecb-expand-methods-nodes}.
|
||
|
||
Be aware that for deep structured paths and a lot of source-paths this
|
||
command can last a long time - depending on machine- and
|
||
disk-performance.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-analyse
|
||
Make the ECB-analyse window the current window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-compilation
|
||
Goto the ecb compilation window @code{ecb-compile-window}.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-directories
|
||
Make the ECB-directories window the current window. If
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} is @code{dir} then
|
||
goto to the speedbar-window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-ecb-by-smart-selection
|
||
selects a special ecb-browsing-window by smart selection. The command offers a
|
||
list of all special ecb-windows by buffer-name. Selecting the buffer-name will
|
||
select the displaying window. Which special ecb-windows are offered depends on
|
||
the currently selected window: If not a special ecb-window is the currently
|
||
selected-window then all edit-windows are offered in canonical order (means
|
||
from top-left to button-right). If an ecb-window is the currently
|
||
selected-window then all other(!) special ecb-windows are offered, beginning
|
||
with the next special ecb-window to the current ecb-window (the following
|
||
special ecb-windows also in canonical order). If there is only one senseful
|
||
destination-ecb-window then this window is immediately selected, without
|
||
confirmation (e.g.: There are two special ecb-windows and point stays in one
|
||
of them. Or there is only one ecb-window and point stays either in one of the
|
||
edit-windows or in the compile-window).
|
||
|
||
If optional argument USE-IMMEDIATE-COMPLETION is nil then all possible
|
||
destination-windows are displayed in the message-area and only hitting TAB
|
||
offers completion. If USE-IMMEDIATE-COMPLETION is not nil then all possible
|
||
destinations are immediately shown in a completion-buffer.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-edit-by-smart-selection
|
||
Selects an edit-window by smart selection. The command offers a list of all
|
||
edit-windows by buffer-name. Selecting the buffer-name will select the
|
||
displaying window. Which edit-windows are offered depends on the currently
|
||
selected window: If not an edit-window is the currently selected-window then
|
||
all edit-windows are offered in canonical order (means from top-left to
|
||
button-right). If an edit-window is the currently selected-window then all
|
||
other(!) edit-windows are offered, beginning with the next edit-window to the
|
||
current edit-window (the following edit-windows also in canonical order). If
|
||
there is only one senseful destination-edit-window then this window is
|
||
immediately selected, without confirmation (e.g.: There are two edit-windows
|
||
and point stays in one of them. Or there is only one edit-window and point
|
||
stays either in one of the special ecb-windows or in the compile-window).
|
||
|
||
If optional argument USE-IMMEDIATE-COMPLETION is nil then all possible
|
||
destination-windows are displayed in the message-area and only hitting TAB
|
||
offers completion. If USE-IMMEDIATE-COMPLETION is not nil then all possible
|
||
destinations are immediately shown in a completion-buffer.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-edit1
|
||
Make the (first) edit-window window the current window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-edit2
|
||
Make the second edit-window (if available) window the current window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-edit-last
|
||
Make the last selected edit-window window the current window. This is
|
||
the same as if @code{ecb-mouse-click-destination} is set to
|
||
@code{last-point}.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command goto-window-history
|
||
Make the ECB-history window the current window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-methods
|
||
Make the ECB-methods window the current window. If
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} is @code{method}
|
||
then goto to the speedbar-window.
|
||
@end deffn
|
||
|
||
@deffn Command goto-window-sources
|
||
Make the ECB-sources window the current window. If
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} is @code{source}
|
||
then goto to the speedbar-window.
|
||
@end deffn
|
||
|
||
@deffn Command history-filter
|
||
Apply a filter to the history-buffer to reduce the number of entries.
|
||
So you get a better overlooking. There are three choices:
|
||
|
||
@itemize @minus
|
||
@item Filter by extension:
|
||
Just insert the extension you want the History-buffer being filtered.
|
||
Insert the extension without leading dot!
|
||
|
||
@item Filter by regexp:
|
||
Insert the filter as regular expression.
|
||
|
||
@item No filter:
|
||
This means to display an entry for all currently living file-buffers.
|
||
@end itemize
|
||
@end deffn
|
||
|
||
@deffn Command jde-display-class-at-point
|
||
Display in the ECB-methods-buffer the contents (methods, attributes
|
||
etc...) of the class which contains the definition of the ``thing''
|
||
under point (this can be a variable-name, class-name, method-name,
|
||
attribute-name). This function needs the same requirements to work as
|
||
the method-completion feature of JDEE (see
|
||
@code{jde-complete})!. The source-file is searched first in
|
||
@code{jde-sourcepath}, then in @code{jde-global-classpath}, then in
|
||
@var{$CLASSPATH}, then in current-directory.
|
||
|
||
Works only for classes where the source-code (i.e. the *.java-file) is
|
||
available.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-analyse
|
||
Maximize the ECB-analyse-window. I.e. delete all other ECB-windows, so
|
||
only one ECB-window and the edit-window(s) are visible (and maybe a
|
||
compile-window). Works also if the ECB-analyse-window is not visible
|
||
in current layout.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-directories
|
||
Maximize the ECB-directories-window, i.e. delete all other
|
||
ECB-windows, so only one ECB-window and the edit-window(s) are visible
|
||
(and maybe a compile-window). Works also if the ECB-directories-window
|
||
is not visible in current layout.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-sources
|
||
Maximize the ECB-sources-window, i.e. delete all other ECB-windows, so
|
||
only one ECB-window and the edit-window(s) are visible (and maybe a
|
||
compile-window). Works also if the ECB-sources-window is not visible
|
||
in current layout.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-methods
|
||
Maximize the ECB-methods-window, i.e. delete all other ECB-windows, so
|
||
only one ECB-window and the edit-window(s) are visible (and maybe a
|
||
compile-window). Works also if the ECB-methods-window is not visible
|
||
in current layout.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-history
|
||
Maximize the ECB-history-window, i.e. delete all other ECB-windows, so
|
||
only one ECB-window and the edit-window(s) are visible (and maybe a
|
||
compile-window). Works also if the ECB-history-window is not visible
|
||
in current layout.
|
||
@end deffn
|
||
|
||
@deffn Command maximize-window-speedbar
|
||
Maximize the ECB-speedbar-window, i.e. delete all other ECB-windows,
|
||
so only one ECB-window and the edit-window(s) are visible (and maybe a
|
||
compile-window). Does nothing if the speedbar-window is not visible
|
||
within the ECB-frame.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter
|
||
Apply a filter to the Methods-buffer to reduce the number of entries.
|
||
So you get a better overlooking. There are six choices:
|
||
|
||
@itemize @bullet
|
||
@item Filter by protection:
|
||
Just insert the protection you want the Methods-buffer being filtered:
|
||
private, protected or public!
|
||
|
||
@item Filter by regexp:
|
||
Insert the filter as regular expression.
|
||
|
||
@item Filter by tag-class:
|
||
You can filter by the tag-classes of current major-mode. The available
|
||
tag-classes come from the variable
|
||
@code{semantic--symbol->name-assoc-list}. The are normally methods,
|
||
variables etc.
|
||
|
||
@item Filter by current type:
|
||
In languages which have types like Java or C++ this filter displays
|
||
only the current type and all its members (e.g. attributes and
|
||
methods). If ECB can not identify the current type in the
|
||
source-buffer or in the methods-window then nothing will be done.
|
||
|
||
@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
|
||
|
||
The protection-, current-type- and the tag-class-filter are only
|
||
available for semantic-supported sources.
|
||
|
||
Be aware that the tag-list specified by the option
|
||
@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.
|
||
|
||
If called with a prefix-argument or when optional arg INVERSE is not
|
||
nil then an inverse filter is applied to the Methods-buffer, i.e. all
|
||
tags which do NOT match the choosen filter will be displayed in the
|
||
Methods-buffer!
|
||
|
||
Per default the choosen filter will be applied on top of already
|
||
existing filters. This means that filters applied before are combined
|
||
with the new filter. This behavior can changed via the option
|
||
@code{ecb-methods-filter-replace-existing}. But regardless of the
|
||
setting in @code{ecb-methods-filter-replace-existing} applying one of
|
||
the not-inverse filters protection, tag-class or current-type always
|
||
replaces exactly already existing filters of that type. On the other
|
||
hand applying more than one inverse tag-class- or protection-filter
|
||
can make sense.
|
||
|
||
Such a filter is only applied to the current source-buffer, i.e. each
|
||
source-buffer can have its own tag-filters.
|
||
|
||
The current active filter will be displayed in the modeline of the
|
||
Methods-buffer [regexp, prot (= protection), tag-class, function (=
|
||
filter-function)]. If an inverse filter has been applied then this is
|
||
signalized by a preceding caret ^. If currently more than 1 filter is
|
||
applied then always the top-most filter is displayed in the modeline
|
||
but the fact of more than 1 filter is visualized by the number of the
|
||
filters - included in parens. You can see all currently applied
|
||
filters by moving the mouse over the filter-string in modeline of the
|
||
Methods-buffer: They will displayed as help-echo.
|
||
|
||
See the option @code{ecb-default-tag-filter} if you search for
|
||
automatically applied default-tag-filters.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-current-type
|
||
Display in the Methods-buffer only the current type and its members.
|
||
For further details see @code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
|
||
@deffn Command methods-filter-delete-last
|
||
Remove the most recent filter from the Methods-buffer. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-function &optional inverse
|
||
Filter the methods-buffer by a function. If INVERSE is not nil (called
|
||
with a prefix arg) then an inverse filter is applied. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-nofilter
|
||
Remove any filter from the Methods-buffer. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-protection &optional inverse
|
||
Filter the methods-buffer by protection. If INVERSE is not nil (called
|
||
with a prefix arg) then an inverse filter is applied. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-regexp &optional inverse
|
||
Filter the methods-buffer by a regexp. If INVERSE is not nil (called
|
||
with a prefix arg) then an inverse filter is applied. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command methods-filter-tagclass &optional inverse
|
||
Filter the methods-buffer by tag-class. If INVERSE is not nil (called
|
||
with a prefix arg) then an inverse filter is applied. For further details see
|
||
@code{ecb-methods-filter}.
|
||
@end deffn
|
||
|
||
@deffn Command minor-mode &optional arg
|
||
Toggle ECB minor mode. With prefix argument @var{ARG}, turn on if
|
||
positive, otherwise off. Return non-@code{nil} if the minor mode is
|
||
enabled.
|
||
@end deffn
|
||
|
||
@deffn Command nav-goto-previous
|
||
Go backward in the navigation history-list, see @ref{Back/forward
|
||
navigation}.
|
||
@end deffn
|
||
|
||
@deffn Command nav-goto-next
|
||
Go forward in the navigation history-list, see @ref{Back/forward
|
||
navigation}.
|
||
@end deffn
|
||
|
||
@deffn Command rebuild-methods-buffer
|
||
Updates the methods buffer with the current buffer after deleting the
|
||
complete previous parser-information, means no semantic-cache is used!
|
||
Point must stay in an edit-window otherwise nothing is done. This
|
||
method is merely needed for semantic parsed buffers if semantic parses
|
||
not the whole buffer because it reaches a not parse-able code or for
|
||
buffers not supported by semantic but by imenu or etags.
|
||
|
||
Examples when a call to this function can be necessary:
|
||
|
||
@itemize
|
||
@item
|
||
If an Elisp-file is parsed which contains in the middle a defun X
|
||
where the closing ) is missing then semantic parses only until this
|
||
defun X is reached and you will get an incomplete ECB-method buffer.
|
||
In such a case you must complete the defun X and then call this
|
||
function to completely reparse the Elisp-file and rebuild the ECB
|
||
method buffer!
|
||
|
||
@item
|
||
For not semantic supported buffers which can be parsed by imenu or
|
||
etags (see @code{ecb-process-non-semantic-files}) because for these
|
||
buffers there is no built-in auto-rebuild mechanism. For these buffers
|
||
this command calls @code{ecb-rebuild-methods-buffer-for-non-semantic}.
|
||
@end itemize
|
||
|
||
For non-semantic-sources supported by etags the option
|
||
@code{ecb-auto-save-before-etags-methods-rebuild} is checked before
|
||
rescanning the source-buffer and rebuilding the methods-buffer.
|
||
|
||
If point is in one of the ecb-windows or in the compile-window then
|
||
this command rebuids the methods-buffer with the contents of the
|
||
source-buffer the last selected edit-window.
|
||
@end deffn
|
||
|
||
@deffn Command redraw-layout &optional ARG
|
||
Redraw the ECB screen.
|
||
|
||
Do not call this command from elisp-program but only interactively!
|
||
|
||
Called without a prefix-argument the state of the ECB-frame-layout
|
||
will preserved. This means:
|
||
|
||
@itemize @minus
|
||
@item
|
||
The state of compile-window (hidden or visible) will be preserved but
|
||
if visible then the height will be as specified in
|
||
@code{ecb-compile-window-height}.
|
||
|
||
@item
|
||
The state of the ECB-windows will be preserved (hidden or visible) but
|
||
if visible then the sizes will be as specified in the layout (and with
|
||
the options @code{ecb-windows-width} and @code{ecb-windows-height}) or
|
||
as stored with @code{ecb-store-window-sizes}.
|
||
@end itemize
|
||
|
||
If called with ONE prefix-argument (@kbd{[C-u]}) then the layout will
|
||
be drawn with all ECB-windows and also with a visible compile-window
|
||
(when @code{ecb-compile-window-height} is not nil). The
|
||
splitting-state of the edit-area will be preserved.
|
||
|
||
If called with TWO prefix-arguments (i.e. hitting @kbd{[C-u]} twice:
|
||
(@kbd{[C-u]} @kbd{[C-u]}) then an emergency-redraw will be performed.
|
||
This means the same as if called with one prefix-argument (s.a.) but
|
||
the splitting-state of the edit-area will NOT be preserved but all
|
||
edit-windows besides the current one will be deleted. Use this only if
|
||
there are some anomalies after standard redraws!
|
||
|
||
If the variable @code{ecb-redraw-layout-quickly} is not nil then the
|
||
redraw is done by the @code{ecb-redraw-layout-quickly} function,
|
||
otherwise by @code{ecb-redraw-layout-full}.
|
||
|
||
Please not: It's strongly recommended to use the quick redraw only if
|
||
you have really slow machines where a full redraw takes several
|
||
seconds because the quick redraw is not really safe and has some
|
||
annoying drawbacks! On normal machines the full redraw should be done
|
||
in << 1s so there should be no need for the quick version!
|
||
@end deffn
|
||
|
||
|
||
@deffn Command restore-default-window-sizes
|
||
Resets the sizes of the ECB windows to their default values.
|
||
@end deffn
|
||
|
||
@deffn Command restore-window-sizes
|
||
Sets the sizes of the ECB windows to their stored values. See option
|
||
@code{ecb-layout-window-sizes} and command
|
||
@code{ecb-store-window-sizes}.
|
||
@end deffn
|
||
|
||
@deffn Command select-ecb-frame
|
||
Selects the @code{ecb-frame} if ECB is activated - otherwise reports
|
||
an error.
|
||
@end deffn
|
||
|
||
@deffn Command show-help &optional format
|
||
Shows the online help of ECB either in Info or in HTML format
|
||
depending on the value of @code{ecb-show-help-format}. If called with
|
||
prefix argument, i.e. if @var{FORMAT} is not nil then the user is
|
||
prompted to choose the format of the help (Info or HTML). If an error
|
||
about not finding the needed help-file occurs please take a look at
|
||
the options @code{ecb-help-info-start-file} and
|
||
@code{ecb-help-html-start-file}!
|
||
|
||
Note: If you got ECB as a standard XEmacs-package maybe the
|
||
HTML-online-documentation is not included.
|
||
@end deffn
|
||
|
||
@deffn Command show-layout-help
|
||
Select a name of a layout and shows the documentation of the
|
||
associated layout-function. At least for the built-in layouts the
|
||
documentation contains a picture of the outline of the chosen layout.
|
||
@end deffn
|
||
|
||
@deffn Command show-tip-of-the-day
|
||
Show tip of the day if @code{ecb-tip-of-the-day} is not nil or if
|
||
called interactively.
|
||
@end deffn
|
||
|
||
@deffn Command sources-filter
|
||
Apply a filter to the sources-buffer to reduce the number of entries.
|
||
So you get a better overlooking. There are three choices:
|
||
|
||
@itemize @minus
|
||
@item Filter by extension:
|
||
Just insert the extension you want the Sources-buffer being filtered.
|
||
Insert the extension without leading dot!
|
||
|
||
@item Filter by regexp:
|
||
Insert the filter as regular expression.
|
||
|
||
@item No filter:
|
||
This means to display an entry for every file in the current selected
|
||
directory (all except these filter already filtered out by
|
||
@code{ecb-source-file-regexps} and
|
||
@code{ecb-sources-exclude-cvsignore}).
|
||
@end itemize
|
||
|
||
Such a filter is only applied to the current selected directory, i.e. each
|
||
directory has its own filtered sources-buffer.
|
||
@end deffn
|
||
|
||
@deffn Command store-window-sizes &optional FIX
|
||
Stores the sizes of the ECB windows for the current layout. The size
|
||
of the ECB windows will be set to their stored values when
|
||
@code{ecb-redraw-layout} or @code{ecb-restore-window-sizes} is called.
|
||
To reset the window sizes to their default values call
|
||
@code{ecb-restore-default-window-sizes}. Please read also the
|
||
documentation of @code{ecb-layout-window-sizes}!
|
||
|
||
The windows sizes are stored per default as fractions of current
|
||
frame-width and -height of the ecb-frame, so the stored values will
|
||
``work'' for other frame sizes too. If a permanent compile-window is
|
||
visible then ECB will tell you that window-sizes should be stored with
|
||
hidden compile-window and ask you if you want proceed; if you proceed
|
||
then the window-heights will be stored as fractions of current
|
||
(frame-height minus current visible compile-window-height) so you
|
||
should ensure that the current compile-window has its standard-height
|
||
as specified in @code{ecb-compile-window-height}!. If @var{FIX} is not
|
||
nil (means called with a prefix argument) then always the fixed values
|
||
of current width and height are stored!
|
||
@end deffn
|
||
|
||
@deffn Command submit-problem-report
|
||
Submit a problem report for the ECB to the ECB mailing-list. This
|
||
command generates in the edit-window a problem-report which contains
|
||
already the current values of all ECB options, the current
|
||
backtrace-buffer if there is any and the current message-buffer. You
|
||
will be asked for a problem-report subject and then you must insert a
|
||
description of the problem. Please describe the problem as detailed as
|
||
possible!
|
||
@end deffn
|
||
|
||
@deffn Command toggle-auto-expand-tag-tree &optional arg
|
||
Toggle auto expanding of the ECB-methods-buffer. With prefix argument
|
||
@var{ARG}, make switch on if positive, otherwise switch off. If the
|
||
effect is that auto-expanding is switched off then the current value
|
||
of @code{ecb-auto-expand-tag-tree} is saved so it can be used for
|
||
the next switch on by this command.
|
||
@end deffn
|
||
|
||
@deffn Command toggle-compile-window &optional arg
|
||
Toggle the visibility of the compile-window of ECB. With prefix
|
||
argument ARG, make visible if positive, otherwise invisible. The
|
||
height of the compile-window is always the current value of
|
||
@code{ecb-compile-window-height}! If called and
|
||
@code{ecb-compile-window-height} is nil then ECB asks for the height
|
||
of the compile-window, sets this height as new value of
|
||
@code{ecb-compile-window-height} and displays the compile-window (so
|
||
if you have called this command by mistake and you do not want a
|
||
compile-window you have to quit with @key{C-g}).
|
||
@end deffn
|
||
|
||
|
||
@deffn Command toggle-compile-window-height &optional arg
|
||
Toggle whether the @code{ecb-compile-window} is enlarged or not. If
|
||
@var{ARG} > 0 then shrink or enlarge the the compile-window according
|
||
to the value of @code{ecb-enlarged-compilation-window-max-height}. But
|
||
never shrink below the value of @code{ecb-compile-window-height}. If
|
||
@var{ARG} <= 0 then shrink @code{ecb-compile-window} to
|
||
@code{ecb-compile-window-height} and if @var{ARG} is nil then toggle
|
||
the enlarge-state.
|
||
@end deffn
|
||
|
||
@deffn Command toggle-ecb-windows &optional arg
|
||
Toggle visibility of the ECB-windows. With prefix argument @var{ARG},
|
||
make visible if positive, otherwise invisible. This has nothing to do
|
||
with (de)activating ECB but only affects the visibility of the ECB
|
||
windows. ECB minor mode remains active!
|
||
@end deffn
|
||
|
||
@deffn Command toggle-layout &optional last-one
|
||
Toggles between the layouts defined in
|
||
@code{ecb-toggle-layout-sequence} (See also option
|
||
@code{ecb-show-sources-in-directories-buffer}). Note: This function
|
||
works by changing the options @code{ecb-layout-name} but only for
|
||
current Emacs-session.
|
||
|
||
If optional argument @var{LAST-ONE} is not nil (e.g. called with a
|
||
prefix-arg) then always the last selected layout was choosen
|
||
regardless of the setting in @code{ecb-toggle-layout-sequence}. The
|
||
last selected layout is always that layout which was current direct
|
||
before the most recent layout-switch. So now a user can switch to
|
||
another layout via `ecb-change-layout' and always come back to his
|
||
previous layout via @kbd{[C-u]} @code{ecb-toggle-layout}.
|
||
@end deffn
|
||
|
||
@deffn Command toggle-scroll-other-window-scrolls-compile &optional ARG
|
||
Toggle the state of
|
||
@code{ecb-scroll-other-window-scrolls-compile-window}. With prefix
|
||
argument @var{ARG}, set it to @code{t}, otherwise to @code{nil}. For
|
||
all details about the scroll-behavior of @code{scroll-other-window}
|
||
see the advice documentation of @code{other-window-for-scrolling}.
|
||
@end deffn
|
||
|
||
@deffn Command update-directories-buffer
|
||
Updates the ECB directories buffer.
|
||
@end deffn
|
||
|
||
@deffn Command upgrade-options
|
||
Check for all ECB-options if their current value is compatible to the
|
||
defined type. If not upgrade it to the new type or reset it to the
|
||
default-value of current ECB. Try also to upgrade renamed options.
|
||
Displays all upgraded or reset options with their old (before the
|
||
upgrade/reset) and new values.
|
||
@end deffn
|
||
|
||
@deffn Command window-sync
|
||
ynchronizes all special ECB-buffers with current buffer.
|
||
Depending on the contents of current buffer this command performs different
|
||
synchronizing tasks but only if ECB is active and point stays in an
|
||
edit-window.
|
||
|
||
@itemize
|
||
@item
|
||
If current buffer is a file-buffer (or an indirect-buffer with a file-buffer
|
||
as base-buffer) then all basic ECB-windows (directories, sources, methods and
|
||
history) are synchronized with current buffer.
|
||
|
||
@item
|
||
If current buffer is a dired-buffer then the directory- and
|
||
the sources-tree-buffer are synchronized if visible
|
||
@end itemize
|
||
|
||
In addition to this the hooks in @code{ecb-basic-buffer-sync-hook} run.
|
||
|
||
If optional argument ONLY-BASIC-WINDOWS is not nil then only the basic
|
||
tree-buffer directories, sources, methods and history are synchronized.
|
||
Otherwise all registered special ecb-buffers are synchronized too.
|
||
|
||
See @ref{ECB-window synchronizing}.
|
||
@end deffn
|
||
|
||
Most of these functions are also available via the menu ``ECB'' and
|
||
also via the ECB key-map with prefix @kbd{C-c .} (see
|
||
@code{ecb-minor-mode} for a complete list of the keybindings).
|
||
|
||
@node Customizing, Submitting problem report, Usage of ECB, Top
|
||
@chapter Customizing ECB
|
||
|
||
This chapter describes how to customize ECB for your personal taste.
|
||
The first section introduces some general aspects (which you should
|
||
really know!), the second one gives an overview of the most important
|
||
options and the third one lists all options of ECB (divided into the
|
||
customize groups).
|
||
|
||
@menu
|
||
* General aspects:: General aspects for customizing ECB
|
||
* Most important options:: Which option you must know
|
||
* Customizable options:: All customizable options of ECB
|
||
@end menu
|
||
|
||
@node General aspects, Most important options, Customizing, Customizing
|
||
@section General aspects for customizing ECB
|
||
|
||
This chapter contains all important informations you should know about
|
||
customizing ECB. The first section gives an answer to the question
|
||
``@code{setq} or @code{customize}'' and the second section describes
|
||
what to do when you have to customize ECB for a lot of people.
|
||
|
||
@menu
|
||
* setq or customize:: Should i use setq or customize?
|
||
* Site-wide customizing:: Site-wide customizing of ECB
|
||
@end menu
|
||
|
||
@node setq or customize, Site-wide customizing, General aspects, General aspects
|
||
@subsection Setq or customize - what should i use?
|
||
|
||
The best way to customize all the options of ECB is via the
|
||
customize-feature of (X)Emacs, i.e. means calling the commands
|
||
@code{customize-option} or @code{customize-group} etc. This is also
|
||
the strongly recommended way!
|
||
|
||
But you can also use @code{setq} or some Elisp-code to change the values of
|
||
many but not all of the options. The values of the following options
|
||
@strong{MUST NOT} be changed via @code{setq} or Elisp-code but only with the
|
||
customize-feature!
|
||
|
||
@itemize @minus
|
||
@item @code{ecb-analyse-buffer-sync-delay}
|
||
@item @code{ecb-analyse-show-node-info}
|
||
@item @code{ecb-basic-buffer-sync-delay}
|
||
@item @code{ecb-bucket-node-display}
|
||
@item @code{ecb-compile-window-height}
|
||
@item @code{ecb-compile-window-temporally-enlarge}
|
||
@item @code{ecb-compile-window-width}
|
||
@item @code{ecb-directories-show-node-info}
|
||
@item @code{ecb-eshell-buffer-sync-delay}
|
||
@item @code{ecb-exclude-parents-regexp}
|
||
@item @code{ecb-fix-window-size}
|
||
@item @code{ecb-font-lock-tags}
|
||
@item @code{ecb-highlight-tag-with-point-delay}
|
||
@item @code{ecb-history-show-node-info}
|
||
@item @code{ecb-key-map}
|
||
@item @code{ecb-layout-name}
|
||
@item @code{ecb-layout-window-sizes}
|
||
@item @code{ecb-methods-show-node-info}
|
||
@item @code{ecb-mode-line-data}
|
||
@item @code{ecb-mode-line-display-window-number}
|
||
@item @code{ecb-mode-line-prefixes}
|
||
@item @code{ecb-show-tags}
|
||
@item @code{ecb-source-path}
|
||
@item @code{ecb-sources-show-node-info}
|
||
@item @code{ecb-speedbar-buffer-sync-delay}
|
||
@item @code{ecb-symboldef-buffer-sync-delay}
|
||
@item @code{ecb-toggle-layout-sequence}
|
||
@item @code{ecb-tag-display-function}
|
||
@item @code{ecb-tree-do-not-leave-window-after-select}
|
||
@item @code{ecb-type-tag-display}
|
||
@item @code{ecb-type-tag-expansion}
|
||
@item @code{ecb-use-speedbar-instead-native-tree-buffer}
|
||
@item @code{ecb-windows-height}
|
||
@item @code{ecb-windows-width}
|
||
@end itemize
|
||
|
||
@node Site-wide customizing, , setq or customize, General aspects
|
||
@subsection Site-wide customizing of ECB
|
||
|
||
If you are the administrator for an Emacs-site, means you are
|
||
responsible for the basic customization of a lot of Emacs users, then
|
||
you maybe need a way to customize Emacs and ECB without changing
|
||
everyones @file{.emacs}-file and normally you will do this with the
|
||
file @file{site-start.el}. You can customize all options of ECB in a
|
||
central @file{site-start.el} (even the options mentioned above!) but
|
||
you @strong{MUST NOT} do this via @code{setq} but you have to use a
|
||
mechanism like the following@footnote{At least for the options for
|
||
which @code{setq} is explicitly forbidden, but it is recommended to
|
||
use always such a mechanism}!
|
||
|
||
This section describes two methods how to pre-customize ECB site-wide.
|
||
The elisp-code contained in the following two subsections has to be
|
||
copied to the file @file{site-start.el} before it can be used.
|
||
|
||
But ensure for both methods that you customize the options with the
|
||
correct lisp format. Read carefully the docstrings of the options you
|
||
want to customize from within Elisp-code!
|
||
|
||
@subsubsection Storing all option-settings in the users custom-file
|
||
|
||
The mechanism described here defines all site-wide-settings in a file
|
||
@file{site-lisp.el} but stores the values in the users
|
||
@code{custom-file} which is probably @file{.emacs}!
|
||
|
||
First two helper functions are needed, namely
|
||
@code{customize-option-get-value} and
|
||
@code{customize-save-variable-save} whereas the latter one sets the
|
||
value for an option via the customize-mechanism (and is therefore
|
||
allowed for the setq-forbidden options!) but only if the option has no
|
||
saved value until now (i.e. the user has not saved this option for
|
||
future sessions until now)
|
||
|
||
@example
|
||
@group
|
||
(defun customize-option-get-value (option type)
|
||
"Return the value of a customizable option OPTION with TYPE, where TYPE
|
||
can either be 'standard-value \(the default-value of the defcustom) or
|
||
'saved-value \(the value stored persistent by the user via customize)."
|
||
(let ((val (car (get option type))))
|
||
(cond ((not (listp val)) val)
|
||
((equal 'quote (car val)) (car (cdr val)))
|
||
(t (car val)))))
|
||
|
||
(defun customize-save-variable-save (option value &optional override)
|
||
"Calls `customize-save-variable' with OPTION and VALUE if OPTION is a
|
||
custom-type and if OPTION has no saved-value until now.
|
||
If OVERRIDE is a function or lambda-form then it is called with two arguments:
|
||
- OLD-SAVED-VAL: The saved value of OPTION
|
||
- NEW-VALUE: see argument VALUE.
|
||
OVERRIDE is only called if OPTION has already a saved-value. If OVERIDE
|
||
returns not nil then `customize-save-variable' is called for OPTION with VALUE
|
||
even if OPTION has no saved-value until now."
|
||
(and (get option 'custom-type)
|
||
(or (not (get option 'saved-value))
|
||
(and (functionp override)
|
||
(funcall override
|
||
(customize-option-get-value option 'saved-value)
|
||
value)))
|
||
(progn
|
||
(message "Overriding saved value for option %s with %s" option value)
|
||
(customize-save-variable option value))))
|
||
@end group
|
||
@end example
|
||
|
||
With @code{customize-save-variable-save} all ECB-options can be
|
||
site-wide pre-customized like follows:
|
||
|
||
@example
|
||
@group
|
||
(customize-save-variable-save 'ecb-show-tags
|
||
'((include collapsed nil)
|
||
(parent collapsed nil)
|
||
(type flattened nil)
|
||
(variable collapsed name)
|
||
(function flattened name)
|
||
(rule flattened name)
|
||
(section flattened nil)
|
||
(def collapsed name)
|
||
(t collapsed name)))
|
||
(customize-save-variable-save 'ecb-font-lock-tags t)
|
||
;; add here more options of ECB it you want
|
||
@end group
|
||
@end example
|
||
|
||
@subsubsection Using a special setq for site-wide settings
|
||
|
||
The mechanism above saves the pre-customized values always in the
|
||
users @code{custom-file} (probably @file{.emacs}). If this is not
|
||
preferred, then you can use the following mechanism but of course the
|
||
offered @code{setq-save} is only allowed for options which are not
|
||
setq-forbidden (@pxref{setq or customize}).
|
||
|
||
The mechanism below does not change the users @code{custom-file}. This
|
||
mechanism is needed especially if ECB should be autoloaded and all
|
||
site-wide settings should first loaded when ECB is activated by the
|
||
user. This can be achieved for example via@footnote{The file
|
||
@file{site-ecb.el} contains all site-wide settings for ECB}:
|
||
|
||
@example
|
||
@group
|
||
(require 'ecb-autoloads))
|
||
(eval-after-load "ecb"
|
||
'(require 'site-ecb))
|
||
@end group
|
||
@end example
|
||
|
||
In such a situation the whole @code{custom-file} of a user is mostly
|
||
loaded @strong{before} ECB is activated and therefore before the
|
||
site-wide-settings are loaded. So the users own customizations are
|
||
loaded before the site-wide ones.
|
||
|
||
The @code{setq-save}-mechanism described below prevents the users own
|
||
customisations contained in his @code{custom-file} from being
|
||
overridden by the site-wide setq-settings. If @code{setq} would be
|
||
used for the site-wide settings then in an autoload-situation the
|
||
site-wide settings would override the users-settings and this should
|
||
not be done!
|
||
|
||
First two helper-macros are needed:
|
||
|
||
@example
|
||
@group
|
||
(defmacro custom-saved-p (option)
|
||
"Return only not nil if OPTION is a defcustom-option and has a
|
||
saved value. Option is a variable and is literal \(not evaluated)."
|
||
`(and (get (quote ,option) 'custom-type)
|
||
(get (quote ,option) 'saved-value)))
|
||
|
||
(defmacro setq-save (option value)
|
||
"Sets OPTION to VALUE if and only if OPTION is not already saved
|
||
by customize. Option is a variable and is literal \(not evaluated)."
|
||
`(and (not (custom-saved-p ,option))
|
||
(set (quote ,option) ,value)))
|
||
@end group
|
||
@end example
|
||
|
||
With @code{setq-save} all ``not-setq-forbidden''-ECB-options can be
|
||
site-wide pre-customized like follows:
|
||
|
||
@example
|
||
@group
|
||
(setq-save ecb-tree-indent 4)
|
||
(setq-save ecb-tree-expand-symbol-before t)
|
||
(setq-save ecb-primary-secondary-mouse-buttons 'mouse-1--mouse-2)
|
||
@end group
|
||
@end example
|
||
|
||
@node Most important options, Customizable options, General aspects, Customizing
|
||
@section The most important options of ECB
|
||
|
||
Here are the most important options (it is recommended to check at
|
||
least the following options before working with ECB). You can
|
||
customize them via the customize-group ``ecb-most-important'' or via
|
||
the command @code{ecb-customize-most-important}.
|
||
|
||
@table @code
|
||
@item ecb-source-path
|
||
Where ECB can find your sources. You must set this option!
|
||
@item ecb-show-help-format
|
||
Should the online help of ECB be displayed in the standard Info format
|
||
or in HTML format in a web-browser.
|
||
@item ecb-auto-activate
|
||
@item ecb-major-modes-show-or-hide
|
||
Auto. activation of ECB after start (@pxref{Automatic activation}) or
|
||
major-mode-based showing or hiding the ecb-windows.
|
||
@item ecb-winman-escreen-number
|
||
@itemx ecb-winman-winring-name
|
||
Support of several window-managers (@pxref{Window-managers and ECB}).
|
||
@item ecb-key-map
|
||
All ECB-keybindings incl. a common prefix-key (@pxref{Using the
|
||
keyboard}).
|
||
@item ecb-new-ecb-frame
|
||
Should ECB create a new frame at activation time.
|
||
@item ecb-primary-secondary-mouse-buttons
|
||
@itemx ecb-mouse-click-destination
|
||
Define how to use the mouse (@pxref{Using the mouse}).
|
||
@item ecb-tree-buffer-style
|
||
@itemx ecb-tree-expand-symbol-before
|
||
@itemx ecb-tree-indent
|
||
@itemx ecb-truncate-lines
|
||
The look&feel of the trees in the tree-buffers. The former option
|
||
defines the general style of the tree-buffers and the latter ones
|
||
allow to customize the ascii-style tree-buffers (maybe you like a
|
||
value of 4 for the latter one if you display the expand-symbol before
|
||
(@pxref{Tree-buffer styles}).
|
||
@item ecb-source-file-regexps
|
||
Which files will (not) be shown in ECB.
|
||
@item ecb-layout-name
|
||
@itemx ecb-compile-window-height
|
||
@itemx ecb-compile-window-width
|
||
@itemx ecb-other-window-behavior
|
||
The ECB layout, means which windows you want to be displayed in the
|
||
ECB-frame and also the location of these windows (@pxref{Changing the
|
||
ECB-layout}).
|
||
@item ecb-compilation-buffer-names
|
||
Which buffers should be treaten as ``compilation-buffers'' and
|
||
therefore displayed in the compile-window of ECB - if there is any.
|
||
@item ecb-tag-display-function
|
||
@itemx ecb-type-tag-display
|
||
@itemx ecb-type-tag-expansion
|
||
@itemx ecb-show-tags
|
||
How to display the entries in the ECB-method window for semantic
|
||
supported sources (@pxref{Customizing the display}). These options
|
||
take only effect for semantic-sources (@pxref{Definition of semantic-
|
||
and non-semantic-sources}).
|
||
@item ecb-process-non-semantic-files
|
||
Displaying file-contents for not by semantic supported files too, e.g.
|
||
for LaTeX- and perl-sources (@pxref{Non-semantic sources}).
|
||
@end table
|
||
|
||
But to make ECB working best for you it is also recommended to have a
|
||
look at @ref{Customizable options}!
|
||
|
||
@node Customizable options, ,Most important options, Customizing
|
||
@section All customizable options of ECB
|
||
|
||
@noindent
|
||
All customization of ECB is divided into the following ``customize
|
||
groups''. You can highly customize all the ECB behavior/layout so just
|
||
go to these groups and you will see all well documented ECB-options.
|
||
|
||
@strong{Please note}: All options in the following subsections are
|
||
listed without the prefix ``ecb-'' (e.g. the option
|
||
@code{ecb-layout-name} is listed with name ``layout-name''). This has
|
||
been done for a better readable option index. @xref{Option Index}.
|
||
|
||
@menu
|
||
* ecb-general:: General customizing ECB
|
||
* ecb-tree-buffer:: Customizing the general tree layout
|
||
* ecb-directories:: Customizing the ECB-directories-tree
|
||
* ecb-sources:: Customizing the ECB-sources-window
|
||
* ecb-methods:: Customizing the ECB-methods-window
|
||
* ecb-history:: Customizing the ECB-history-window
|
||
* ecb-analyse:: Customizing the ECB-analyse-window
|
||
* ecb-symboldef:: Customizing the ECB-symboldef-window
|
||
* ecb-layout:: Customizing the ECB-layout
|
||
* ecb-compilation:: Customizing the compile-window
|
||
* ecb-create-layout:: Customizing options for creating layouts
|
||
* ecb-face-options:: Customizing options for faces
|
||
* ecb-faces:: Customizing the faces
|
||
* ecb-help:: Customizing the online help of ECB
|
||
* ecb-eshell:: Customizing the eshell-integration
|
||
* ecb-speedbar:: Customizing the speedbar-integration
|
||
* ecb-non-semantic:: Customizing parsing non-semantic sources
|
||
* ecb-winman:: Customizing window-manager support
|
||
* ecb-mode-line:: Customizing the tree-buffer-modelines
|
||
* ecb-version-control:: Customizing the version-control-support
|
||
@end menu
|
||
|
||
@node ecb-general, ecb-tree-buffer, Customizable options, Customizable options
|
||
@subsection Group ecb-general
|
||
|
||
@noindent
|
||
This group contains general settings for the Emacs code browser:
|
||
|
||
@defopt activate-before-layout-draw-hook
|
||
Normal hook run at the end of activating the ecb-package by running
|
||
@code{ecb-activate}. This hooks are run after all the internal setup
|
||
process but directly before(!) drawing the layout specified in
|
||
@code{ecb-layout} (means before dividing the frame into several
|
||
windows).
|
||
|
||
A senseful using of this hook can be maximizing the Emacs-frame for
|
||
example, because this should be done before the layout is drawn
|
||
because ECB computes the size of the ECB-windows with the current
|
||
frame size! If you need a hook-option for the real end of the
|
||
activating process (i.e. after the layout-drawing) look at
|
||
@code{ecb-activate-hook}.
|
||
|
||
IMPORTANT: The difference between this hook and
|
||
@code{ecb-redraw-layout-before-hook} is that the latter one is
|
||
evaluated always before the layout is redrawn (for example after
|
||
calling @code{ecb-redraw-layout}) whereas the former one (this hook)
|
||
is only evaluated exactly once during the activation-process of ECB.
|
||
So during the activation process there is the following sequence of
|
||
hooks:
|
||
@enumerate
|
||
@item @code{ecb-activate-before-layout-draw-hook} \(this one)
|
||
@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
|
||
@end defopt
|
||
|
||
@defopt activate-hook
|
||
Hook run at the end of activating ECB by @code{ecb-activate}. This
|
||
hooks are run at the real end of the activating process, means after
|
||
the layout has been drawn!. If you need hooks which are run direct
|
||
before the layout-drawing look at
|
||
@code{ecb-activate-before-layout-draw-hook}.
|
||
@end defopt
|
||
|
||
@defopt activation-selects-ecb-frame-if-already-active
|
||
Trying to activate an already activated ECB selects the ECB-frame. If
|
||
t then the ECB-frame is selected, if nil then it is not. If 'ask then
|
||
ECB asks if the ECB-frame should be selected if the current-frame is
|
||
not the @code{ecb-frame}.
|
||
@end defopt
|
||
|
||
@defopt auto-activate
|
||
Automatically startup ECB when Emacs starts up. This should only be
|
||
true if you always want to run @code{ecb-activate}.
|
||
@end defopt
|
||
|
||
@defopt auto-compatibility-check
|
||
Check at ECB-startup if all ECB-options have correct values. If not
|
||
nil then all ECB-options are checked if their current value have the
|
||
correct type. It the type is incorrect the option is either auto.
|
||
upgraded to the new type or reset to the default-value of current ECB
|
||
if no upgrade is possible. This feature can also upgrade options which
|
||
are renamed in current ECB and try to transform the old-value to the
|
||
new named option. After startup all upgraded or reset options are
|
||
displayed with their old (before upgrade/reset) and new values. See
|
||
also the commands @code{ecb-upgrade-options} and
|
||
@code{ecb-display-upgraded-options}. If this option is off then the
|
||
user can perform the check and reset manually with
|
||
@code{ecb-upgrade-options}.
|
||
@xref{Auto. option-upgrading}.
|
||
@end defopt
|
||
|
||
@defopt before-activate-hook
|
||
Normal hook run at the beginning of activating the ecb-package by
|
||
running @code{ecb-activate}. These hooks run before any other tasks of
|
||
the activating process are performed. If any of these hooks returns
|
||
nil then ECB will not be activated!
|
||
|
||
This can be used to check some conditions and then only start ECB if
|
||
all conditions are true. For example a function could be added which
|
||
returns only nil if Gnus is running. Then calling @code{ecb-activate}
|
||
or @code{ecb-minor-mode} will only start ECB if Gnus is not already
|
||
running.
|
||
@end defopt
|
||
|
||
@defopt before-deactivate-hook
|
||
Normal hook run at the beginning of deactivating ECB by running
|
||
@code{ecb-deactivate}. These hooks run before any other tasks of the
|
||
deactivating process are performed. If any of these hooks returns nil
|
||
then ECB will not be deactivated! See also
|
||
@code{ecb-before-activate-hook}.
|
||
@end defopt
|
||
|
||
@defopt bucket-node-display
|
||
How ECB displays bucket-nodes in a ECB tree-buffer. Bucket-nodes have
|
||
only one job: Nodes with similar properties will be dropped into one
|
||
bucket for such a common property and all these nodes will be added as
|
||
children to the bucket-node. Besides being expandable and collapsable
|
||
a bucket-node has no senseful action assigned. Examples for
|
||
bucket-nodes are ``[+] Variables, ``[+] Dependencies'' etc. in the
|
||
Methods-buffer or buckets which combine filenames with same extension
|
||
under a bucket-node with name this extension.
|
||
|
||
This option defines how bucket-node should be displayed. The name of
|
||
the bucket-node is computed by ECB but you can define a prefix, a
|
||
suffix and a special face for the bucket-node
|
||
|
||
The default are empty prefix/suffix-strings and
|
||
@code{ecb-bucket-node-face}. But an alternative can be for example
|
||
'(``['' ``]'' nil) which means no special face and a display like
|
||
``[+] [<bucket-name>]''.
|
||
@end defopt
|
||
|
||
|
||
@defopt clear-caches-before-activate
|
||
Clear all ECB internal caches before startup. If t then ECB clears all
|
||
its internal caches before starting up. Caches are used for files- and
|
||
subdirs (see @code{ecb-cache-directory-contents} and
|
||
@code{ecb-cache-directory-contents-not}) for semantic-tags and for
|
||
the history-filter.
|
||
|
||
This caches are completely clean at load-time of the ECB-library!
|
||
|
||
Default is nil, because is makes sense not to clear these caches at
|
||
start-time because ECB is often deacticated temporally especially in
|
||
combination with window-managers like escreen.el. In these situations
|
||
the internal state of ECB should be preserved for next activation.
|
||
@end defopt
|
||
|
||
|
||
@defopt deactivate-hook
|
||
Normal hook run at the end of deactivating (but before the ecb-layout
|
||
is cleared!) ECB by running @code{ecb-deactivate}.
|
||
@end defopt
|
||
|
||
@defopt debug-mode
|
||
If not nil ECB displays debug-information in the Messages-buffer. This
|
||
is done for some critical situations concerning semantic-tags and
|
||
their overlays (or extends for XEmacs). Normally you should not need
|
||
this switched on! But if you get errors like ``destroyed extend'' for
|
||
XEmacs or ``wrong-argument-type'' concerning overlays for GNU Emacs then
|
||
you should switch on this option and submitting a bug-report to the
|
||
ecb-mailing-list (@code{ecb-submit-problem-report}) after getting the
|
||
error again!
|
||
@end defopt
|
||
|
||
@defopt grep-function
|
||
Function used for performing a grep. The popup-menu of the
|
||
tree-buffers ``Directories'', ``Sources'' and ``History'' offer to
|
||
grep the ``current'' directory:
|
||
@itemize @minus
|
||
@item
|
||
Directory-buffer: The grep is performed in the current popup-directory
|
||
after clicking the right mouse-button onto a node.
|
||
@item
|
||
Sources-buffer: The grep is performed in the current selected directory.
|
||
@item
|
||
History-buffer: The grep is performed in the directory of the current
|
||
popup-source after clicking the right mouse-button onto a node.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt grep-recursive-function
|
||
Function used for performing a recursive grep. For more Details see
|
||
option `ecb-grep-function' and replace ``grep'' with ``recursive
|
||
grep''.
|
||
@end defopt
|
||
|
||
@defopt key-map
|
||
Specifies all keybindings for the ECB minor-mode key-map. The value is
|
||
a cons-cell where the car is a common-prefix key for all the
|
||
keybindings. The cdr is a list of keybindings each of them a list
|
||
again. A key-binding has the following form:
|
||
|
||
@example
|
||
'(<common-prefix-flag> <keysequence> <function>) where
|
||
@end example
|
||
|
||
@table @code
|
||
@item <common-prefix-flag>
|
||
If t then the common-prefix-key defined as car of the value (see above)
|
||
is used.
|
||
|
||
@item <keysequence>
|
||
If the common prefix-key is used then the final key-binding is the
|
||
concatenation of the common-prefix-key (see above) and this
|
||
keysequence.
|
||
|
||
@item <function>:
|
||
The function to bind to the key. This can also be a lambda-expression
|
||
.
|
||
@end table
|
||
|
||
It is highly recommended to use one of the standard keys C-c or C-x as
|
||
first key of your common-prefix-key!
|
||
|
||
You MUST change this option via customize to take effect!
|
||
|
||
All keysequences must be inserted as a string and must follow the
|
||
syntax needed by @code{read-kbd-macro} or @code{kbd}. This means you
|
||
can insert the key in the same manner @kbd{C-h k} displays keysequences.
|
||
Here is the summary of the syntax:
|
||
|
||
Text is divided into ``words'' separated by whitespace. Except for the words
|
||
described below, the characters of each word go directly as characters of the
|
||
keysequence. The whitespace that separates words is ignored. Whitespace in the
|
||
macro must be written explicitly, as in @kbd{C-c SPC}.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The special words RET, SPC, TAB, DEL, LFD, ESC, and NUL represent
|
||
special control characters. The words must be written in uppercase.
|
||
|
||
@item
|
||
A word in angle brackets, e.g., <return>, <down>, <left> or <f1>,
|
||
represents a function key. (Note that in the standard configuration,
|
||
the function key <return> and the control key RET are synonymous.).
|
||
You can use angle brackets on the words RET, SPC, etc., but they are
|
||
not required there.
|
||
|
||
@item
|
||
Keys can be written by their ASCII code, using a backslash followed by
|
||
up to six octal digits. This is the only way to represent keys with
|
||
codes above <20>.
|
||
|
||
@item
|
||
One or more prefixes M- (meta), C- (control), S- (shift), A- (alt), H-
|
||
(hyper), and s- (super) may precede a character or key notation. For
|
||
function keys, the prefixes may go inside or outside of the brackets:
|
||
C-<down> = <C-down>. The prefixes may be written in any order: M-C-x =
|
||
C-M-x. Prefixes are not allowed on multi-key words, e.g., C-abc,
|
||
except that the Meta prefix is allowed on a sequence of digits and
|
||
optional minus sign: M--123 = M-- M-1 M-2 M-3.
|
||
|
||
@item
|
||
The @code{^} notation for control characters also works: ^M = C-m.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt major-modes-show-or-hide
|
||
List of major-modes which show or hide the ecb-windows. The value is a
|
||
cons-cell where the car contains all major-mode-symbols which should
|
||
show the special ecb-windows and the cdr contains all
|
||
major-mode-symbols which should hide the special ecb-windows. If the
|
||
symbol of a major-mode is neither contained in the car-``show-list''
|
||
nor in the cdr-``hide-list'' then the visibility-state of the
|
||
ecb-windows does not change.
|
||
@end defopt
|
||
|
||
|
||
@defopt minor-mode-text
|
||
String to display in the mode line when ECB minor mode is active.
|
||
(When the string is not empty, make sure that it has a leading space.)
|
||
|
||
Because for ECB it is quite obvious if it is active or not when the
|
||
ECB-windows are visible this text is only display in the modeline if
|
||
the ECB-windows are hidden.
|
||
@end defopt
|
||
|
||
|
||
@defopt run-ediff-in-ecb-frame
|
||
Run ediff-sessions in the same frame as ECB is running.
|
||
If not nil then ECB ensures that ediff runs in the same frame as ECB and ECB
|
||
restores exactly the ``before-ediff''-window-layout after quiting ediff. If
|
||
nil then ediff decides in which frame it will run - depending on the current
|
||
window-layout (e.g. if the ecb-windows are currently hidden) this can be the
|
||
ecb-frame but this can also be a newly created frame or any other frame.
|
||
@end defopt
|
||
|
||
@defopt stealthy-tasks-delay
|
||
Time Emacs must be idle before ECB runs its stealthy tasks. Currently
|
||
ECB performes the following stealthy tasks:
|
||
|
||
@table @asis
|
||
@item Prescann directories for emptyness
|
||
Prescann directories and display them as empty or not-empty in the
|
||
directories-buffer. See the documentation of the option
|
||
@code{ecb-prescan-directories-for-emptyness} for a description.
|
||
|
||
@item File is read only
|
||
Check if sourcefile-items of the directories- or sources-buffer are
|
||
read-only or not. See documentation of the option
|
||
@code{ecb-sources-perform-read-only-check}.
|
||
|
||
@item Version-control-state
|
||
Checks the version-control-state of files in directories which are
|
||
managed by a VC-backend. See the option @code{ecb-vc-enable-support}.
|
||
|
||
@end table
|
||
|
||
Here the interval is defined ECB has to be idle before starting with
|
||
these stealthy tasks. It can be a floating-point value in seconds. The
|
||
value can also be changed during running ECB.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt tip-of-the-day
|
||
Show tip of the day at start time of ECB.
|
||
@end defopt
|
||
|
||
@defopt tip-of-the-day-file
|
||
File where tip-of-the-day cursor is stored.
|
||
@end defopt
|
||
|
||
@defopt use-recursive-edit
|
||
Tell ECB to use a recursive edit. If set then it can easily be
|
||
deactivated by (keyboard-escape-quit).
|
||
@end defopt
|
||
|
||
@defopt version-check
|
||
Checks at start-time if the requirements are fulfilled. It checks if the
|
||
required versions of CEDET is installed and loaded into Emacs.
|
||
|
||
It is strongly recommended to set this option to not @code{nil}!
|
||
@end defopt
|
||
|
||
|
||
@node ecb-tree-buffer, ecb-directories, ecb-general, Customizable options
|
||
@subsection Group ecb-tree-buffer
|
||
|
||
@noindent
|
||
This group contains general settings related to the tree-buffers of
|
||
ECB:
|
||
|
||
@defopt basic-buffer-sync
|
||
Synchronize the basic ECB-buffers automatically with current edit buffer.
|
||
|
||
The basic ECB-buffers are the buffers for directories, sources, methods and
|
||
history.
|
||
|
||
If 'always then the synchronization takes place always a buffer changes in the
|
||
edit window, if nil then never. If a list of major-modes then only if the
|
||
@code{major-mode} of the new buffer belongs NOT to this list.
|
||
|
||
But in every case the synchronization takes only place if the current-buffer
|
||
in the edit-window has a relation to files or directories. Examples for the
|
||
former one are all programming-language-modes, @code{Info-mode} too, an
|
||
example for the latter one is @code{dired-mode}. For all major-modes related
|
||
to non-file/directory-buffers like @code{help-mode}, @code{customize-mode} and
|
||
others never an autom. synchronization will be done!
|
||
|
||
It's recommended to exclude at least @code{Info-mode} because it makes no
|
||
sense to synchronize the ECB-windows after calling the Info help. Per default
|
||
also @code{dired-mode} is excluded but it can also making sense to synchronize
|
||
the ECB-directories/sources windows with the current directory in the
|
||
dired-buffer.
|
||
|
||
IMPORTANT NOTE: Every time the synchronization is done the hook
|
||
@code{ecb-basic-buffer-sync-hook} is evaluated.
|
||
@end defopt
|
||
|
||
@defopt basic-buffer-sync-delay
|
||
Time Emacs must be idle before the special ECB-buffers are synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately. A
|
||
small value of about 0.25 seconds saves CPU resources and you get even though
|
||
almost the same effect as if you set no delay.
|
||
@end defopt
|
||
|
||
@defopt basic-buffer-sync-hook
|
||
Hook run at the end of @code{ecb-basic-buffer-sync}.
|
||
See documentation of @code{ecb-basic-buffer-sync} for conditions when
|
||
synchronization takes place and so in turn these hooks are evaluated.
|
||
|
||
Precondition for such a hook:
|
||
Current buffer is the buffer of the currently selected edit-window.
|
||
|
||
Postcondition for such a hook:
|
||
Point must stay in the same edit-window as before evaluating the hook.
|
||
|
||
Important note: If the option @code{ecb-basic-buffer-sync} is not nil
|
||
the function @code{ecb-basic-buffer-sync} is running either every time
|
||
Emacs is idle or even after every command (see
|
||
@code{ecb-basic-buffer-sync-delay}). So these hooks can be really
|
||
called very often! Therefore each function of this hook
|
||
should/must check in an efficient way at beginning if its task
|
||
have to be really performed and then do them only if really
|
||
necessary! Otherwise performance of Emacs could slow down
|
||
dramatically!
|
||
|
||
It is strongly recommended that each function added to this hook uses the
|
||
macro @code{ecb-do-if-buffer-visible-in-ecb-frame} at beginning! See
|
||
@code{ecb-speedbar-buffer-sync} and @code{ecb-eshell-buffer-sync} for
|
||
examples how to use this macro!
|
||
@end defopt
|
||
|
||
@defopt bucket-node-display
|
||
How ECB displays bucket-nodes in a ECB tree-buffer.
|
||
Bucket-nodes have only one job: Nodes with similar properties will be dropped
|
||
into one bucket for such a common property and all these nodes will be added
|
||
as children to the bucket-node. Besides being expandable and collapsable a
|
||
bucket-node has no senseful action assigned. Examples for bucket-nodes are
|
||
''[+] Variables'', ``[+] Dependencies'' etc. in the Methods-buffer or buckets
|
||
which combine filenames with same extension under a bucket-node with name this
|
||
extension.
|
||
|
||
This option defines how bucket-node should be displayed. The name of the
|
||
bucket-node is computed by ECB but you can define a prefix, a suffix and a
|
||
special face for the bucket-node
|
||
|
||
The default are empty prefix/suffix-strings and @code{ecb-bucket-node-face}. But
|
||
an alternative can be for example '(''['' ``]'' nil) which means no special
|
||
face and a display like ``[+] [<bucket-name>]''.
|
||
@end defopt
|
||
|
||
|
||
@defopt common-tree-buffer-after-create-hook
|
||
Local hook running at the end of each tree-buffer creation. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating a tree-buffer of ECB and it's local key-map. So for example a
|
||
function could be added which performs calls of @code{local-set-key}
|
||
to define new keybindings for EVERY tree-buffer.
|
||
|
||
The following keys must not be rebind in all tree-buffers:
|
||
@itemize @minus
|
||
@item @kbd{RET} and all combinations with @kbd{Shift} and @kbd{Ctrl}
|
||
@item @kbd{TAB}
|
||
@item @code{C-t}
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt mouse-click-destination
|
||
Destination of a mouse-button click. Defines in which edit-window (if
|
||
splitted) ECB does the ``right'' action (opening a source, jumping to
|
||
a method/variable etc.) after clicking with the primary mouse-button
|
||
(see @code{ecb-primary-secondary-mouse-buttons}) onto a node. There
|
||
are two possible choices:
|
||
|
||
@itemize @minus
|
||
@item @code{left-top}:
|
||
Does the ``right'' action always in the left/topmost edit-window.
|
||
@item @code{last-point}:
|
||
Does the ``right'' action always in that edit-window which had the point
|
||
before.
|
||
@end itemize
|
||
This is if the user has clicked either with the primary mouse-button or
|
||
has activated a popup-menu in the tree-buffer.
|
||
|
||
If the edit-area is not splitted this setting doesn't matter.
|
||
|
||
A click with the secondary mouse-button (see again
|
||
@code{ecb-primary-secondary-mouse-buttons} does the ``right'' action
|
||
always in another edit-window related to the setting in this option:
|
||
If there are two edit-windows then the ``other'' edit-window is used
|
||
and for more than 2 edit-windows the ``next'' edit-window is used
|
||
(whereas the next edit-window of the last edit-window is the first
|
||
edit-window).
|
||
|
||
Note: If the tree-buffers are used with the keyboard instead with the
|
||
mouse then this option takes effect too because @kbd{RET} is
|
||
interpreted as primary mouse-button and @kbd{C-RET} as secondary
|
||
mouse-button!
|
||
@end defopt
|
||
|
||
|
||
@defopt primary-secondary-mouse-buttons
|
||
Primary- and secondary mouse button for using the ECB-buffers. A click
|
||
with the primary button causes the main effect in each ECB-buffer:
|
||
|
||
@itemize @bullet
|
||
@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
|
||
|
||
A click with the primary mouse-button while the SHIFT-key is pressed called
|
||
the POWER-click and does the following (depending on the ECB-buffer where the
|
||
POWER-click occurs):
|
||
|
||
@itemize @bullet
|
||
@item ECB Directories:
|
||
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 the edit-window.
|
||
|
||
@item ECB Methods:
|
||
Narrowing to the clicked method/variable/ect... (see
|
||
@code{ecb-tag-visit-post-actions}). This works only for semantic
|
||
supported sources but not for imenu- or etags-supported ones!
|
||
@end itemize
|
||
|
||
In addition always the whole node-name is displayed in the minibuffer after a
|
||
POWER-click (for this see also @code{ecb-methods-show-node-info}).
|
||
|
||
The secondary mouse-button is for opening (jumping to) the file in
|
||
another edit-window (see the documentation
|
||
@code{ecb-mouse-click-destination}).
|
||
|
||
The following combinations are possible:
|
||
|
||
@itemize @minus
|
||
@item
|
||
primary: mouse-2, secondary: C-mouse-2 (means mouse-2 while CTRL-key is
|
||
pressed). This is the default setting.
|
||
@item
|
||
primary: mouse-1, secondary: C-mouse-1
|
||
@item
|
||
primary: mouse-1, secondary: mouse-2
|
||
@end itemize
|
||
|
||
Please note: If the tree-buffers are used with the keyboard instead
|
||
with the mouse then @kbd{RET} is interpreted as primary mouse-button and
|
||
@kbd{C-RET} as secondary mouse-button!
|
||
|
||
If you change this during ECB is activated you must deactivate and
|
||
activate ECB again to take effect
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt tree-buffer-style
|
||
The style of the tree-buffers.
|
||
There are three different styles available:
|
||
|
||
Image-style (value @code{image}): Very nice and modern - just try it. For this
|
||
style the options @code{ecb-tree-indent} and
|
||
@code{ecb-tree-expand-symbol-before} have no effect! The value 'image means
|
||
use image-style if images can be displayed with current Emacs-setup
|
||
\(otherwise auto. 'ascii-style is used). Note: GNU Emacs <= 21.3.X for Windows
|
||
does not support image-display so ECB uses always 'ascii-guides even when here
|
||
'image is set!
|
||
|
||
Ascii-style with guide-lines (value @code{ascii-guides}):
|
||
@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
|
||
|
||
With both ascii-styles the tree-layout can be affected with the
|
||
options @code{ecb-tree-indent} and
|
||
@code{ecb-tree-expand-symbol-before}.
|
||
@end defopt
|
||
|
||
@defopt tree-do-not-leave-window-after-select
|
||
Tree-buffers which stay selected after a key- or mouse-selection. If a
|
||
buffer (either its name or the variable-symbol which holds the name)
|
||
is contained in this list then selecting a tree-node either by RET or
|
||
by a mouse-click doesn't leave that tree-buffer after the
|
||
node-selection but performes only the appropriate action (opening a
|
||
new source, selecting a method etc.) but point stays in the
|
||
tree-buffer. In tree-buffers not contained in this option normaly a
|
||
node-selection selects as ``last'' action the right edit-window or
|
||
maximizes the next senseful tree-buffer in case of a currently
|
||
maximized tree-buffer (see
|
||
@code{ecb-maximize-next-after-maximized-select}).
|
||
|
||
The buffer-name can either be defined as plain string or with a symbol
|
||
which contains the buffer-name as value. The latter one is recommended
|
||
for the builtin ECB-tree-buffers because then simply the related
|
||
option-symbol can be used.
|
||
|
||
A special remark for the @code{ecb-directories-buffer-name}: Of course
|
||
here the value of this option is only relevant if the name of the
|
||
current layout is contained in
|
||
@code{ecb-show-sources-in-directories-buffer} or if the value of
|
||
@code{ecb-show-sources-in-directories-buffer} is 'always and the
|
||
clicked ot hitted node represents a sourcefile (otherwise this would
|
||
not make any sense)!
|
||
|
||
The setting in this option is only the default for each tree-buffer.
|
||
With the command @code{ecb-toggle-do-not-leave-window-after-select}
|
||
the behavior of a node-selection can be changed fast and easy in a
|
||
tree-buffer without customizing this option, but of course not for
|
||
future Emacs sessions!
|
||
@end defopt
|
||
|
||
|
||
@defopt tree-easy-hor-scroll
|
||
Scroll step for easy hor. scrolling via mouse-click in tree-buffers.
|
||
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.
|
||
|
||
If this option is a positive integer S then in all ECB-tree-buffers
|
||
the keys @kbd{M-mouse-1} and @code{M-mouse-3} are bound to scrolling
|
||
left rsp. right with scroll-step S - clicking with @kbd{mouse-1} or
|
||
@kbd{mouse-2} onto the edge of the modeline has the same effect, i.e.
|
||
if you click with mouse-1 onto the left (rsp right) edge of the
|
||
modeline you will scroll left (rsp. right).
|
||
|
||
Additionally @code{C-M-mouse-1} and @code{C-M-mouse-3} are bound to
|
||
scrolling left rsp. right with scroll-step @code{window-width} - 2.
|
||
|
||
Default is a scroll-step of 5. If the value is @code{nil} then no keys
|
||
for horizontal scrolling are bound.
|
||
@end defopt
|
||
|
||
@defopt tree-expand-symbol-before
|
||
Show the expand symbol before the items in a tree. When the
|
||
expand-symbol is located before the items then the tree looks like:
|
||
|
||
@example
|
||
@group
|
||
[-] ECB
|
||
[+] code-save
|
||
[-] ecb-images
|
||
[-] directories
|
||
@end group
|
||
@end example
|
||
|
||
When located after then the tree looks like:
|
||
|
||
@example
|
||
@group
|
||
ECB [-]
|
||
code-save [+]
|
||
ecb-images [-]
|
||
directories [-]
|
||
@end group
|
||
@end example
|
||
|
||
The after-example above use a value of 2 for @code{ecb-tree-indent}
|
||
whereas the before-example uses a value of 4.
|
||
|
||
It is recommended to display the expand-symbol before because
|
||
otherwise it could be that with a deep nested item-structure with
|
||
and/or with long item-names (e.g. a deep directory-structure with some
|
||
long subdirectory-names) the expand-symbol is not visible in the
|
||
tree-buffer and the tree-buffer has to be horizontal scrolled to
|
||
expand an item.
|
||
@end defopt
|
||
|
||
@defopt tree-image-icons-directories
|
||
Directories where the images for the tree-buffer can be found. This is
|
||
a cons cell where:
|
||
|
||
car: Default directory where the default images for the tree-buffer
|
||
can be found. It should contain an image for every name of
|
||
@code{tree-buffer-tree-image-names}. The name of an image-file must
|
||
be: ``ecb-<NAME of TREE-BUFFER-TREE-IMAGE-NAMES>.<ALLOWED
|
||
EXTENSIONS>''.
|
||
|
||
cdr: This is a list where each element is a cons again with: car is
|
||
the buffer name of the tree-buffer for which a special image-path
|
||
should be used. The buffer-name can either be defined as plain string
|
||
or with a symbol which contains the buffer-name as value. The latter
|
||
one is recommended for the builtin ECB-tree-buffers because then
|
||
simply the related option-symbol can be used (e.g. the symbol
|
||
@code{ecb-directories-buffer-name}). The cdr is the the full-path of
|
||
an additional image-directorie which is searched first for images
|
||
needed for the related tree-buffer. If the image can not be found in
|
||
this directory then the default-directory (see above) is searched. If
|
||
the image can't even be found there the related ascii-symbol is used -
|
||
which is defined in @code{tree-buffer-tree-image-names}. If a
|
||
tree-buffer is not contained in this list then there is no additional
|
||
special image-directory for it.
|
||
|
||
ECB comes with predefined images in several different heights - so for
|
||
the most senseful font-heights of a tree-buffer a fitting image-size
|
||
should be available. The 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 (locate-data-directory ``ecb'').
|
||
@end defopt
|
||
|
||
|
||
@defopt tree-incremental-search
|
||
Enable incremental search in the ECB-tree-buffers. For a detailed
|
||
explanation see the online help section ``Working with the keyboard in
|
||
the ECB buffers''. If you change this during ECB is activated you must
|
||
deactivate and activate ECB again to take effect.
|
||
@end defopt
|
||
|
||
@defopt tree-indent
|
||
Indent size for tree buffer. If you change this during ECB is
|
||
activated you must deactivate and activate ECB again to take effect.
|
||
@end defopt
|
||
|
||
@defopt tree-make-parent-node-sticky
|
||
Make the parent-node sticky in the headerline of the tree-buffer.
|
||
|
||
If not nil then the first line of the tree-buffer is used as header-line which
|
||
is used to display the next unvisible parent of the first visible node as
|
||
sticky, so always the parent of a node is visible and clickable. If a node has
|
||
no parent then just the next node above is displayed in the header-line. The
|
||
node displayed in the header-line is exactly in the same manner clickable as
|
||
all other nodes.
|
||
|
||
See also @code{ecb-tree-stickynode-indent-string}.
|
||
|
||
This feature is only available with Gnu Emacs, not with XEmacs.
|
||
@end defopt
|
||
|
||
@defopt tree-mouse-action-trigger
|
||
When the tree-buffer mouse-action should be triggered. This option
|
||
determines the moment a mouse-action in a tree-buffer is triggered.
|
||
This can be either direct after pressing a mouse-button (value
|
||
@code{button-press}) or not until releasing the mouse-button (value:
|
||
@code{button-release}).
|
||
|
||
If you change this during ECB is activated you must deactivate and
|
||
activate ECB again to take effect!
|
||
@end defopt
|
||
|
||
|
||
@defopt tree-navigation-by-arrow
|
||
Enable smart navigation in the tree-windows by horiz. arrow-keys. If
|
||
not nil then the left- and right-arrow keys work in the ECB
|
||
tree-window in the following smart way if onto an expandable node:
|
||
|
||
@itemize @bullet
|
||
@item Left-arrow:
|
||
If node is expanded then it will be collapsed otherwise point jumps to
|
||
the next ``higher'' node in the hierarchical tree (higher means the next
|
||
higher tree-level or - if no higher level available - the next higher
|
||
node on the same level).
|
||
|
||
@item Right-arrow:
|
||
If node is not expanded then it will be expanded. Onto a not
|
||
expandable node the horizontal arrow-keys go one character in the
|
||
senseful correct direction.
|
||
@end itemize
|
||
|
||
If this option is changed the new value takes first effect after deactivating
|
||
ECB and then activating it again!
|
||
@end defopt
|
||
|
||
@defopt tree-stickynode-indent-string
|
||
String used to indent the stickynode.
|
||
This string is used to match the space used by scrollbars and
|
||
fringe so it does not appear that the node-name is moving left/right
|
||
when it lands in the sticky line.
|
||
|
||
Normally the needed value is computed automatically by ECB. But if the result
|
||
is not matching this option allows to customize the indent-string. The default
|
||
value is computed by the function
|
||
@code{tree-buffer-sticky-default-indent-string}, so you can change the needed
|
||
value with that starting-point.
|
||
|
||
Changing this option takes only effect after restarting Emacs!
|
||
@end defopt
|
||
|
||
@defopt tree-truncate-lines
|
||
Truncate lines in ECB buffers. If a buffer (either its name or the
|
||
variable-symbol which holds the name) is contained in this list then
|
||
line-truncation is switched on for this buffer otherwise it is off.
|
||
|
||
The buffer-name can either be defined as plain string or with a symbol
|
||
which contains the buffer-name as value. The latter one is recommended
|
||
to switch on line-truncation for one of the builtin ECB-tree-buffers
|
||
because then simply the related option-symbol can be used. To truncate
|
||
lines in the builtin directories tree-buffer just add the symbol
|
||
@code{ecb-directories-buffer-name} to this option.
|
||
|
||
If you change this during ECB is activated you must deactivate and
|
||
activate ECB again to take effect.
|
||
@end defopt
|
||
|
||
@defopt truncate-long-names
|
||
Truncate long names that don't fit in the width of the ECB windows. If
|
||
you change this during ECB is activated you must deactivate and
|
||
activate ECB again to take effect.
|
||
@end defopt
|
||
|
||
|
||
@node ecb-directories, ecb-sources, ecb-tree-buffer, Customizable options
|
||
@subsection Group ecb-directories
|
||
|
||
@noindent
|
||
This group contains settings for the directories-buffer in the ECB:
|
||
|
||
@defopt add-path-for-not-matching-files
|
||
Add path of a file to @code{ecb-source-path} if not already contained.
|
||
This is done during the auto. windows synchronization which happens if
|
||
a file is opened not via the file/directory-browser of ECB. In such a
|
||
situation ECB adds the path of the new file auto. to
|
||
@code{ecb-source-path} at least temporally for the current Emacs
|
||
session. This option defines two things:
|
||
|
||
@enumerate
|
||
@item
|
||
Should only the root-part (which means for Unix-like systems always
|
||
'/' and for windows-like systems the drive) of the new file be added
|
||
as source-path to @code{ecb-source-path} or the whole directory-part?
|
||
For remote-files (e.g. tramp, ange-ftp- or efs-files) the root-part is
|
||
the complete host-part + the root-dir at that host (example:
|
||
/berndl@@ecb.sourceforge.net:/ would be the root-part of
|
||
/berndl@@ecb.sourceforge.net:/tmp/test.txt).
|
||
@item
|
||
Should this path be added for future sessions too?
|
||
@end enumerate
|
||
|
||
The value of this option is a cons-cell where the car is a boolean for
|
||
1. and the cdr is a boolean for 2.
|
||
|
||
A value of not nil for the car (1.) is reasonably if a user often
|
||
opens files not via the ECB-browser which are not located in any of
|
||
the paths of @code{ecb-source-path} because then only one path for
|
||
each drive (windows) or the root-path (Unix) is added to the directory
|
||
buffer of ECB.
|
||
@end defopt
|
||
|
||
@defopt auto-expand-directory-tree
|
||
Automatically expand the directory tree to the current source file.
|
||
There are three options:
|
||
|
||
@itemize @minus
|
||
@item @code{best}: Expand the best-matching source-path
|
||
@item @code{first}: Expand the first matching source-path
|
||
@item @code{nil}: Do not automatically expand the directory tree.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt after-directory-change-hook
|
||
Hook which run directly after the selected directory has changed. This means
|
||
not onyl after a click onto a directory in the directory-window of ECB but it
|
||
means this hook runs always when the current directory changes regardless of
|
||
the trigger of this change. So for example it runs also when you just switches
|
||
from one buffer to another via @code{switch-to-buffer} or
|
||
@code{switch-to-buffer-other-window} and the directory of these filebuffers is
|
||
different but only when auto-synchronizing of the ECB-windows is on (see
|
||
@code{ecb-basic-buffer-sync}). It runs not when switching between buffers and
|
||
the associated files reside in the same directory.
|
||
|
||
Each function added to this hook will be called with two arguments:
|
||
The directory which was current _before_ the directory-change-trigger
|
||
and the directory which was now the current (i.e. after the trigger).
|
||
|
||
Example: If you switch from a filebuffer ``~/.emacs'' to a filebuffer
|
||
``/tmp/test.txt'' then the functions of this hook will be called with
|
||
the two arguments ``~'' and ``/tmp''.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt cache-directory-contents
|
||
Cache contents of directories.
|
||
|
||
This can be useful if @code{ecb-source-path} contains directories with
|
||
many files and subdirs, especially if these directories are mounted
|
||
net-drives (``many'' means here something > 500, dependent of the
|
||
speed of the net-connection and the machine). Or if it contains
|
||
remote-source-paths which means paths in the sense of tramp, ange-ftp
|
||
or efs. For these directories actualizing the sources- and/or
|
||
directories- buffer of ECB (if displayed in current layout!) can slow
|
||
down dramatically so a caching increases speed a lot.
|
||
|
||
The value of this option is a list where each element is a cons-cell
|
||
and looks like:
|
||
|
||
@example
|
||
(<dir-regexp> . <filenumber threshold>) with
|
||
@end example
|
||
|
||
@table @code
|
||
@item <dir-regexp>:
|
||
Regular expression a directory must match to be cached.
|
||
@item <filenumber threshold>:
|
||
Number of directory contents must exceed this number.
|
||
@end table
|
||
|
||
A directory will only be cached if and only if the directory-name
|
||
matches at least one rexexp of this option and its content-number
|
||
exceeds the related threshold AND the directory-name matches NOT any
|
||
regexp of @code{ecb-cache-directory-contents-not}!
|
||
|
||
The cache entry for a certain directory will be refreshed and
|
||
actualized only by using the POWER-click (see
|
||
@code{ecb-primary-secondary-mouse-buttons}) in the directories-buffer
|
||
of ECB (@pxref{Using the mouse}).
|
||
|
||
Default-value: ECB caches the contents of all remote directories
|
||
regardless of the size and all other directories if more than 50
|
||
entries are contained.
|
||
|
||
Examples:
|
||
|
||
An entry @code{("/usr/home/john_smith/bigdir*" . 1000)} means the
|
||
contents of every subdirectory of the home-directory of John Smith
|
||
will be cached if the directory contains more than 1000 entries and
|
||
its name begins with ``bigdir''.
|
||
|
||
An entry @code{(".*" . 1000)} caches every directory which has more
|
||
than 1000 entries.
|
||
|
||
An entry @code{("^/\\([^:/]*@@\\)?\\([^@@:/]*\\):.*" . 0)} caches
|
||
every remote (in the sense of tramp, ange-ftp or efs) directory
|
||
regardless of the number of entries."
|
||
|
||
Please note: If you want your home-dir being cached then you MUST NOT
|
||
use ``~'' because ECB tries always to match full path-names!
|
||
@end defopt
|
||
|
||
@defopt cache-directory-contents-not
|
||
Do not cache the contents of certain directories. The value of this
|
||
option is a list where the each element is a regular expression a
|
||
directory must match if it should not being cached.
|
||
|
||
If a directory-name matches at least one of the regexps of this option
|
||
the directory-contents will never being cached. See
|
||
@code{ecb-cache-directory-contents} to see when a directory will be
|
||
cached.
|
||
|
||
This option can be useful when normally all directories with a certain
|
||
amount of content (files and subdirs) should be cached but some
|
||
special directories not. This can be achieved by:
|
||
|
||
@itemize @minus
|
||
@item
|
||
Setting @code{ecb-cache-directory-contents} to ((``.*'' . 500)):
|
||
Caches all directories with more then 500 entries
|
||
|
||
@item
|
||
Setting @code{ecb-cache-directory-contents-not} to a value which
|
||
matches these directories which should not being cached (e.g.
|
||
(``/usr/home/john_smith'') excludes the HOME-directory of John Smith
|
||
from being cached).
|
||
@end itemize
|
||
|
||
Please note: If you want your home-dir exclude from being cached then
|
||
you MUST NOT use ``~'' because ECB tries always to match full
|
||
path-names!
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt directories-buffer-after-create-hook
|
||
Local hook running after the creation of the directories-buffer. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating the directories-buffer of ECB and it's local key-map. So for
|
||
example a function could be added which performs calls of
|
||
@code{local-set-key} to define new keybindings only for the
|
||
directories-buffer of ECB.
|
||
|
||
The following keys must not be rebind in the directories-buffer:
|
||
@kbd{F2}, @kbd{F3} and @kbd{F4}
|
||
@end defopt
|
||
|
||
|
||
@defopt directories-buffer-name
|
||
Name of the ECB directory buffer. Because it is not a normal buffer
|
||
for editing you should enclose the name with stars, e.g. `` *ECB
|
||
Directories*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the buffer-object of
|
||
the ECB-directory-buffer by this name, e.g. by a call of @code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after
|
||
deactivating and then activating ECB again!
|
||
@end defopt
|
||
|
||
@defopt directories-menu-sorter
|
||
Function which re-sorts the menu-entries of the directories buffer.
|
||
|
||
If a function then this function is called to re-arrange the
|
||
menu-entries of the combined menu-entries of the user-menu-extensions
|
||
of @code{ecb-directories-menu-user-extension} and the built-in-menu
|
||
@code{ecb-directories-menu}. If nil then no special sorting will be
|
||
done and the user-extensions are placed in front of the
|
||
built-in-entries.
|
||
|
||
The function get one argument, a list of menu-entries. For the format
|
||
of this argument see @code{ecb-directories-menu-user-extension}. The
|
||
function must return a new list in the same format. Of course this
|
||
function can not only re-arrange the entries but also delete entries
|
||
or add new entries.
|
||
@end defopt
|
||
|
||
|
||
@defopt directories-menu-user-extension
|
||
Static user extensions for the popup-menu of the directories buffer.
|
||
Value is a list of elements of the following type: Each element
|
||
defines a new menu-entry and is either:
|
||
|
||
@enumerate
|
||
@item Menu-command:
|
||
A list containing two sub-elements, whereas the first is the function
|
||
(a function symbol) being called if the menu-entry is selected and the
|
||
second is the name of the menu-entry.
|
||
|
||
@item Separator:
|
||
A one-element-list and the element is the string ``---'': Then a
|
||
non-selectable menu-separator is displayed.
|
||
|
||
@item Submenu:
|
||
A list where the first element is the title of the submenu displayed
|
||
in the main-menu and all other elements are either menu-commands (see
|
||
1) or separators (see 2) or another submenu (see c). This allows deep
|
||
nested menu-submenu-structures. Currently a level of 4 is allowed but
|
||
in general there could be an infinite depth of nesting but it makes no
|
||
sense - if possible at all - to define infinite nested
|
||
defcustom-types. So there is a limit of 4 levels but tis is not a hard
|
||
limit: Just increase the value of the @code{ecb-max-submenu-depth}
|
||
@strong{BEFORE} first loading ECB!
|
||
@end enumerate
|
||
|
||
The function of a menu-command must follow the following guidelines:
|
||
Such a function must be defined with the macro
|
||
@code{tree-buffer-defpopup-command}! This macro defines a new
|
||
popup-command whereas the newly defined command gets one argument
|
||
@var{NODE}. See the docstring of @code{tree-buffer-defpopup-command}
|
||
for further details.
|
||
|
||
Example for the definition of such a menu-function:
|
||
|
||
@example
|
||
(tree-buffer-defpopup-command ecb-my-special-dir-popup-function
|
||
"Prints the name of the directory of the node under point."
|
||
(let ((node-data=dir (tree-node-get-data node)))
|
||
(message ``Dir under node: %s'' node-data=dir)))
|
||
@end example
|
||
|
||
Per default the static user-extensions are added at the beginning of
|
||
the built-in menu-entries of @code{ecb-directories-menu} but the whole
|
||
menu can be re-arranged with @code{ecb-directories-menu-sorter}.
|
||
|
||
These menu-extensions are static. A dynamic menu-extension can be
|
||
achieved via @code{ecb-directories-menu-user-extension-function}.
|
||
@end defopt
|
||
|
||
@defopt directories-menu-user-extension-function
|
||
Dynamic user extensions for the popup-menu of the directories buffer.
|
||
A function which has to return a list in the same format like the
|
||
option @code{ecb-directories-menu-user-extension}. This function is
|
||
called when the user opens the popup-menu for the directories buffer.
|
||
|
||
If no dynamically evaluated menu-extensions should be added to the
|
||
directories-buffer the function has to return nil. Therefore the
|
||
default-value of this option is @code{ignore}.
|
||
|
||
Per default the dynamic user-extensions are added in front of the
|
||
static extensions of @code{ecb-directories-menu-user-extension} but
|
||
the whole menu can be re-arranged with
|
||
@code{ecb-directories-menu-sorter}.
|
||
@end defopt
|
||
|
||
@defopt directories-show-node-info
|
||
When to display which node-info in the directories-buffer.
|
||
Define which node info should be displayed after moving the mouse
|
||
over a node (or after a shift click onto the node) in the
|
||
directories-buffer.
|
||
|
||
You can define ``when'' a node-info should be displayed:
|
||
@itemize @minus
|
||
@item always: Node info is displayed by moving with the mouse over a node.
|
||
@item if-too-long: Node info is only displayed by moving with the mouse over a
|
||
node does not fit into the window-width of the tree-buffer window.
|
||
In the ECB directories buffer this means also if a node is shortend or if
|
||
the node has an alias (see @code{ecb-source-path}).
|
||
@item shift-click: Node info is only displayed after a shift click with the
|
||
primary mouse button onto the node.
|
||
@item never: Node info is never displayed.
|
||
@end itemize
|
||
|
||
You can define ``which'' info should be displayed:
|
||
@itemize @minus
|
||
@item name: Only the full node-name is displayed.
|
||
@item path: The full-path of the node is displayed.
|
||
@end itemize
|
||
|
||
Do NOT set this option directly via setq but use always customize!
|
||
@end defopt
|
||
|
||
@defopt display-default-dir-after-start
|
||
Automatically display current default-directory after activating ECB.
|
||
|
||
If a file-buffer is displayed in the current active edit-window then
|
||
ECB synchronizes its basic tree-buffers to this file-buffer - at least if
|
||
the option @code{ecb-basic-buffer-sync} it not nil. So for this situation
|
||
@code{ecb-display-default-dir-after-start} takes no effect but this
|
||
option is for the case if no file-buffer is displayed in the
|
||
edit-window after startup:
|
||
|
||
If true then ECB selects autom. the current default-directory after
|
||
activation even if no file-buffer is displayed in the current active
|
||
edit-window. This is useful if ECB is autom. activated after startup
|
||
of Emacs and Emacs is started without a file-argument. So the
|
||
directory from which the startup has performed is auto. selected in
|
||
the ECB-directories buffer and the ECB-sources buffer displays the
|
||
contents of this directory.
|
||
@end defopt
|
||
|
||
|
||
@defopt excluded-directories-regexps
|
||
Directories that should not be included in the directories list. The
|
||
value of this variable should be a list of regular expression.
|
||
@end defopt
|
||
|
||
@defopt prescan-directories-for-emptyness
|
||
Prescan directories for emptyness. ECB does this so directories are
|
||
displayed as empty in the directories-buffer even without
|
||
user-interaction (i.e. in previous ECB-versions the emptyness of a
|
||
directory has been first checked when the user has clicked onto a
|
||
directory). ECB optimizes this check as best as possible but if a
|
||
directory contains a lot of subdirectories which contain in turn a lot
|
||
of entries, then expanding such a directory or selecting it would take
|
||
of course more time as without this check - at least at the first time
|
||
(all following selects of a directory uses the cached information if
|
||
its subdirectories are empty or not). Therefore ECB performs this
|
||
check stealthy (see @code{ecb-stealthy-tasks-delay}) so normally there
|
||
should no performance-decrease or additional waiting-time for the
|
||
user. There is one exception: For remote directories (in the sense of
|
||
tramp, ange-ftp, or efs) this check can descrease performance even if
|
||
performed stealthy and interruptable. Therefore this option offers
|
||
three possible settings:
|
||
|
||
@itemize @bullet
|
||
@item @code{t}
|
||
Switch on this feature
|
||
|
||
@item @code{unless-remote}
|
||
Switch on this feature but not for remote directories. The term
|
||
``remote'' means here directories which are used via tramp, ange-ftp
|
||
or efs. So mounted directories are counted not as remote directories
|
||
here even if such a directory is maybe hosted on a remote machine. But
|
||
normally only directories in a LAN are mounted so there should be no
|
||
performance-problems with such mounted directories.
|
||
|
||
@item @code{nil}
|
||
Switch off this feature completely.
|
||
@end itemize
|
||
|
||
The option @code{ecb-prescan-directories-exclude-regexps} offers are
|
||
more fine granularity to exclude certain directories from this
|
||
prescan.
|
||
@end defopt
|
||
|
||
@defopt host-accessible-check-valid-time
|
||
Time in seconds a cached accessible-state of a remote host is valid.
|
||
This option is a list where each element specifies how long for a
|
||
certain remote host the cached ping-state (i.e. if the host is
|
||
accessible or not) should be valid. During this time-intervall ECB
|
||
pings such a remote host only once, all other checks use the cached
|
||
value of that real check. But it the cached value is older than the
|
||
value of this option ECB will ping again.
|
||
|
||
Per default ECB discards after 1 minute the cached ping-state of each
|
||
remote host. But if you are sure that a certain remote host is always
|
||
accessible (i.e. means in consequence that you are always online when
|
||
working with ECB and remote-paths) then add an entry to this option
|
||
with a high valid-interval.
|
||
|
||
Examples: An entry (``.*sourceforge.*'' . 3600) ensures that all
|
||
remote hosts machting the string ``sourceforge'' will only once pinged
|
||
during one hour. Or (``.*'' . 300) would ensure that every remote host
|
||
would be pinged only once during 5 minutes.
|
||
@end defopt
|
||
|
||
@defopt ping-options
|
||
List of options for the ping program. These options can be used to
|
||
limit how many ICMP packets are emitted. Ping is used to test if a
|
||
remote host of a remote path (e.g. a tramp-, ange-ftp- or efs-path) is
|
||
accessible See also @code{ecb-ping-program}.
|
||
@end defopt
|
||
|
||
@defopt ping-program
|
||
Program to send network test packets to a host. See also
|
||
@code{ecb-ping-options}.
|
||
@end defopt
|
||
|
||
@defopt prescan-directories-exclude-regexps
|
||
Which directories should be excluded from the empty-prescan. If a
|
||
directory matches any of the regexps of this option it will not be
|
||
prescanned for emptyness - This option takes only effect if
|
||
@code{ecb-prescan-directories-for-emptyness} is not nil.
|
||
@end defopt
|
||
|
||
|
||
@defopt show-sources-in-directories-buffer
|
||
Show source files in directories buffer.
|
||
@end defopt
|
||
|
||
@defopt source-path
|
||
Paths where to find code sources. Each path can have an optional alias
|
||
that is used as it's display name. If no alias is set, the path is
|
||
used as display name.
|
||
|
||
Lisp-type of tis option: The value must be a list L whereas each
|
||
element of L is either
|
||
@itemize @minus
|
||
@item
|
||
a simple string which has to be the full path of a directory (this
|
||
string is displayed in the directory-browser of ECB) or
|
||
|
||
@item
|
||
a 2-elemet list whereas the first element is the full path of a
|
||
directory (string) and the second element is an arbitrary alias
|
||
(string) for this directory which is then displayed instead of the
|
||
underlying directory.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt use-speedbar-instead-native-tree-buffer
|
||
If true then uses speedbar for directories, sources or methods. This
|
||
means that speedbar is integrated in the ECB-frame and is displayed in
|
||
that window normally displaying the standard ECB-directories-buffer,
|
||
ECB-sources-buffer or ECB-methods-buffer.
|
||
|
||
This option takes effect in all layouts which contain either a
|
||
directory window, a sources window or a method window.
|
||
|
||
This option can have four valid values:
|
||
@itemize @minus
|
||
@item @code{nil}: Do not use speedbar (default)
|
||
@item @code{dir}: Use speedbar instead of the standard directories-buffer
|
||
@item @code{source}: Use speedbar instead of the standard sources-buffer
|
||
@item @code{method}: Use speedbar instead of the standard methods-buffer
|
||
@end itemize
|
||
|
||
Note: For directories and sources a similar effect and usability is
|
||
available by setting this option to @code{nil} (or @code{method}) and
|
||
setting @code{ecb-show-sources-in-directories-buffer} to not
|
||
@code{nil}, because this combination displays also directories and
|
||
sources in one window.
|
||
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} is for people who
|
||
like the speedbar way handling directories and source-files or methods
|
||
and want it in conjunction with ECB.
|
||
@end defopt
|
||
|
||
|
||
@node ecb-sources, ecb-methods, ecb-directories, Customizable options
|
||
@subsection Group ecb-sources
|
||
|
||
@noindent
|
||
This group contains settings for the sources-buffer in the ECB:
|
||
|
||
@defopt read-only-check-exclude-regexps
|
||
Which directories should be excluded from the sources-read-only-check.
|
||
If a directory matches any of the regexps of this option their sources
|
||
will not be checked if they are writable - This option takes only
|
||
effect if @code{ecb-sources-perform-read-only-check} is not nil.
|
||
@end defopt
|
||
|
||
@defopt show-source-file-extension
|
||
Show the file extension of source files.
|
||
@end defopt
|
||
|
||
@defopt source-file-regexps
|
||
Specifies which files are shown as source files.
|
||
|
||
This is done on directory-base, which means for each directory-regexp
|
||
the files to display can be specified. If more than one
|
||
directory-regexp matches the current selected directory then always the
|
||
first one (and its related file-exclude/include-regexps) is used! If
|
||
no directory-regexp matches then all files are displayed for the
|
||
currently selected directory.
|
||
|
||
Important note: It is recommended that the *LAST* element of this list
|
||
should contain an always matching directory-regexp (@code{".*"})!
|
||
|
||
So the value of this option is a list of cons-cells where the car is a
|
||
directory regexp and the cdr is a 2 element list where the first
|
||
element is a list of exclude regexps and the second element is a list
|
||
of include regexps. A file is displayed in the source-buffer of ECB
|
||
iff: The file does not match any of the exclude regexps OR the file
|
||
matches at least one of the include regexps.
|
||
|
||
But regardless of the value of this option a file F is never displayed
|
||
in the sources-buffer if the directory matches
|
||
@code{ecb-sources-exclude-cvsignore} and the directory contains a file
|
||
.cvsignore which contains F as an entry!
|
||
|
||
There are three predefined and useful combinations of an exclude and
|
||
include regexp:
|
||
|
||
@itemize @bullet
|
||
@item All files
|
||
|
||
@item All, but no backup, object, lib or ini-files (except .emacs and .gnus). This
|
||
means all files except those starting with ``.'', ``#'' or ending with
|
||
``~'', ``.elc'', ``.obj'', ``.o'', ``.lib'', ``.dll'', ``.a'',
|
||
``.so''. (but including .emacs and .gnus)
|
||
|
||
@item Common source file types (.c, .java etc.)
|
||
@end itemize
|
||
|
||
In addition to these predefined values a custom exclude and include
|
||
combination can be defined.
|
||
|
||
Tips for the directory- and file-rexexps: @code{"$^"} matches no
|
||
files/directories, @code{".*"} matches all files/directories.
|
||
@end defopt
|
||
|
||
@defopt sources-buffer-after-create-hook
|
||
Local hook running after the creation of the sources-buffer. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating the sources-buffer of ECB and it's local key-map. So for
|
||
example a function could be added which performs calls of
|
||
@code{local-set-key} to define new keybindings only for the
|
||
sources-buffer of ECB.
|
||
@end defopt
|
||
|
||
|
||
@defopt sources-buffer-name
|
||
Name of the ECB sources buffer. Because it is not a normal buffer for
|
||
editing you should enclose the name with stars, e.g. ``*ECB Sources*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the
|
||
buffer-object of the ECB-sources-buffer by this name, e.g. by a call
|
||
of @code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after
|
||
deactivating and then activating ECB again!
|
||
@end defopt
|
||
|
||
|
||
@defopt sources-exclude-cvsignore
|
||
Specify if files contained in a @file{.cvsignore} should be
|
||
excluded.
|
||
|
||
Value is a list of regular expressions or nil. If you want to exclude
|
||
files listed in a @file{.cvsignore}-file from being displayed in the
|
||
ecb-sources-buffer then specify a regexp for such a directory.
|
||
|
||
If you want to exclude the contents of @file{.cvsignore}-files for
|
||
every directory then you should add one regexp ``.*'' which matches
|
||
every directory.
|
||
|
||
If you never want to exclude the contents of @file{.cvsignore}-files
|
||
then set this option to nil.
|
||
@end defopt
|
||
|
||
|
||
@defopt sources-menu-sorter
|
||
Function which re-sorts the menu-entries of the directories buffer.
|
||
|
||
If a function then this function is called to sort the menu-entries of
|
||
the combined menu-entries of the user-menu-extensions of
|
||
@code{ecb-sources-menu-user-extension} and the built-in-menu
|
||
@code{ecb-sources-menu}. If nil then no special sorting will be done
|
||
and the user-extensions are placed in front of the built-in-entries.
|
||
|
||
For the guidelines for such a sorter-function see
|
||
@code{ecb-directories-menu-sorter}.
|
||
@end defopt
|
||
|
||
@defopt sources-menu-user-extension
|
||
Static user extensions for the popup-menu of the sources buffer.
|
||
For further explanations see @code{ecb-directories-menu-user-extension}.
|
||
|
||
The node-argument of a menu-function contains as data the source
|
||
for which the popup-menu has been opened. Use always
|
||
@code{ecb-source-get-*} to extract whatever you need from the
|
||
node-data. E.g. use @code{ecb-source-get-filename} to get the full
|
||
filename of the source of the node.
|
||
|
||
Per default the static user-extensions are added at the beginning of the
|
||
built-in menu-entries of @code{ecb-sources-menu} but the whole menu can be
|
||
re-arranged with @code{ecb-sources-menu-sorter}.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt sources-menu-user-extension-function
|
||
Dynamic user extensions for the popup-menu of the sources buffer. A
|
||
function which has to return a list in the same format like the option
|
||
@code{ecb-sources-menu-user-extension}. This function is called when
|
||
the user opens the popup-menu for the sources buffer.
|
||
|
||
If no dynamically evaluated menu-extensions should be added to the
|
||
sources-buffer the function has to return nil. Therefore the
|
||
default-value of this option is @code{ignore}.
|
||
|
||
Per default the dynamic user-extensions are added in front of the
|
||
static extensions of @code{ecb-sources-menu-user-extension} but the
|
||
whole menu can be re-arranged with @code{ecb-sources-menu-sorter}.
|
||
@end defopt
|
||
|
||
|
||
@defopt sources-perform-read-only-check
|
||
Check if source-items in the tree-buffers are read-only. If a
|
||
sourcefile is read-only then it will be displayed with that face set
|
||
in the option @code{ecb-source-read-only-face}.
|
||
|
||
Because this check can be take some time if files are used via a
|
||
mounted net-drive ECB performs this check stealthily (see
|
||
@code{ecb-stealthy-tasks-delay}) so normally the user should not see a
|
||
performance-decrease or additional waiting-time. But to get sure this
|
||
option offers three choices: @code{t}, @code{unless-remote} and
|
||
@code{nil}. See @code{ecb-prescan-directories-for-emptyness} for an
|
||
explanation for these three choices.
|
||
|
||
The option @code{ecb-read-only-check-exclude-regexps} offers are more
|
||
fine granularity to exclude the sources of certain directories from
|
||
the read-only state-check.
|
||
@end defopt
|
||
|
||
@defopt sources-show-node-info
|
||
When to display which node-info in the sources-buffer.
|
||
Define which node info should be displayed after moving the mouse
|
||
over a node (or after a shift click onto the node) in the
|
||
sources-buffer.
|
||
|
||
You can define ``when'' a node-info should be displayed:
|
||
See @code{ecb-directories-show-node-info} for the possible choices.
|
||
|
||
@itemize @minus
|
||
@item name: Only the full node-name is displayed.
|
||
@item file-info: File infos for this file are displayed.
|
||
@item file-info-full: Fill infos incl. full path for this file are displayed.
|
||
@end itemize
|
||
|
||
Do NOT set this option directly via setq but use always customize!
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt sources-sort-ignore-case
|
||
Ignore case for sorting the source-files of the Sources-buffer. See
|
||
also @code{ecb-sources-sort-method}.
|
||
@end defopt
|
||
|
||
@defopt sources-sort-method
|
||
Defines how the source files are sorted.
|
||
|
||
@itemize @minus
|
||
@item @code{name}:
|
||
Sorting by name.
|
||
@item @code{extension}:
|
||
Sorting first by extension and then by name.
|
||
@item @code{nil}:
|
||
No sorting, means source files are displayed in the sequence returned
|
||
by @code{directory-files} (called without sorting).
|
||
@end itemize
|
||
|
||
See also @code{ecb-sources-sort-ignore-case}
|
||
@end defopt
|
||
|
||
|
||
@node ecb-methods, ecb-history, ecb-sources, Customizable options
|
||
@subsection Group ecb-methods
|
||
|
||
@noindent
|
||
This group contains settings for the methods-buffer in the ECB:
|
||
|
||
@defopt auto-expand-tag-tree
|
||
Expand the methods-tag-tree automatically if node invisible.
|
||
|
||
This option has only an effect if option @code{ecb-highlight-tag-with-point} is
|
||
switched on too. There are three possible choices:
|
||
@itemize @minus
|
||
@item @code{nil}:
|
||
No auto. expanding of the method buffer.
|
||
@item @code{expand-spec}:
|
||
Auto expand the method-buffer nodes if the node belonging to current
|
||
tag under point is invisible because its parent-node is collapsed.
|
||
But expanding is only done if the type of the tag under point in the
|
||
edit-buffer is contained in @code{ecb-methods-nodes-expand-spec}.
|
||
@item @code{all}:
|
||
Like expand-spec but expands all tags regardless of the setting in
|
||
@code{ecb-methods-nodes-expand-spec}.
|
||
@end itemize
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt auto-expand-tag-tree-collapse-other
|
||
Auto. expanding the tag-tree collapses all not related nodes. There
|
||
are several choices:
|
||
|
||
@itemize @minus
|
||
@item Only if on tag:
|
||
This means collapsing 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. But do this only if
|
||
point stays onto a tag in the selected edit-window.
|
||
|
||
@item Always:
|
||
Same as before but collapse also when point doesn't stays on a tag
|
||
(e.g. between two defuns in elisp) in the selected edit-window. This
|
||
means in such a situation a full collapsing of the methods-buffer.
|
||
|
||
@item Never:
|
||
Do not automatically collapse the methods-buffer.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
|
||
@defopt auto-update-methods-after-save
|
||
Automatically updating the ECB method buffer after saving a source.
|
||
@end defopt
|
||
|
||
@defopt default-tag-filter
|
||
Default tag-filters for certain files. This option 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. Please be aware that symbol-filters (e.g.
|
||
protection-symbols like public or private) must not be inserted with
|
||
quotes whereas a filter-regexp has to be inserted with surrounding
|
||
double-quotes! In addition backslashes in a regexp have to be doubled!
|
||
|
||
For each file-spec (a major-mode plus a file-regexp which both specify
|
||
a file for which filters should be applied) there can be as much
|
||
filters as needed - they are layered like with
|
||
@code{ecb-methods-filter} too.
|
||
|
||
Tag-classes which are completely hidden or excluded by the option
|
||
@code{ecb-show-tags} will never being displayed in the Methods-buffer
|
||
regardless of the filters of this option!
|
||
@end defopt
|
||
|
||
@defopt disable-semantic-threshold-alist
|
||
Threshold for disabling semantic-parsing Define a threshold fpr
|
||
buffer-size. Exceeding this threshold disables parsing current buffer
|
||
by semantic.
|
||
|
||
This functionality is set on a major-mode base, i.e. for every
|
||
major-mode a different setting can be used. The value of this option
|
||
is a list of cons-cells:
|
||
|
||
@itemize @minus
|
||
@item
|
||
The car is either a major-mode symbol or the special symbol 'default which
|
||
means if no setting for a certain major-mode is defined then the cdr of
|
||
the 'default cons-cell is used.
|
||
@item
|
||
The cdr is an integer which defines the threshold for the buffer-size for
|
||
this major-mode.
|
||
@end itemize
|
||
|
||
Example:
|
||
|
||
@example
|
||
((default . 1000000)
|
||
(c-mode . 200000))
|
||
@end example
|
||
|
||
This example whould not parse c-mode buffers exceeding a buffer-size
|
||
of 200000. And buffers of all other modes would be only parsed if
|
||
smaller than 1000000.
|
||
|
||
A setting of @code{((c-mode . 200000))} would only restrict c-mode
|
||
buffers to a size of 200000 but would parse all other buffer
|
||
regardless their size.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt display-image-icons-for-semantic-tags
|
||
Display nice and pretty icons for semantic-tags in the Methods-buffer. A non
|
||
nil value takes only effect if Emacs can display images and if
|
||
@code{ecb-tree-buffer-style} is set to @code{image}.
|
||
@end defopt
|
||
|
||
@defopt exclude-parents-regexp
|
||
Regexps which parent classes should not be shown in the methods buffer
|
||
(see also @code{ecb-show-parents}). If nil then all parents will be
|
||
shown if @code{ecb-show-parents} is not nil.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt expand-methods-switch-off-auto-expand
|
||
Switch off auto expanding in the ECB-method buffer. If on then auto
|
||
expanding is switched off after explicit expanding or collapsing by
|
||
@code{ecb-expand-methods-nodes}.
|
||
|
||
This is done with @code{ecb-toggle-auto-expand-tag-tree} so after
|
||
the switch off the auto expanding feature can again switched on
|
||
quickly.
|
||
|
||
But after explicitly expanding/collapsing the methods-buffer to a
|
||
certain level the auto. expanding could undo this when the node
|
||
belonging to current tag under point in the current active edit-window
|
||
is invisible after @code{ecb-expand-methods-nodes} - then the auto.
|
||
expand feature would make this node immediately visible and destroys
|
||
the explicitly set expand-level.
|
||
@end defopt
|
||
|
||
@defopt find-external-tag-functions
|
||
Functions used for searching external tags clicked in the methods buffer.
|
||
|
||
The methods buffer displays for oo-languages the parents of a type under a
|
||
special bucket ``Parents''. Languages like C++, CLOS and Eieio allow to define
|
||
the implementation of a method outside of the class definition and even in
|
||
another file. In the methods-buffer of ECB such externaly defined methods are
|
||
collected and displayed under a @code{virtual} faux type-tag named as the
|
||
class-qualifier of the methods. This faux-tag is virtual because it does not
|
||
extist in the parsed buffer.
|
||
|
||
If a user clicks either onto such a faux-type-tag or onto a parent-tag then
|
||
ECB tries to find the definition of the underlying type on a name-basis,
|
||
displaying the containing file as buffer in the current edit-window and
|
||
jumping to the start of the type-definition in this buffer.
|
||
|
||
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 @code{major-mode} base, i.e. for every
|
||
@code{major-mode} a different setting can be used. The value of this option is
|
||
a list of cons-cells: The car is either a @code{major-mode} symbol or the
|
||
special symbol 'default. The cdr is a list of find-functions or nil.
|
||
|
||
ECB first performs all find-functions defined for current @code{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
|
||
@item @code{ecb-search-type-tag-by-semantic-analyzer} (most powerful)
|
||
@item @code{ecb-search-type-tag-by-semanticdb}
|
||
@item @code{ecb-jde-show-class-source} (for major-mode @code{jde-mode} when
|
||
coding in java)
|
||
@end itemize
|
||
|
||
This function does not only the searching but displays the founded tag. See
|
||
the documentation of these function for details how they work.
|
||
|
||
But you can add any arbitrary function if the following conditions are
|
||
fulfilled:
|
||
|
||
@itemize
|
||
@item
|
||
The function gets a semantic tag representing the external type which should
|
||
be found. This is a positionless-tag (otherwise it would not be hard to go
|
||
to it) and it's either a faux-tag (for which @code{ecb--semantic-faux-tag-p} is
|
||
not nil; the function can use this check if necessary) or a simple tag
|
||
containing only a name an a tag-class. The tag-class for both is 'type.
|
||
|
||
@item
|
||
The return value of the function must be one of:
|
||
@itemize @minus
|
||
@item @code{nil}: No tag is found
|
||
@item @code{t}: A tag has been found and also be displayed in the edit-window (this
|
||
prevents ECB from running further function of this option because the searched
|
||
tag is already displayed. So a function should only return @code{t} if all is
|
||
fine and no further actions are needed.
|
||
@item A positioned semantic tag (for which @code{ecb--semantic-tag-with-position-p}
|
||
returns not @code{nil}) which represents the found external type-tag.
|
||
@end itemize
|
||
@end itemize
|
||
|
||
It's strongly recommended for the function not to display the found location
|
||
for itself but to return a positioned semantic tag! But sometimes the
|
||
displaying is integrated in a third-party find-function like
|
||
@code{jde-show-class-source} which is used by
|
||
@code{ecb-jde-show-class-source}. In these cases the function has to return t
|
||
if the searched tag has been successfully displayed.
|
||
|
||
Precondition for a find-function:
|
||
Current buffer is the buffer the clicked faux- or parent tag belongs to
|
||
Current point depends on the clicked tag:
|
||
@itemize
|
||
@item In case of a faux-tag it's the start of the first child of the
|
||
faux-tag. There must be at least one adopted child-tag because
|
||
otherwise we would not have the faux-tag
|
||
@item In case of an external parent-tag its the the start of the
|
||
external tag itself.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt font-lock-tags
|
||
Adds font-locking (means highlighting) to the ECB-method buffer.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt highlight-tag-with-point
|
||
How to highlight the method or variable under the cursor.
|
||
|
||
@itemize @minus
|
||
@item @code{highlight-scroll}:
|
||
Always scroll the method buffer, so the current method of the
|
||
edit-window is highlighted in the method-window.
|
||
@item @code{highlight}:
|
||
Only highlight the current method of the edit window in the
|
||
method window if the method is visible in the method-window.
|
||
@item @code{nil}:
|
||
No highlighting is done.
|
||
@end itemize
|
||
|
||
See also @code{ecb-highlight-tag-with-point-delay}.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt highlight-tag-with-point-delay
|
||
Time Emacs must be idle before current tag is highlighted. If nil
|
||
then there is no delay, means current tag is highlighted
|
||
immediately. A small value of about 0.25 seconds saves CPU resources
|
||
and you get even though almost the same effect as if you set no delay.
|
||
But such a delay prevents also ``jumping backward/forward'' during
|
||
scrolling within java-classes if point goes out of method-definition
|
||
into class-definition. Therefore the default value is a delay of 0.25
|
||
seconds.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt methods-buffer-after-create-hook
|
||
Local hook running after the creation of the methods-buffer. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating the methods-buffer of ECB and it's local key-map. So for
|
||
example a function could be added which performs calls of
|
||
@code{local-set-key} to define new keybindings only for the
|
||
methods-buffer of ECB.
|
||
@end defopt
|
||
|
||
|
||
@defopt methods-buffer-name
|
||
Name of the ECB methods buffer. Because it is not a normal buffer for
|
||
editing you should enclose the name with stars, e.g. `` *ECB
|
||
Methods*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the
|
||
buffer-object of the ECB-methods-buffer by this name, e.g. by a call
|
||
of @code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after
|
||
deactivating and then activating ECB again!
|
||
@end defopt
|
||
|
||
@defopt methods-filter-replace-existing
|
||
How the methods-filter should be applied to existing filters. There
|
||
are three different choices:
|
||
|
||
@itemize @minus
|
||
@item @code{never}:
|
||
This is the default and means that calling @code{ecb-methods-filter}
|
||
always adds the new filter on top of already existing filters. So you
|
||
can combine several filter to one combined like this example: 'Display
|
||
only all public methods having the string ``test'' in its name.' With
|
||
this setting the filters can only be cleared by calling
|
||
@code{ecb-methods-filter} and then choosing ``nothing''.
|
||
|
||
@item @code{always}:
|
||
This means that @code{ecb-methods-filter} always clears a previous
|
||
filter before applying the new one.
|
||
|
||
@item @code{ask}:
|
||
ECB asks if the new filter should replace the existing ones.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt methods-menu-sorter
|
||
Function which re-sorts the menu-entries of the directories buffer.
|
||
|
||
If a function then this function is called to sort the menu-entries of
|
||
the combined menu-entries of the user-menu-extensions of
|
||
@code{ecb-methods-menu-user-extension} and the built-in-menu
|
||
@code{ecb-methods-menu}. If nil then no special sorting will be done
|
||
and the user-extensions are placed in front of the built-in-entries.
|
||
|
||
For the guidelines for such a sorter-function see
|
||
@code{ecb-directories-menu-sorter}.
|
||
@end defopt
|
||
|
||
|
||
@defopt methods-menu-user-extension
|
||
Static user extensions for the popup-menu of the methods buffer. For
|
||
further explanations see @code{ecb-directories-menu-user-extension}.
|
||
|
||
The node-argument of a menu-function contains as data the semantic-tag
|
||
of the method/variable/tag for which the popup-menu has been opened.
|
||
|
||
Per default the static user-extensions are added at the beginning of
|
||
the built-in menu-entries of @code{ecb-methods-menu} but the whole
|
||
menu can be re-arranged with @code{ecb-methods-menu-sorter}.
|
||
@end defopt
|
||
|
||
@defopt methods-menu-user-extension-function
|
||
Dynamic user extensions for the popup-menu of the methods buffer. A
|
||
function which has to return a list in the same format like the option
|
||
@code{ecb-methods-menu-user-extension}. This function is called when
|
||
the user opens the popup-menu for the methods buffer. For an example
|
||
how such a function can be programmed see
|
||
@code{ecb-methods-menu-editwin-entries}.
|
||
|
||
If no dynamically evaluated menu-extensions should be added to the
|
||
methods-buffer the function has to return nil. Therefore the
|
||
default-value of this option is @code{ignore}.
|
||
|
||
Per default the dynamic user-extensions are added in front of the
|
||
static extensions of @code{ecb-methods-menu-user-extension} but the
|
||
whole menu can be re-arranged with @code{ecb-methods-menu-sorter}.
|
||
@end defopt
|
||
|
||
|
||
@defopt methods-nodes-collapse-spec
|
||
Semantic tag-types collapsed by @code{ecb-expand-methods-nodes}.
|
||
For valid values of this option see @code{ecb-methods-nodes-expand-spec}!
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
|
||
@defopt methods-nodes-expand-spec
|
||
Semantic tag-types expanded by @code{ecb-expand-methods-nodes}.
|
||
|
||
The value of this option is either the symbol @code{all} (all tags
|
||
are expanded regardless of their type) or a list of symbols where each
|
||
symbol is a valid semantic tag-type. For a description of semantic
|
||
tag types see option @code{ecb-show-tags}.
|
||
|
||
But this option also defines if bucket-nodes in the ECB-method-buffer
|
||
(e.g. ``[Variables]'') should be expanded. Therefore valid symbols for
|
||
this list are also all cars of the variable returned by
|
||
@code{ecb--semantic-symbol->name-assoc-list}.
|
||
|
||
If there is a bucket-name (the node-name stripped of the settings in
|
||
@code{ecb-bucket-node-display}) which is not contained as cdr in the
|
||
value returned by @code{ecb--semantic-symbol->name-assoc-list} then
|
||
the symbol with this bucket-name as name is also a valid symbol for
|
||
this list. Example: In ECB there are buckets ``[Parents]''. The
|
||
bucket-name is ``Parents'' and the valid symbol-name is then
|
||
@code{Parents}.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt methods-separate-prototypes
|
||
Separate function-prototypes from the real functions. This is for
|
||
example useful for C++ and C because these languages distinct between
|
||
a method-prototype (rsp. function-prototype for C) and the method
|
||
(rsp. function for C) itself. If this option is not nil then ECB
|
||
separates the prototypes from the real function/methods. Then with
|
||
@code{ecb-show-tags} the user can define different display-settings
|
||
for each of them. If this option is nil then the prototypes and the
|
||
real functions are filled in the same bucket and displayed plain and
|
||
there is no sorting between prototypes and functions possible. If this
|
||
option is switched on then it is senseful that @code{ecb-show-tags}
|
||
contains for all modes which distinct between prototypes and real
|
||
functions/methods two entries for the tag-type 'function - see the
|
||
documentation of this option.
|
||
@end defopt
|
||
|
||
@defopt methods-show-node-info
|
||
When to display which node-info in the methods-buffer. Define which
|
||
node info should displayed after moving the mouse over a node (or
|
||
after a shift click onto the node) in the methods-buffer.
|
||
|
||
You can define ``when'' a node-info should be displayed: See
|
||
@code{ecb-directories-show-node-info} for the possible choices.
|
||
|
||
You can define what info should be displayed:
|
||
@itemize @minus
|
||
@item name:
|
||
Only the full node name is displayed.
|
||
|
||
@item name+type:
|
||
The full name + the type of the node (function, class, variable) is
|
||
displayed.
|
||
@end itemize
|
||
|
||
Do NOT set this option directly via setq but use always customize!
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt post-process-semantic-taglist
|
||
Define mode-dependent post-processing for the semantic-taglist. This
|
||
is an alist where the car is a major-mode symbol and the cdr is a list
|
||
of function-symbols of functions which should be used for
|
||
post-processing the taglist (returned by
|
||
@code{ecb--semantic-bovinate-toplevel}) for a buffer in this
|
||
major-mode. The first function in the list is called with current
|
||
semantic taglist of current buffer and must return a valid taglist
|
||
again. All other functions are called with the result-taglist of its
|
||
preceding function and have to return a new taglist again.
|
||
|
||
For oo-programming languages where the methods of a class can be
|
||
defined outside the class-definition (e.g. C++, Eieio) the function
|
||
@code{ecb-group-function-tags-with-parents} can be used to get a much
|
||
better method-display in the methods-window of ECB, because all method
|
||
implementations of a class are grouped together.
|
||
|
||
Another senseful usage is to filter out certain tags, e.g. prototype
|
||
tags in @code{c-mode}. For this you can set
|
||
@code{ecb-filter-c-prototyp-tags}.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt show-only-positioned-tags
|
||
Show only nodes in the method-buffer which are ``jump-able''. If not nil
|
||
then ECB displays in the method-buffer only nodes which are
|
||
``jump-able'', i.e. after selecting it by clicking or with RET then ECB
|
||
jumps to the corresponding location in the edit-window. Example: With
|
||
CLOS or Eieio source-code there can exist some position-less nodes like
|
||
variable-attributes in a @code{defclass} form which are only displayed
|
||
if this option is nil. Displaying such nodes can be senseful even if
|
||
they can not be jumped.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt show-tags
|
||
How to show tags in the methods buffer first time after find-file.
|
||
This functionality is set on a major-mode base, i.e. for every
|
||
major-mode a different setting can be used. The value of this option
|
||
is a list of cons-cells:
|
||
|
||
The car is either a major-mode symbol or the special symbol 'default
|
||
which means if no setting for a certain major-mode is defined then the
|
||
cdr of the 'default cons-cell is used. This option should always
|
||
contain a default-setting!
|
||
|
||
The cdr is a list where each element represents a type of tags:
|
||
|
||
@example
|
||
(<tag type> <display type> <sort method>)
|
||
@end example
|
||
|
||
There can be more than 1 element for a certain <tag type>. This is for
|
||
example useful for C++ and C because these languages distinct between
|
||
a method-prototype (rsp. function-prototype for C) and the method
|
||
(rsp. function for C) itself. The default value of these option
|
||
contains two entries for <tag type> is @code{function} whereas the
|
||
first one is responsible for the ``real'' methods (rsp. functions) and
|
||
the second one for the prototypes. So if the methods should be
|
||
flattened and the prototypes collapsed the show-tags-list for C++ and
|
||
C must contain two entries for <tag type> @code{function}, the first
|
||
one defined as @code{flattened} and the second one defined as
|
||
@code{collapsed}.
|
||
|
||
The tags in the methods buffer are displayed in the order as they appear in
|
||
this list.
|
||
|
||
@table @code
|
||
@item <tag type>
|
||
A Semantic tag type symbol (function, variable, rule, include etc.)
|
||
or one of the following:
|
||
|
||
@itemize @minus
|
||
@item @code{t}: All tag types not specified anywhere else in the list.
|
||
@item @code{parent}: The parents of a type.
|
||
@end itemize
|
||
|
||
@item <display type>
|
||
A symbol which describes how the tags of this type shall be shown:
|
||
|
||
@itemize @minus
|
||
@item @code{expanded}: The tags are shown in an expanded node.
|
||
@item @code{collapsed}: The tags are shown in a collapsed node.
|
||
@item @code{flattened}: The tags are added to the parent node.
|
||
@item @code{hidden}: The tags are not shown.
|
||
@end itemize
|
||
|
||
@item <sort method>
|
||
A symbol describing how to sort the tags of this type:
|
||
|
||
@itemize @minus
|
||
@item @code{name}:
|
||
Sort by the tag name.
|
||
@item @code{access}:
|
||
Sort by tag access (public, protected, private) and then by name.
|
||
@item @code{nil}:
|
||
Don't sort tags. They appear in the same order as in the source
|
||
buffer.
|
||
@end itemize
|
||
@end table
|
||
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt tag-display-function
|
||
Function to use for displaying tags in the methods buffer. This
|
||
functionality is set on major-mode base, i.e. for every major-mode a
|
||
different function can be used. The value of this option is a list of
|
||
cons-cells:
|
||
|
||
@itemize @minus
|
||
@item
|
||
The car is either a major-mode symbol or the special symbol 'default which
|
||
means if no function for a certain major-mode is defined then the cdr of
|
||
the 'default cons-cell is used.
|
||
@item
|
||
The cdr is the function used for displaying a tag in the related
|
||
major-mode.
|
||
@end itemize
|
||
|
||
Every function is called with 3 arguments:
|
||
|
||
@enumerate
|
||
@item The tag
|
||
@item The parent-tag of tag (can be nil)
|
||
@item The value of @code{ecb-font-lock-tags}.
|
||
@end enumerate
|
||
|
||
Every function must return the display of the tag as string,
|
||
colorized if the third argument is not nil.
|
||
|
||
The following functions are predefined:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
For each element E of @code{ecb--semantic-format-function-alist}
|
||
exists a function with name ``ecb--<(cdr E)>''. These functions are
|
||
just aliase to the builtin format-functions of semantic. See the
|
||
docstring of these functions to see what they do. Example:
|
||
(semantic-name-nonterminal . semantic-format-tag-name) is an element
|
||
of @code{ecb--semantic-format-function-alist}. Therefore the
|
||
alias-function for this element is named
|
||
@code{ecb--semantic-format-tag-name}.
|
||
|
||
@item
|
||
For every cdr in @code{ecb--semantic-format-function-alist} with name
|
||
``semantic-XYZ'' a function with name ``ecb-XYC'' is predefined. The
|
||
differences between the semantic- and the ECB-version are:
|
||
|
||
@itemize @minus
|
||
@item
|
||
The ECB-version displays for type tags only the type-name and nothing
|
||
else (exception: In c++-mode a template specifier is appended to the
|
||
type-name if a template instead a normal class).
|
||
@item
|
||
The ECB-version displays type-tags according to the setting in
|
||
@code{ecb-type-tag-display}. This is useful for better recognizing
|
||
different classes, structs etc. in the ECB-method window.
|
||
@end itemize
|
||
|
||
For all tags which are not types the display of the ECB-version is
|
||
identical to the semantic version. Example: For
|
||
@code{ecb--semantic-format-tag-name} (one of the builtin semantic
|
||
formatters) the pendant is @code{ecb-format-tag-name}.
|
||
@end itemize
|
||
|
||
This functionality also allows the user to display tags as UML. To
|
||
enable this functionality set the function for a major-mode \(e.g.
|
||
@code{jde-mode}) to
|
||
@code{ecb--semantic-format-tag-uml-concise-prototype},
|
||
@code{ecb--semantic-format-tag-uml-prototype}, or
|
||
@code{ecb--semantic-format-tag-uml-abbreviate} the ECB-versions of
|
||
these functions.
|
||
|
||
If the value is @code{nil}, i.e. neither a function for a major-mode
|
||
is defined nor the special 'default, then
|
||
@code{ecb--semantic-format-tag-prototype} is used for displaying the
|
||
tags.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt tag-jump-sets-mark
|
||
Set the mark after jumping to a tag from the ECB-method buffer. If
|
||
set the user can easily jump back.
|
||
@end defopt
|
||
|
||
@defopt tag-visit-post-actions
|
||
Actions to perform after visiting a tag from the Method-buffer. With
|
||
this option actions can be added which will be performed after
|
||
visiting the start of the tag in the source-buffer.
|
||
|
||
This functionality is set on a @code{major-mode} base, i.e. for every
|
||
@code{major-mode} a different setting can be used. The value of this
|
||
option is a list of cons-cells:
|
||
@itemize @minus
|
||
@item
|
||
The car is either a @code{major-mode} symbol or the special symbol
|
||
'default.
|
||
|
||
@item
|
||
The cdr is a list of action-functions or nil.
|
||
@end itemize
|
||
|
||
ECB first performs all actions defined for the special symbol 'default
|
||
(if any) and then all actions defined for current @code{major-mode}
|
||
(if any).
|
||
|
||
ECB offers some predefined senseful action-functions. Currently there
|
||
are: @code{ecb-tag-visit-highlight-tag-header}
|
||
@code{ecb-tag-visit-smart-tag-start}
|
||
@code{ecb-tag-visit-recenter} @code{ecb-tag-visit-recenter-top}
|
||
@code{ecb-tag-visit-goto-doc-start}
|
||
@code{ecb-tag-visit-narrow-tag} See the documentation of these
|
||
function for details what they do.
|
||
|
||
But you can add any arbitrary function if the following conditions are
|
||
fulfilled: The function gets the semantic tag as argument, returns the
|
||
(new) point after finishing its job and the function must not put the
|
||
point outside the tag-boundaries of the tag-argument.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt type-tag-display
|
||
How to display semantic type-tags in the methods buffer. Normally
|
||
all tag displaying, colorizing and facing is done by semantic
|
||
according to the value returned by
|
||
@code{ecb--semantic-format-face-alist} and the semantic
|
||
display-function (e.g. one from
|
||
@code{ecb--semantic-format-tag-functions}). But sometimes a finer
|
||
distinction in displaying the different type specifiers of type-tags
|
||
can be useful. For a description when this option is evaluated look at
|
||
@code{ecb-tag-display-function}!
|
||
|
||
This functionality is set on a major-mode base, i.e. for every
|
||
major-mode a different setting can be used. The value of this option
|
||
is a list of cons-cells:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The car is either a major-mode symbol or the special symbol 'default which
|
||
means if no setting for a certain major-mode is defined then the cdr of
|
||
the 'default cons-cell is used.
|
||
|
||
@item
|
||
The cdr is a list of 3-element-lists:
|
||
|
||
@enumerate
|
||
@item
|
||
First entry is a semantic type specifier in string-form. Current
|
||
available type specifiers are for example ``class'', ``interface'',
|
||
``struct'', ``typedef'' and ``enum''. In addition to these ones there
|
||
is also a special ECB type specifier ``group'' which is related to
|
||
grouping tags (see @code{ecb-post-process-semantic-taglist} and
|
||
@code{ecb-group-function-tags-with-parents}). Any arbitrary
|
||
specifier can be set here but if it is not ``group'' or not known by
|
||
semantic it will be useless.
|
||
@item
|
||
Second entry is a flag which indicates if the type-specifier string
|
||
from (1.) itself should be removed (if there is any) from the display.
|
||
@item
|
||
Third entry is the face which is used in the ECB-method window to
|
||
display type-tags with this specifier. ECB has some predefined faces
|
||
for this (@code{ecb-type-tag-class-face},
|
||
@code{ecb-type-tag-interface-face}, @code{ecb-type-tag-struct-face},
|
||
@code{ecb-type-tag-typedef-face}, @code{ecb-type-tag-union-face},
|
||
@code{ecb-type-tag-enum-face} and @code{ecb-type-tag-group-face}) but
|
||
any arbitrary face can be set here. This face is merged with the faces
|
||
semantic already uses to display a tag,
|
||
i.e. the result is a display where all face-attributes of the ECB-face
|
||
take effect plus all face-attributes of the semantic-faces which are not
|
||
set in the ECB-face (with XEmacs this merge doesn't work so here the
|
||
ECB-face replaces the semantic-faces; this may be fixed in future
|
||
versions).
|
||
@end enumerate
|
||
@end itemize
|
||
|
||
The default value is nil means there is no special ECB-displaying of
|
||
type-tags in addition to the displaying and colorizing semantic
|
||
does. But a value like the following could be a useful setting:
|
||
|
||
@example
|
||
@group
|
||
((default
|
||
("class" t ecb-type-tag-class-face)
|
||
("group" nil ecb-type-tag-group-face))
|
||
(c-mode
|
||
("struct" nil ecb-type-tag-struct-face)
|
||
("typedef" nil ecb-type-tag-typedef-face)))
|
||
@end group
|
||
@end example
|
||
|
||
This means that in @code{c-mode} only ``struct''s and ``typedef''s are
|
||
displayed with special faces (the specifiers itself are not removed)
|
||
and in all other modes ``class''s and grouping-tags (see
|
||
@code{ecb-tag-display-function},
|
||
@code{ecb-group-function-tags-with-parents}) have special faces and
|
||
the ``class'' specifier-string is removed from the display.
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
@defopt type-tag-expansion
|
||
Default expansion of semantic type-tags. Semantic groups type-tags in
|
||
different type-specifiers. Current available type specifiers are for
|
||
example ``class'', ``interface'', ``struct'', ``typedef'', ``union''
|
||
and ``enum''. In addition to these ones there is also a special ECB
|
||
type-specifier ``group'' which is related to grouping tags (see
|
||
@code{ecb-post-process-semantic-taglist}).
|
||
|
||
This option defines which type-specifiers should be expanded at
|
||
file-open-time. Any arbitrary specifier can be set here but if it is
|
||
not ``group'' or not known by semantic it will be useless.
|
||
|
||
This functionality is set on a major-mode base, i.e. for every
|
||
major-mode a different setting can be used. The value of this option
|
||
is a list of cons-cells:
|
||
|
||
@itemize
|
||
@item
|
||
The car is either a major-mode symbol or the special symbol
|
||
@code{default} which means if no setting for a certain major-mode is
|
||
defined then the cdr of the @code{default} cons-cell is used.
|
||
|
||
@item
|
||
The cdr is either a list of type-specifiers which should be expanded
|
||
at file-open-time or the symbol @code{all-specifiers} (then a type-tag
|
||
is always expanded regardless of its type-specifier).
|
||
@end itemize
|
||
|
||
This options takes only effect for semantic-sources - means sources
|
||
supported by semantic!
|
||
@end defopt
|
||
|
||
|
||
@node ecb-history, ecb-analyse, ecb-methods, Customizable options
|
||
@subsection Group ecb-history
|
||
|
||
@noindent
|
||
This group contains settings for the history-buffer in the ECB:
|
||
|
||
@defopt history-buffer-after-create-hook
|
||
Local hook running after the creation of the history-buffer. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating the history-buffer of ECB and it's local key-map. So for
|
||
example a function could be added which performs calls of
|
||
@code{local-set-key} to define new keybindings only for the
|
||
history-buffer of ECB.
|
||
@end defopt
|
||
|
||
|
||
@defopt history-buffer-name
|
||
Name of the ECB history buffer. Because it is not a normal buffer for
|
||
editing you should enclose the name with stars, e.g. ``*ECB
|
||
History*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the
|
||
buffer-object of the ECB-history-buffer by this name, e.g. by a call
|
||
of @code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after
|
||
deactivating and then activating ECB again!
|
||
@end defopt
|
||
|
||
@defopt history-exclude-file-regexps
|
||
List of regexps which exclude source-files from being historized. Be
|
||
aware that each always full filenames (ie. incl. full path) are
|
||
matched against these regexps! Therefore be carefore with regexps
|
||
beginning with ^!
|
||
@end defopt
|
||
|
||
@defopt history-item-name
|
||
The name to use for items in the history buffer.
|
||
@end defopt
|
||
|
||
@defopt history-make-buckets
|
||
Bucketize the entries of the history-buffer.
|
||
|
||
There are several options how the bucketizing should be done:
|
||
@itemize
|
||
@item 'never:
|
||
|
||
No bucketizing at all, ie. all entries of the history-buffer we be
|
||
displayed flat.
|
||
|
||
@item 'directory:
|
||
|
||
All entries with related filesources residing in the same
|
||
directory will be contained in a bucket named with that directory.
|
||
|
||
@item 'directory-with-source-path:
|
||
|
||
Same as 'directory but the best matching source-path of the directory-window
|
||
(see @code{ecb-source-path}) substituts the matching part of the directory.
|
||
For this a special face is used (see
|
||
@code{ecb-history-bucket-node-dir-soure-path-face}).
|
||
|
||
@item 'mode:
|
||
|
||
All entries with related buffers have the same
|
||
major-mode will be contained in a bucket named with that major-mode
|
||
|
||
@item 'extension:
|
||
|
||
All entries with related filesources having the
|
||
same extension will be contained in a bucket named with that extension
|
||
@end itemize
|
||
|
||
If the value is a list of regular expressions then all entries where the
|
||
buffername matches the same regular expression will be contained in one
|
||
bucket. If the value is nil then this is interpreted as an empty list of
|
||
regular expressions!
|
||
|
||
The default value is 'directory.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt history-menu-sorter
|
||
Function which re-sorts the menu-entries of the directories buffer.
|
||
|
||
If a function then this function is called to sort the menu-entries of
|
||
the combined menu-entries of the user-menu-extensions of
|
||
@code{ecb-history-menu-user-extension} and the built-in-menu
|
||
@code{ecb-history-menu}. If nil then no special sorting will be done
|
||
and the user-extensions are placed in front of the built-in-entries.
|
||
|
||
For the guidelines for such a sorter-function see
|
||
@code{ecb-directories-menu-sorter}.
|
||
@end defopt
|
||
|
||
@defopt history-menu-user-extension
|
||
Static user extensions for the popup-menu of the history buffer.
|
||
For further explanations see @code{ecb-directories-menu-user-extension}.
|
||
|
||
The node-argument of a menu-function contains as data a cons:
|
||
|
||
car is the filename of the source for which the popup-menu has
|
||
been opened. cdr is the related buffer-name; but be careful,
|
||
because the node can point to a dead buffer (see
|
||
@code{ecb-kill-buffer-clears-history}). Use always @code{ecb-source-get-*}
|
||
to extract whatever you need from the node-data. E.g. use
|
||
@code{ecb-source-get-filename} to get the full filename of the source
|
||
of the node and use @code{ecb-source-get-buffername} or @code{ecb-source-get-buffer} to
|
||
get the buffername rsp. the buffer-object.
|
||
|
||
Per default the static user-extensions are added at the beginning of the
|
||
built-in menu-entries of @code{ecb-history-menu} but the whole menu can be
|
||
re-arranged with @code{ecb-history-menu-sorter}.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt history-menu-user-extension-function
|
||
Dynamic user extensions for the popup-menu of the history buffer. A
|
||
function which has to return a list in the same format like the option
|
||
@code{ecb-history-menu-user-extension}. This function is called when
|
||
the user opens the popup-menu for the history buffer.
|
||
|
||
If no dynamically evaluated menu-extensions should be added to the
|
||
history-buffer the function has to return nil. Therefore the
|
||
default-value of this option is @code{ignore}.
|
||
|
||
Per default the dynamic user-extensions are added in front of the
|
||
static extensions of @code{ecb-history-menu-user-extension} but the
|
||
whole menu can be re-arranged with @code{ecb-history-menu-sorter}.
|
||
@end defopt
|
||
|
||
@defopt history-show-node-info
|
||
When to display which node-info in the history-buffer.
|
||
Define which node info should be displayed after moving the mouse
|
||
over a node (or after a shift click onto the node) in the
|
||
history-buffer.
|
||
|
||
You can define ``when'' a node-info should be displayed:
|
||
See @code{ecb-directories-show-node-info} for the possible choices.
|
||
|
||
You can define ``which'' info should be displayed:
|
||
@itemize
|
||
@item name: Only the full node-name is displayed.
|
||
@item path: The full-path of the node is displayed.
|
||
@item name-path: The full node-name and the full-path is displayed.
|
||
@end itemize
|
||
|
||
Do NOT set this option directly via setq but use always customize!
|
||
@end defopt
|
||
|
||
@defopt history-sort-ignore-case
|
||
Ignore case for sorting the history-entries. See also
|
||
@code{ecb-history-sort-method}.
|
||
@end defopt
|
||
|
||
@defopt history-sort-method
|
||
Defines how the entries in the history-buffer are sorted.
|
||
@itemize @minus
|
||
@item @code{name}:
|
||
Sorting by name (default).
|
||
@item @code{extension}:
|
||
Sorting first by extension and then by name.
|
||
@item @code{nil}:
|
||
No sorting, means the most recently used buffers are on the top of the
|
||
history and the seldom used buffers at the bottom.
|
||
@end itemize
|
||
|
||
See also @code{ecb-history-sort-ignore-case}.
|
||
|
||
If the history is bucketized (see @code{ecb-history-make-buckets}) then this
|
||
sorting applies to the sorting within each bucket.
|
||
@end defopt
|
||
|
||
@defopt history-stick-indirect-buffers-to-basebuffer
|
||
Stick all indirect-buffers as subnodes to their base-buffer.
|
||
|
||
If 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}.
|
||
|
||
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 looks like:
|
||
|
||
@example
|
||
[-] <base-buffer BB>
|
||
| <indirect-buffer 1 of BB>
|
||
`- <indirect-buffer 2 of BB>
|
||
@end example
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt kill-buffer-clears-history
|
||
Define if @code{kill-buffer} should also clear the history. There are
|
||
three options:
|
||
|
||
@itemize @minus
|
||
@item @code{auto}:
|
||
Removes automatically the corresponding history-entry after the buffer
|
||
has been killed.
|
||
@item @code{ask}:
|
||
Asks, if the history-entry should be removed after the kill.
|
||
@item @code{nil}:
|
||
@code{kill-buffer} does not affect the history (this is the default).
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@node ecb-analyse, ecb-symboldef, ecb-history, Customizable options
|
||
@subsection Group ecb-analyse
|
||
|
||
@defopt analyse-bucket-element-face
|
||
Basic face for displaying elements of buckets in the
|
||
ECB-analyse-buffer. This defines the basic face for the elements of
|
||
category-buckets like Context, Prefix, Completions etc. in the
|
||
ECB-analyse-buffer.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt analyse-bucket-node-face
|
||
Basic face for displaying a bucket-node in the ECB-analyse-buffer.
|
||
This defines the basic face for the bucket-nodes like Context, Prefix,
|
||
Completions etc. in the ECB-analyse-buffer.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt analyse-buffer-after-create-hook
|
||
Local hook running after the creation of the analyse-buffer. Every
|
||
function of this hook is called once without arguments direct after
|
||
creating the analyse-buffer of ECB and it's local key-map. So for
|
||
example a function could be added which performs calls of
|
||
@code{local-set-key} to define new key-bindings only for the
|
||
analyse-buffer of ECB.
|
||
@end defopt
|
||
|
||
@defopt analyse-buffer-name
|
||
Name of the ECB analyse buffer. Because it is not a normal buffer for
|
||
editing you should enclose the name with stars, e.g. ``*ECB
|
||
Analyse*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the
|
||
buffer-object of the ECB-analyse-buffer by this name, e.g. by a call
|
||
of @code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after
|
||
deactivating and then activating ECB again!
|
||
@end defopt
|
||
|
||
@defopt analyse-buffer-sync
|
||
Synchronize the analyse buffer automatically with current edit buffer.
|
||
|
||
If 'always then the synchronization takes place always a buffer changes in the
|
||
edit window, if nil then never. If a list of major-modes then only if the
|
||
@code{major-mode} of the new buffer belongs NOT to this list.
|
||
|
||
Normally it's not necessary to exclude some major-modes because with
|
||
not-semantic supported major-modes simply nothing happens. But maybe it can be
|
||
helpful for certain situations...
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync}.
|
||
|
||
IMPORTANT NOTE: Every time the synchronization is done the hook
|
||
@code{ecb-analyse-buffer-sync-hook} is evaluated.
|
||
@end defopt
|
||
|
||
@defopt analyse-buffer-sync-delay
|
||
Time Emacs must be idle before the analyse-buffer is synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately.
|
||
|
||
CAUTION: With analysing a value not too small is strongly recommended because
|
||
it can be very annoying if more or less after each typing the current context
|
||
is analysed. If set to nil then *each* keyboard hit refreshes the
|
||
analyse-buffer which will make ECB quite unusable!
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync-delay}
|
||
@end defopt
|
||
|
||
@defopt analyse-buffer-sync-hook
|
||
ook run at the end of @code{ecb-analyse-buffer-sync}.
|
||
See documentation of @code{ecb-analyse-buffer-sync} for conditions when
|
||
synchronization takes place and so in turn these hooks are evaluated.
|
||
|
||
Preconditions for such a hook:
|
||
|
||
@itemize
|
||
|
||
@item Current buffer is the buffer of the currently selected
|
||
edit-window.
|
||
|
||
@item The analyse-buffer is displayed in a visible window of the
|
||
ecb-frame (so no check for visibilty of the analyse-buffer in
|
||
the ecb-frame is necessary in a hook function)
|
||
@end itemize
|
||
|
||
Postcondition for such a hook:
|
||
Point must stay in the same edit-window as before evaluating the hook.
|
||
|
||
Important note: If the option @code{ecb-analyse-buffer-sync} is not
|
||
nil the function @code{ecb-analyse-buffer-sync} is running either
|
||
every time Emacs is idle or even after every command (see
|
||
@code{ecb-analyse-buffer-sync-delay}). So if the anaylse-buffer is
|
||
displayed in a window of the ecb-frame (see preconditions above)
|
||
these hooks can be really called very often! Therefore each
|
||
function of this hook should/must check in an efficient way at
|
||
beginning if its task have to be really performed and then do
|
||
them only if really necessary! Otherwise performance of Emacs
|
||
could slow down dramatically!
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt analyse-collapsed-buckets
|
||
Buckets collapsed when displaying the current semantic analysis. The
|
||
semantic analyse-modul offers several categories of analysis which are
|
||
called buckets here. These are for example:
|
||
|
||
Context: The current context, which is the current function/method,
|
||
variable, class etc. (what exactly depends on the programming
|
||
language) point is in. This means not the current
|
||
function/method/variable/class-name point stand on but the current
|
||
surrounding context. Example: If point stays somewhere within a
|
||
defun-definition in emacs-lisp or within a java-method then this defun
|
||
rsp. method is the context. In object oriented languages this can be
|
||
the full hierachy, i.e. not only the current method, but the current
|
||
method, the class of this method, the superclass of this class and so
|
||
on!
|
||
|
||
Arguments: The arguments of the context if the context is a
|
||
function/method.
|
||
|
||
Local Variables: All accessible and bound local variables visible at
|
||
current point.
|
||
|
||
Prefix: The currently parsed prefix, which is mostly the current
|
||
identifier point stands on.
|
||
|
||
Assignee: See the semantic user-manual
|
||
|
||
Function: Current function-name point stands on.
|
||
|
||
Argument #: When point is located within a function-call then this is
|
||
the number of the argument point stands on.
|
||
|
||
Completions: All possible completions for current prefix (see above).
|
||
This is probably the most helpful bucket.
|
||
|
||
If one of these categories/buckets are not needed per default then add
|
||
the bucket-name (s.a.) to this option and ECB will per default
|
||
collapse this bucket. So most needed buckets are better visible in the
|
||
analyse-buffer.
|
||
@end defopt
|
||
|
||
@defopt analyse-face
|
||
Face used for highlighting current entry in the analyse buffer. If the
|
||
face @code{ecb-default-highlight-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-highlight-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt analyse-fontified-buckets
|
||
Buckets whose elements should be fontified as in the methods-buffer.
|
||
If the name of a category/bucket is contained in this option then all
|
||
elements of this bucket will be displayed as in the methods-buffer -
|
||
at least if an element is a semantic-tag. This means if
|
||
@code{ecb-font-lock-tags} is not nil these elements will be fontified
|
||
and also displayed with an appropriate icon if possible. The default
|
||
value does this only for the Context-bucket because for most of the
|
||
other buckets this makes not really much sense.
|
||
|
||
For available buckets see @code{ecb-analyse-collapsed-buckets}.
|
||
|
||
For the faces used to display a bucket-node itself or bucket-elements
|
||
not fontified see the options @code{ecb-analyse-bucket-node-face} rsp.
|
||
@code{ecb-analyse-bucket-element-face}.
|
||
@end defopt
|
||
|
||
@defopt analyse-gen-tag-info-fn
|
||
Which info should be displayed for a tag of the analyse-buffer. If nil
|
||
then the default information about a tag will be displayed. If a
|
||
function then this function gets as argument the tag for which
|
||
tag-information should be displayed. This function has to return a
|
||
string which will be then display as tag-info. This string has to be
|
||
fully formatted (e.g. must already include line-breaks if the tag-info
|
||
should be displayed in several lines).
|
||
|
||
See @code{ecb-analyse-show-tag-info-fn} how the tag-info is displayed.
|
||
@end defopt
|
||
|
||
@defopt analyse-general-face
|
||
Basic face for the ECB analyse buffer. This defines the basic face the
|
||
whole history buffer should displayed with. If the face
|
||
@code{ecb-default-general-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-general-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt analyse-show-node-info
|
||
When to display which node-info in the history-buffer. Define which
|
||
node info should displayed after moving the mouse over a node (or
|
||
after a shift click onto the node) in the history-buffer.
|
||
|
||
You can define ``when'' a node-info should be displayed: See
|
||
@code{ecb-directories-show-node-info} for the possible choices.
|
||
|
||
You can define what info should be displayed:
|
||
|
||
@itemize @minus
|
||
@item name: The full name of the node
|
||
@item full-info: All infos available to a node.
|
||
@end itemize
|
||
|
||
Do NOT set this option directly via setq but use always customize!
|
||
@end defopt
|
||
|
||
@defopt analyse-show-tag-info-fn
|
||
How to display the tag-info for a tag of the analyse-buffer. The value
|
||
of this option is a function which will be called with the info-string
|
||
generated for the current tag of the analyse-buffer. This function
|
||
must do all things necessary for displaying this info. When this
|
||
function is called the window stored in
|
||
@code{ecb-last-edit-window-with-point} is the selected window!
|
||
|
||
ECB offers two builtin ways: Display the info in the echo-area (via
|
||
the function @code{message}) or in a temp-buffer in the edit-area (via
|
||
the function @code{ecb-analyse-show-tag-info-in-temp-buffer}). Default
|
||
is echo-area-display.
|
||
|
||
See also @code{ecb-analyse-gen-tag-info-fn}.
|
||
@end defopt
|
||
|
||
@node ecb-symboldef, ecb-layout, ecb-analyse, Customizable options
|
||
@subsection Group ecb-analyse
|
||
|
||
@defopt symboldef-buffer-name
|
||
Name of the ECB-symbol-definition buffer.
|
||
Because it is not a normal buffer for editing you should enclose the name with
|
||
stars, e.g. ``*ECB Symboldefinition*''.
|
||
|
||
If it is necessary for you you can get emacs-lisp access to the buffer-object
|
||
of the ECB-symbol-definition-buffer by this name, e.g. by a call of
|
||
@code{set-buffer}.
|
||
|
||
Changes for this option at runtime will take affect only after deactivating and
|
||
then activating ECB again!
|
||
@end defopt
|
||
|
||
@defopt symboldef-buffer-sync
|
||
Synchronize the symboldef buffer automatically with current edit buffer.
|
||
|
||
If @code{always} then the synchronization takes place always a buffer changes in the
|
||
edit window, if nil then never. If a list of major-modes then only if the
|
||
@code{major-mode} of the new buffer belongs NOT to this list.
|
||
|
||
If the special value @code{basic} is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync}.
|
||
|
||
IMPORTANT NOTE: Every time the synchronization is done the hook
|
||
@code{ecb-symboldef-buffer-sync-hook} is evaluated.
|
||
@end defopt
|
||
|
||
@defopt symboldef-buffer-sync-delay
|
||
Time Emacs must be idle before the symboldef-buffer is synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately. A
|
||
small value of about 0.25 seconds saves CPU resources and you get even though
|
||
almost the same effect as if you set no delay.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync-delay}.
|
||
@end defopt
|
||
|
||
@defopt symboldef-buffer-sync-hook
|
||
ook run at the end of the function @code{ecb-symboldef-buffer-sync}.
|
||
See documentation of @code{ecb-symboldef-buffer-sync} for conditions when
|
||
synchronization takes place and so in turn these hooks are evaluated.
|
||
|
||
Preconditions for such a hook:
|
||
|
||
@itemize
|
||
@item Current buffer is the buffer of the currently selected edit-window.
|
||
@item The symboldef-buffer is displayed in a visible window of the
|
||
ecb-frame (so no check for visibilty of the symboldef-buffer in
|
||
the ecb-frame is necessary in a hook function)
|
||
@end itemize
|
||
|
||
Postcondition for such a hook:
|
||
Point must stay in the same edit-window as before evaluating the hook.
|
||
|
||
Important note: If the option @code{ecb-symboldef-buffer-sync} is not
|
||
nil the function @code{ecb-symboldef-buffer-sync} is running either
|
||
every time Emacs is idle or even after every command (see
|
||
@code{ecb-symboldef-buffer-sync-delay}). So if the symboldef-buffer is
|
||
displayed in a window of the ecb-frame (see preconditions above)
|
||
these hooks can be really called very often! Therefore each
|
||
function of this hook should/must check in an efficient way at
|
||
beginning if its task have to be really performed and then do
|
||
them only if really necessary! Otherwise performance of Emacs
|
||
could slow down dramatically!
|
||
@end defopt
|
||
|
||
@defopt symboldef-find-functions
|
||
Funtions to find the definition for current symbol under point.
|
||
This functionality is set on a major-mode base, i.e. for every major-mode a
|
||
different setting can be used. The value of this option is a list of
|
||
cons-cells:
|
||
|
||
@itemize
|
||
|
||
@item
|
||
The car is either a major-mode symbol or the special symbol 'default which
|
||
means if no setting for a certain major-mode is defined then the cdr of
|
||
the 'default cons-cell is used.
|
||
|
||
@item
|
||
The car is a function intended to find the definition of a certain symbol for
|
||
files of this major-mode. Such a function will be called with two arguments,
|
||
the first is the symbol-name as string for which the definition should be
|
||
displayed and the second the current edit-buffer as buffer-object,
|
||
i.e. the current buffer of the current edit-window. The function will be
|
||
called with the special ecb-symbol-definition-buffer as current buffer
|
||
whereas this buffer is empty. The function has to insert everything
|
||
necessary to display the symbol-definition and is also responsible to format
|
||
the displayed text. The buffer-local variable @code{fill-column is already preset
|
||
to the window-width of the special ecb-window minus 1. The function is
|
||
responsible to set the buffer-local variable `truncate-lines} appropriate.
|
||
The function can either return nil or a string which will be integrated in
|
||
the modeline-display of this ecb-window.
|
||
@end itemize
|
||
|
||
There are two prefined functions @code{ecb-symboldef-find-lisp-doc} and
|
||
@code{ecb-symboldef-find-definition} whereas the latter on is used a default
|
||
find-function.
|
||
@end defopt
|
||
|
||
@defopt symboldef-minimum-symbol-length
|
||
Minimum length a symbol must have so its definition or doc is displayed.
|
||
@end defopt
|
||
|
||
|
||
@node ecb-layout, ecb-compilation, ecb-symboldef, Customizable options
|
||
@subsection Group ecb-layout
|
||
|
||
@noindent
|
||
This group contains settings for the screen-layout of the ECB:
|
||
|
||
@defopt activate-before-new-frame-created-hook
|
||
Normal hook run before the new ECB-frame is created if
|
||
@code{ecb-new-ecb-frame} is not nil (otherwise this hook is not
|
||
evaluated).
|
||
@end defopt
|
||
|
||
@defopt advice-window-functions-signal-error
|
||
Signal an error if an adviced function can not do its job. If not nil
|
||
then an error is signaled if one of the adviced user-commands can not
|
||
do its job. So for example if the user tries to split the
|
||
compile-window or an ecb-tree-window or if one tries to switch to
|
||
another buffer in one of the ecb-tree-windows. For details see the
|
||
documentation of each of the adviced functions to get info when an
|
||
error is signaled.
|
||
|
||
If this option is nil then no error is signaled but the called adviced
|
||
function does simply nothing.
|
||
|
||
Default is nil but it can also be useful to signal errors - so you see
|
||
when call a function in a situation which is not supported by this
|
||
function.
|
||
@end defopt
|
||
|
||
@defopt fix-window-size
|
||
Fix size of the ECB-windows/buffers even after frame-resizing. The fix
|
||
type (valid values are nil, t, width and height) can either be set on
|
||
a layout-basis (means a different value for each layout) or one value
|
||
can be set for all layouts. For the latter case there is an additional
|
||
value @code{auto} which choose autom. the senseful fix-type depending
|
||
on the current layout-type: For top-layouts the fix-type @code{height}
|
||
and for all other layout-types the fix-type @code{width}.
|
||
|
||
For a detailed description of the valid values see documentation of
|
||
@code{window-size-fixed} which is newly introduced in GNU Emacs 21 and
|
||
is only available there. Therefore this option takes only effect with
|
||
GNU Emacs >= 21. This option has no effect with XEmacs because it does
|
||
not support the feature @code{window-size-fixed}.
|
||
|
||
Note1: Manually resizing the ECB-windows via @code{enlarge-window},
|
||
@code{shrink-window}, @code{mouse-drag-vertical-line} and
|
||
@code{mouse-drag-mode-line} is still possible even if the window-sizes
|
||
are fixed for frame-resizing!
|
||
|
||
Note2: The description of @code{window-size-fixed} in the
|
||
elisp-info-manual is more detailed than the description offered by
|
||
@kbd{C-h v}!
|
||
|
||
Note3: With Emacs < 22 there seems to be no distinction between
|
||
'width, 'height and t. Therefore this option takes no effect (means
|
||
all ecb-windows have always unfixed sizes) with Emacs < 22 if
|
||
@code{ecb-compile-window-height} is not nil.
|
||
|
||
Per default no window-size fixing has been done.
|
||
@end defopt
|
||
|
||
|
||
@defopt hide-ecb-windows-after-hook
|
||
Hooks run direct after the ECB windows have been hidden. Hiding was
|
||
done either by @code{ecb-toggle-ecb-windows} or
|
||
@code{ecb-hide-ecb-windows}.
|
||
|
||
IMPORTANT: Hiding the ECB-windows is internally done by calling
|
||
@code{ecb-redraw-layout} and therefore also the hooks
|
||
@code{ecb-redraw-layout-before-hook} and
|
||
@code{ecb-redraw-layout-after-hook} are evaluated. The hook-sequence
|
||
is analogous to that described in
|
||
@code{ecb-show-ecb-windows-after-hook}.
|
||
@end defopt
|
||
|
||
@defopt hide-ecb-windows-before-hook
|
||
Hook run direct before the ECB windows will be hidden. Hiding is done
|
||
either by @code{ecb-toggle-ecb-windows} or
|
||
@code{ecb-hide-ecb-windows}. This means that at runtime of this hook
|
||
all the ECB-tree-windows of current layout are visible.
|
||
|
||
IMPORTANT: Hiding the ECB-windows is internally done by calling
|
||
@code{ecb-redraw-layout} and therefore also the hooks
|
||
@code{ecb-redraw-layout-before-hook} and
|
||
@code{ecb-redraw-layout-after-hook} are evaluated. The hook-sequence
|
||
is analogous to that described in
|
||
@code{ecb-show-ecb-windows-before-hook}.
|
||
@end defopt
|
||
|
||
@defopt ignore-display-buffer-function
|
||
Adviced @code{display-buffer} ignores @code{display-buffer-function}.
|
||
This means, that the adviced version of @code{display-buffer} ignores
|
||
the value of @code{display-buffer-function} when called for the
|
||
@code{ecb-frame}. If this variable should not be ignored then the
|
||
function of @code{display-buffer-function} is completely responsible
|
||
which window is used for the buffer to display - no smart ECB-logic
|
||
will help to deal best with the ECB-window-layout! You can define if
|
||
and when @code{display-buffer-function} should be ignored:
|
||
|
||
@itemize @minus
|
||
@item
|
||
only when persistent compile window is used - i.e. if
|
||
@code{ecb-compile-window-height} is not nil
|
||
|
||
@item
|
||
always when ECB is active - that means ignore when ECB is active
|
||
otherwise not - this is the default value
|
||
|
||
@item
|
||
never, the adviced version of @code{display-buffer} always uses the
|
||
value of @code{display-buffer-function} if the value is a function.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt ignore-pop-up-frames
|
||
Ignore setting of option @code{pop-up-frames}.
|
||
This means, that a value of not nil for @code{pop-up-frames} is ignored:
|
||
@itemize
|
||
@item 'compile-window: only when persistent compile window is used - i.e. if
|
||
@code{ecb-compile-window-height} is not nil - this is the default value.
|
||
@item 'always: always when ECB is active - that means no pop-up-frames when ECB is active
|
||
@item @code{nil}: pop-up-frames is fully active when set
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt ignore-special-display
|
||
Ignore special-display-handling. This means, that all values of
|
||
@code{special-display-function}, @code{special-display-buffer-names}
|
||
and @code{special-display-regexps} are ignored
|
||
|
||
@itemize
|
||
@item
|
||
only when persistent compile window is used - i.e. if
|
||
@code{ecb-compile-window-height} is not nil - this is the default
|
||
value.
|
||
|
||
@item
|
||
always when ECB is active - that means no special-display-handling of
|
||
buffers when ECB is active
|
||
|
||
@item
|
||
never, i.e. special-dislay-handling depends on the values of the
|
||
options @code{special-display-function},
|
||
@code{special-display-buffer-names} and
|
||
@code{special-display-regexps}.
|
||
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt layout-always-operate-in-edit-window
|
||
Adviced window functions work always in the edit-window. If we are in
|
||
an ECB special buffer (methods, directories, etc), and any of the
|
||
adviced windowing functions is called interactively, we will select
|
||
first an edit-window according to the value of
|
||
@code{ecb-mouse-click-destination}. This is useful if you have any
|
||
functions that use such functions and you don't want them to fail with
|
||
an error complaining that the current buffer can not be split, or
|
||
something similar.
|
||
|
||
Because this may not be desirable in all situations and for all
|
||
adviced functions this can be enabled separately for function where it
|
||
is senseful. If the symbol of an adviced function is contained in the
|
||
value of this option, then the edit-window is first selected otherwise
|
||
either an error is reported or some other special reaction (depends on
|
||
@code{ecb-advice-window-functions-signal-error}); see the
|
||
documentation of the adviced functions for this.
|
||
|
||
Per default this is only enabled for @code{switch-to-buffer}.
|
||
@end defopt
|
||
|
||
|
||
@defopt layout-debug-mode
|
||
Write debug-information about layout-operations in the
|
||
Messages-buffer. Normally there should be no need to set this option
|
||
to true but if there are problems to display buffers in the
|
||
compile-window of ECB (e.g. buffers which should be displayed there
|
||
aren't or the temporally enlarging-mechanism does not do what you
|
||
think it should do etc...) then please do the following steps:
|
||
|
||
@enumerate
|
||
@item
|
||
Set @code{ecb-layout-debug-mode} to not nil
|
||
|
||
@item
|
||
Reproduce the wrong behavior exactly by repeating all the operations
|
||
which lead to the problem.
|
||
|
||
@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
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt layout-name
|
||
Select a window layout of ECB. Value is any arbitrary string. There are
|
||
four different types of layouts: left, right, top and left-right,
|
||
which means the location of the ECB-tree-windows in the ECB-frame.
|
||
Currently there are 20 predefined layouts; names see below. You can
|
||
savely try out any of them by changing this value and saving it only
|
||
for the current session. If you are sure which layout you want you can
|
||
save it for future sessions. To get a picture of the layout for name
|
||
<name> call `ecb-show-layout-help'. @code{ecb-layout-function-9}.
|
||
|
||
Currently available layouts:
|
||
|
||
@itemize @bullet
|
||
@item Left layouts:
|
||
left1 left2 left3 left4 left5 left6 left7 left8 left9 left10 left11
|
||
left12 left13 left14 left15
|
||
|
||
@item Right layouts:
|
||
right1
|
||
|
||
@item Top layouts:
|
||
top1 top2
|
||
|
||
@item Left-right layouts:
|
||
leftright1 leftright2
|
||
@end itemize
|
||
|
||
Regardless of the settings you define here: If you have destroyed or
|
||
changed the ECB-screen-layout by any action you can always go back to
|
||
this layout with @code{ecb-redraw-layout}
|
||
@end defopt
|
||
|
||
@defopt layout-window-sizes
|
||
Specifies the sizes of the ECB windows for each layout.
|
||
The easiest way (and also the very strongly recommended way) to set this
|
||
option is to change the window sizes by dragging the window borders using
|
||
the mouse and then store the window sizes by calling the command
|
||
@code{ecb-store-window-sizes}. Next time the layout is redrawn the values stored in
|
||
this option will be used.
|
||
|
||
If @code{ecb-store-window-sizes} is used then the windows sizes are stored per
|
||
default as fractions of current frame-width and -height of the ecb-frame, so
|
||
the stored values will ``work'' for other frame sizes too. But if you call
|
||
@code{ecb-store-window-sizes} with a prefix-argument then the fixed values of
|
||
current width and height are stored!
|
||
|
||
If this option is set ``by hand'' (i.e. not by @code{ecb-store-window-sizes}) then
|
||
the following is important:
|
||
@itemize
|
||
@item Use always @code{customize-option}, never @code{setq}!
|
||
@item It is recommended to use fractions of frame-width and -height!.
|
||
@item It is also recommended to use buffer-name-symbols instead of plain
|
||
buffer-names (e.g. ecb-history-buffer-name instead of " *ECB History*'')
|
||
@item There must be an entry for each special ecb-buffer of that layout for which
|
||
the sizes are stored.
|
||
@item The order of the sequence of the inserted window sizes doesn't matter
|
||
because each size-pair is assigned to a buffer-name the sizes belong to.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
@defopt maximize-ecb-window-after-selection
|
||
If not nil maximize current tree-window after selection. When
|
||
selecting another not-tree-window after such an automatic maximizing
|
||
all tree-windows of current layout are displayed again. But a
|
||
tree-window is not maximized if either a node has been selected via
|
||
primary- oder secondarc mouse-button or the popup-menu of that
|
||
tree-buffer has been opened.
|
||
@end defopt
|
||
|
||
@defopt maximize-next-after-maximized-select
|
||
Maximizes the next logical tree-window after a maximized
|
||
node-selection. Selecting a node in a maximized tree-window is handled
|
||
very smart by ECB:
|
||
|
||
If a tree-buffer-name is not contained in this option then selecting a
|
||
node in this maximized tree-buffer automatically ``minimizes'' that
|
||
tree-window (i.e. displays all windows of the current layout) so the
|
||
user can perform the next logical step (e.g. the next logical step
|
||
after selecting a directory in the directories-buffer is to select a
|
||
source-file - therefore the sources-buffer of current layout has to be
|
||
displayed - if the current layout contains one; the next logical step
|
||
of selecting a source-file is probably to jump to a certain tag via
|
||
the methods-buffer).
|
||
|
||
If a tree-buffer-name is contained in this option then selecting a
|
||
node in this tree-buffer automatically maximizes the next logical
|
||
tree-window (e.g. directories --> sources, sources/history -->
|
||
methods). But if the current maximized tree-buffer is also contained
|
||
in the option @code{ecb-tree-do-not-leave-window-after-select} (see
|
||
also the tree-buffer-command
|
||
@code{ecb-toggle-do-not-leave-window-after-select} which is bound to
|
||
@code{C-t} in each tree-buffer) then ECB does *not* maximize the next
|
||
logical tree-window but point stays in the currently maximized
|
||
tree-buffer so for example the user can select more than one node
|
||
(e.g. more than one source-file from the sources-buffer.
|
||
|
||
The tree-buffer-name can either be defined as plain string or with a
|
||
symbol which contains the buffer-name as value. The latter one is
|
||
recommended for the builtin ECB-tree-buffers because then simply the
|
||
related option-symbol can be used (e.g.
|
||
@code{ecb-directories-buffer-name}, @code{ecb-sources-buffer-name} or
|
||
@code{ecb-history-buffer-name}).
|
||
|
||
In future versions this option will probably also allow to define the
|
||
next logical tree-buffer for a tree-buffer - currently this is
|
||
hard-coded as follows:
|
||
@itemize @minus
|
||
@item directories --next-logical--> sources
|
||
@item sources --next-logical--> methods
|
||
@item history --next-logical--> methods.
|
||
@end itemize
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt maximize-next-after-maximized-select
|
||
Maximizes the next logical tree-window after a maximized
|
||
node-selection. Selecting a node in a maximized tree-window is handled
|
||
very smart by ECB:
|
||
|
||
If this option is nil then selecting a node in a maximized
|
||
directories- sources- or history-tree-buffer automatically
|
||
``minimizes'' that tree-window (i.e. displays all windows of the
|
||
current layout) so the user can perform the next logical step (e.g.
|
||
the next logical step after selecting a directory in the
|
||
directories-buffer is to select a source-file - therefore the
|
||
sources-buffer of current layout has to be displayed - if the current
|
||
layout contains one; the next logical step of selecting a source-file
|
||
is probably to jump to a certain tag via the methods-buffer).
|
||
|
||
If this option is not nil then selecting a node in a maximized
|
||
directories- sources- or history-tree-buffer automatically maximizes
|
||
the next logical tree-window (directories --> sources, sources/history
|
||
--> methods). But if the current maximized tree-buffer is contained in
|
||
the option @code{ecb-tree-do-not-leave-window-after-select} (see also
|
||
the tree-buffer-command
|
||
@code{ecb-toggle-do-not-leave-window-after-select} which is bound to
|
||
@code{C-t} in each tree-buffer) then ECB does *not* maximize the next
|
||
logical tree-window but point stays in the currently maximized
|
||
tree-buffer so for example the user can select more than one
|
||
source-file from the sources-buffer.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt new-ecb-frame
|
||
Create a new frame at activation time of ECB.
|
||
@end defopt
|
||
|
||
@defopt other-window-behavior
|
||
The behavior of ECB concerning getting an ``other window''. The
|
||
following settings are possible:
|
||
|
||
@code{all}:
|
||
|
||
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}.
|
||
|
||
@code{only-edit}:
|
||
|
||
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
|
||
it behaves like with value @code{all}.
|
||
|
||
@code{edit-and-compile}:
|
||
|
||
Like @code{only-edit} plus the compile window if any. If the selected
|
||
window is neither an edit-window nor the compile-window then it
|
||
behaves like with value @code{all}.
|
||
|
||
@code{smart}:
|
||
|
||
With this setting 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.
|
||
|
||
If there is an active minibuffer:
|
||
|
||
Regardless of the allowed values 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.
|
||
|
||
In addition to the allowed values above the value of this option can
|
||
also be a function:
|
||
|
||
A function:
|
||
|
||
This 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 then 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.
|
||
@code{ecb-get-other-window-smart} is an example for such a function.
|
||
@end defopt
|
||
|
||
@defopt redraw-layout-after-hook
|
||
Hooks run direct before the ECB windows will be shown either by
|
||
@code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
|
||
means that at runtime of this hook the ECB-windows are already
|
||
visible.
|
||
@end defopt
|
||
|
||
@defopt redraw-layout-before-hook
|
||
Hooks run direct before the ECB-layout will be redrawn by either
|
||
@code{ecb-redraw-layout}.
|
||
@end defopt
|
||
|
||
@defopt redraw-layout-quickly
|
||
If non-nil, we will attempt to redraw the layout quickly. Please read
|
||
also carefully the documentation of @code{ecb-redraw-layout}.
|
||
@end defopt
|
||
|
||
@defopt select-edit-window-on-redraw
|
||
Select the first edit window on @code{ecb-redraw-layout}.
|
||
@end defopt
|
||
|
||
@defopt show-ecb-windows-after-hook
|
||
Hooks run direct before the ECB windows will be shown either by
|
||
@code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
|
||
means that at runtime of this hook the ECB-windows are already
|
||
visible.
|
||
|
||
IMPORTANT: Showing the hidden ECB-windows is internally done by
|
||
calling @code{ecb-redraw-layout} and therefore also the hooks
|
||
@code{ecb-redraw-layout-before-hook} and
|
||
@code{ecb-redraw-layout-after-hook} are evaluated. So there is the
|
||
following sequence of hooks during the process of showing the hidden
|
||
ECB-windows:
|
||
@enumerate
|
||
@item @code{ecb-show-ecb-windows-before-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item <redrawing the layout to show the hidden ECB-windows>
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-show-ecb-windows-after-hook}
|
||
@end enumerate
|
||
So be aware which code you add to which hook!
|
||
@end defopt
|
||
|
||
@defopt show-ecb-windows-before-hook
|
||
Hooks run direct before the ECB windows will be shown either by
|
||
@code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
|
||
means that at runtime of this hook the ECB-windows are still hidden.
|
||
|
||
IMPORTANT: Showing the hidden ECB-windows is internally done by
|
||
calling @code{ecb-redraw-layout} and therefore also the hooks
|
||
@code{ecb-redraw-layout-before-hook} and
|
||
@code{ecb-redraw-layout-after-hook} are evaluated. So there is the
|
||
following sequence of hooks during the process of showing the hidden
|
||
ECB-windows:
|
||
@enumerate
|
||
@item @code{ecb-show-ecb-windows-before-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item <redrawing the layout to show the hidden ECB-windows>
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-show-ecb-windows-after-hook}
|
||
@end enumerate
|
||
So be aware which code you add to which hook!
|
||
@end defopt
|
||
|
||
|
||
@defopt split-edit-window-after-start
|
||
Sets if and how the edit window should be splitted after ECB-start.
|
||
But be aware: This option determines only if and how the edit-window
|
||
should be splitted at start-time of ECB. There are five different
|
||
values allowed for this option:
|
||
|
||
@itemize @minus
|
||
@item @code{nil}:
|
||
Do not split the edit-area of ECB after activation, i.e. there will be
|
||
only one edit-window after starting ECB.
|
||
|
||
@item @code{horizontal}:
|
||
Split the edit-area in 2 edit-windows side by side.
|
||
|
||
@item @code{vertical}:
|
||
Split the edit-area in 2 edit-windows, one above the other.
|
||
|
||
@item @code{before-activation}:
|
||
Split the edit-area as before the ECB-start, i.e. the edit-area will
|
||
have after start a window-layout as the whole frame had before the
|
||
start of ECB.
|
||
|
||
@item @code{before-deactivation}:
|
||
Split the edit-area into a window-layout ECB had in its edit-area
|
||
direct before the ECB-deactivation. This value preserves the full
|
||
state between activations of ECB, i.e. the visibility of the
|
||
ECB-windows, the visibility of a compile-window and also the full
|
||
split-state of the edit-area. But this can only be done if important
|
||
layout-options have not been changed in the meanwhile. These are the
|
||
options @code{ecb-layout-name}, @code{ecb-compile-window-height},
|
||
@code{ecb-compile-window-width}, @code{ecb-windows-width} and
|
||
@code{ecb-windows-height}.
|
||
@end itemize
|
||
|
||
Default value is @code{before-deactivation}.
|
||
|
||
Some remarks to the value @code{before-activation}: If this value has
|
||
been set then ECB needs three permanent adivces even when ECB is
|
||
deactivated: @code{split-window}, @code{delete-window} and
|
||
@code{delete-other-windows}. But these advices do not change any
|
||
behavior of these functions but only storing in an internal
|
||
ECB-variable the facts that a window has been splitted or deleted. In
|
||
addition to this these advices are 100% error-save, means the
|
||
functionality of the original functions will be performed in every(!)
|
||
case even if within the advice an error occurs (but normally there can
|
||
no errors occur in these advices because they are very simple).
|
||
Conclusion: If you want really all ECB-advices being disabled after
|
||
deactivating ECB then you have to set this option to other values then
|
||
@code{before-activation}. But setting this variable to this value is
|
||
really completely save.
|
||
@end defopt
|
||
|
||
@defopt toggle-layout-sequence
|
||
Toggle sequence for layout toggling with @code{ecb-toggle-layout}.
|
||
Every element of this list has to be a valid layout-name i.e. either
|
||
one of the predefined layouts or one of the user-defined layouts.
|
||
|
||
You can add here as many layouts as you want but to use this option
|
||
most effective you should not add more than 2 or 3 layouts so every
|
||
layout can be accessed very fast by toggling with
|
||
@code{ecb-toggle-layout}. It is also senseful to add layouts which
|
||
have the same principal outline, i.e. all their tree-buffers are on
|
||
the same side of the frame and the tree-buffer-''column'' (or
|
||
-''row'') has identical size for the layouts.
|
||
|
||
Recommended values are for example:
|
||
|
||
@itemize @minus
|
||
@item (``left10'' ``left15''), toggles between methods and directories/history
|
||
@item (``left10'' ``left13''), toggles between methods and directories
|
||
@item (``left10'' ``left14''), toggles between methods and history
|
||
@item (``left10'' ``left13'' ``left14''), toggles between methods, history and directories
|
||
@end itemize
|
||
|
||
See also option @code{ecb-show-sources-in-directories-buffer}.
|
||
|
||
This option makes only sense if the value is a list with more than 1
|
||
element!
|
||
@end defopt
|
||
|
||
@defopt windows-height
|
||
The height of the ECB windows in lines for top-layouts. If the number
|
||
is less than 1.0 the width is a fraction of the frame height.
|
||
@end defopt
|
||
|
||
@defopt windows-width
|
||
The width of the ECB windows in columns for left- and right layouts.
|
||
If the number is less than 1.0 the width is a fraction of the frame
|
||
width.
|
||
@end defopt
|
||
|
||
@node ecb-compilation, ecb-create-layout, ecb-layout, Customizable options
|
||
@subsection Group ecb-compilation
|
||
|
||
@noindent
|
||
This group contains settings for the compile window of ECB:
|
||
|
||
@defopt compilation-buffer-names
|
||
Additional buffer names that should be displayed in the
|
||
compile-window. Buffer names can either be defined as strings or as
|
||
regexps. If the buffer-name of a buffer matches one of the defined
|
||
string or regexp then it will be displayed in the compile-window of
|
||
ECB even if @code{compilation-buffer-p} says nil for this buffer.
|
||
|
||
It is not recommended to add the eshell-buffer-names to this list
|
||
because ECB already handles the eshell-integration as best as
|
||
possible (@pxref{Using eshell}).
|
||
|
||
See also the options @code{ecb-compilation-major-modes} and
|
||
@code{ecb-compilation-predicates}.
|
||
@end defopt
|
||
|
||
@defopt compilation-major-modes
|
||
Additional major-mode that should be displayed in the compile-window.
|
||
All buffers of a major-mode contained in this list are displayed in
|
||
the compile-window even if @code{compilation-buffer-p} says nil for
|
||
such a buffer.
|
||
|
||
It is not recommended to add @code{eshell-mode} to this list because
|
||
ECB already handles the eshell-integration as best as possible
|
||
(@pxref{Using eshell}).
|
||
@end defopt
|
||
|
||
@defopt compilation-predicates
|
||
Predicates when a buffer should be treated as compilation-buffer.
|
||
Every element of this list has to be a function or lambda-expression
|
||
which gets as argument a buffer-object and which has to return not nil
|
||
when this buffer should be treated as compilation-buffer (even if
|
||
@code{compilation-buffer-p} says nil) and therefore be displayed in
|
||
the compile-window of ECB (if there is any).
|
||
|
||
In combination with the values of @code{ecb-compilation-buffer-names}
|
||
and @code{ecb-compilation-major-modes} ECB decides when a buffer is
|
||
displayed in the compile-window.
|
||
|
||
Default value is the function @code{comint-check-proc} which returns
|
||
not nil when the buffer is related to a living process.
|
||
@end defopt
|
||
|
||
@defopt compile-window-height
|
||
Height of the persistent compilation-window of ECB. If you want a
|
||
compilation window shown at the bottom of the ECB-layout then set here
|
||
the height of it (Default is a height of 5). If you redraw the current
|
||
layout with @code{ecb-redraw-layout} then the compilation window (if
|
||
any) has the height you set here. If the number is less than 1.0 the
|
||
height is a fraction of the frame height.
|
||
|
||
If you do not set a persistent compilation window then doing a
|
||
compilation or displaying temp-buffers (e.g. *Help*-buffers) splits
|
||
temporally the edit window vertically if the edit window is not
|
||
splitted already or uses another edit window temporally for
|
||
compilation output if the edit window is already splitted. This is the
|
||
recommended value for this option because this is the
|
||
standard-behavior of Emacs.
|
||
|
||
Beware: If you set a persistent compilation window then ECB displays all
|
||
buffers for which @code{ecb-compilation-buffer-p} returns not nil in
|
||
that persistent compilation window. If a buffer which should being
|
||
displayed there is not displayed there then try to modify the options
|
||
@code{ecb-compilation-buffer-names},
|
||
@code{ecb-compilation-major-modes} or
|
||
@code{ecb-compilation-predicates} (in this sequence).
|
||
|
||
See also the options @code{ecb-compile-window-temporally-enlarge} and
|
||
@code{ecb-enlarged-compilation-window-max-height} and also the command
|
||
@code{ecb-toggle-compile-window-height}!
|
||
|
||
ECB offers the functionality of such a persistent compile-window
|
||
regardless if the special ECB-windows are visible or not (see the
|
||
command @code{ecb-toggle-ecb-windows}).
|
||
|
||
Regardless of the settings you define here: If you have destroyed or
|
||
changed the ECB-screen-layout by any action you can always go back to
|
||
this layout with @code{ecb-redraw-layout}
|
||
@end defopt
|
||
|
||
@defopt compile-window-prevent-shrink-below-height
|
||
Allow the compile-window to be shrunken below its height. A non nil
|
||
value means ECB prevents the compile-window from being shrunken below
|
||
the threshold of @code{ecb-compile-window-height} by displaying
|
||
temp-buffers (e.g. *Help* etc.) or after running compilations or
|
||
greps. But interactively it is always allowed to shrink it to every
|
||
height!
|
||
|
||
If nil then ECB does nothing to prevent being shrunken below the value
|
||
of @code{ecb-compile-window-height}.
|
||
|
||
Default is t.
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt compile-window-temporally-enlarge
|
||
Let Emacs temporally enlarge the compile-window of the ECB-layout.
|
||
This option has only an effect if @code{ecb-compile-window-height} is
|
||
not nil!
|
||
|
||
The following values are possible:
|
||
@itemize @minus
|
||
@item @code{after-display}:
|
||
After displaying a ``compilation-buffer'' (in the sense of
|
||
@code{ecb-compilation-buffer-p}!) in the compile-window of ECB. For
|
||
the max. height of the enlarged compile-window see the option
|
||
@code{ecb-enlarged-compilation-window-max-height}.
|
||
|
||
@item @code{after-selection}:
|
||
Selecting the @code{ecb-compile-window} auto. enlarges it and
|
||
de-selecting (means leaving @code{ecb-compile-window}) auto. shrinks
|
||
it. Enlarging and shrinking the @code{ecb-compile-window} is done with
|
||
@code{ecb-toggle-compile-window-height}. See also the
|
||
documentation of this function!
|
||
|
||
@item @code{both}:
|
||
The combination of 'after-display and 'after-selection.
|
||
|
||
@item @code{nil}:
|
||
ECB fixes always the height of the @code{ecb-compile-window} at the
|
||
value of @code{ecb-compile-window-height}.
|
||
@end itemize
|
||
|
||
To restore the ECB-layout after such a buffer-enlarge just call
|
||
@code{ecb-toggle-compile-window-height} or
|
||
@code{ecb-redraw-layout}.
|
||
@end defopt
|
||
|
||
@defopt compile-window-width
|
||
Width of the compile-window.
|
||
|
||
Possible values are @code{frame} and @code{edit-window}.
|
||
With @code{frame} the compile-window looks like:
|
||
|
||
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| edit-window(s) |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
With @code{edit-window} the compile-window looks like:
|
||
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| Directories | |
|
||
| | |
|
||
|--------------| edit-window(s) |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| |---------------------------------------
|
||
| | |
|
||
| | Compilation |
|
||
| | |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
This option takes only effect if @code{ecb-compile-window-height} is
|
||
not nil!
|
||
@end defopt
|
||
|
||
@defopt change-layout-preserves-compwin-state
|
||
Changing the layout preserves the state of the compile-window. This is
|
||
for example useful if the user toggles between several layouts (see
|
||
@code{ecb-toggle-layout}) and wants to preserve the hidden-state of
|
||
the compile-window.
|
||
@end defopt
|
||
|
||
|
||
@defopt enlarged-compilation-window-max-height
|
||
The max height of the compile-window after enlarging it. The max
|
||
height of the compilation window after enlarged by
|
||
@code{ecb-toggle-compile-window-height}. The following values are
|
||
allowed:
|
||
|
||
@code{best}:
|
||
|
||
ECB fits the height of the compile-window exactly to the size of its
|
||
current contents but never shrinks below the value of
|
||
@code{ecb-compile-window-height} or enlarges over the half of the
|
||
frame-height of the ECB-frame. The values of the options
|
||
@code{compilation-window-height} and @code{temp-buffer-max-height} are
|
||
taken into account dependent of the current @code{major-mode} of the
|
||
buffer in the compile-window: If @code{compilation-mode} then
|
||
@code{compilation-window-height} is used otherwise
|
||
@code{temp-buffer-max-height}.
|
||
|
||
@code{half}:
|
||
|
||
1/2 the frame-height of the ECB-frame
|
||
|
||
Any number:
|
||
|
||
Max height in lines. If the number is less than 1.0 the height is a
|
||
fraction of the frame height (e.g. 0.33 results in a max-height of 1/3
|
||
the frame-height).
|
||
@end defopt
|
||
|
||
@defopt scroll-other-window-scrolls-compile-window
|
||
@code{scroll-other-window} scrolls always the compile-window. For all
|
||
details about the scroll-behavior of @code{scroll-other-window} see
|
||
the advice documentation of @code{other-window-for-scrolling}.
|
||
@end defopt
|
||
|
||
|
||
@node ecb-create-layout, ecb-face-options, ecb-compilation, Customizable options
|
||
@subsection Group ecb-create-layout
|
||
|
||
@noindent
|
||
This group contains settings for creating new ECB-layouts:
|
||
|
||
@defopt create-layout-file
|
||
File where all layouts created by @code{ecb-create-new-layout} are
|
||
stored.
|
||
@end defopt
|
||
|
||
@defopt ecb-create-layout-frame-height
|
||
Frame height of the layout creation frame.
|
||
@end defopt
|
||
|
||
@defopt ecb-create-layout-frame-width
|
||
Frame width of the layout creation frame.
|
||
@end defopt
|
||
|
||
@node ecb-face-options, ecb-faces, ecb-create-layout, Customizable options
|
||
@subsection Group ecb-face-options
|
||
|
||
@noindent
|
||
This group contains settings for all faces used in ECB:
|
||
|
||
@defopt directories-general-face
|
||
Basic face for the ECB directories buffer. This defines the basic face
|
||
the whole directory buffer should displayed with. If the face
|
||
@code{ecb-default-general-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-general-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt directory-face
|
||
Face used for highlighting current directory in the directories
|
||
buffer. If the face @code{ecb-default-highlight-face} is used then the
|
||
display of all ECB-tree-buffers can be changed by modifying only the
|
||
face @code{ecb-default-highlight-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt directory-not-accessible-face
|
||
Face for not accessible dirs in the directories buffer.
|
||
@end defopt
|
||
|
||
@defopt history-bucket-node-dir-soure-path-face
|
||
Basic face for displaying the source-path part in a directory bucket.
|
||
This defines the face for the source-path part in a bucket-node of the
|
||
history-buffer if @code{ecb-history-make-buckets} is set to
|
||
'directory-with-source-path. For all other values of
|
||
@code{ecb-history-make-buckets} this option takes no effect.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
|
||
@defopt history-bucket-node-face
|
||
Basic face for displaying a bucket-node in the ECB-history-buffer.
|
||
This defines the basic face for the bucket-nodes used to bucketize the
|
||
history-entries as defined with the option @code{ecb-history-make-buckets}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt history-dead-buffer-face
|
||
Face for history entries pointing to dead buffers.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt history-face
|
||
Face used for highlighting current history-entry in the history
|
||
buffer. If the face @code{ecb-default-highlight-face} is used then the
|
||
display of all ECB-tree-buffers can be changed by modifying only the
|
||
face @code{ecb-default-highlight-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt history-general-face
|
||
Basic face for the ECB directory buffer. This defines the basic face
|
||
the whole history buffer should displayed with. If the face
|
||
@code{ecb-default-general-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-general-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt history-indirect-buffer-face
|
||
Face for indirect buffers in the history buffer.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
|
||
|
||
@defopt method-face
|
||
Face used for highlighting current method, class or variable in the
|
||
methods buffer. If the face @code{ecb-default-highlight-face} is used
|
||
then the display of all ECB-tree-buffers can be changed by modifying
|
||
only the face @code{ecb-default-highlight-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt method-non-semantic-face
|
||
Face used for for displaying tags of sources not supported by
|
||
semantic.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
|
||
@defopt methods-general-face
|
||
Basic face for the ECB methods buffer. This defines the basic face the
|
||
whole methods buffer should displayed with. If the face
|
||
@code{ecb-default-general-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-general-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt source-face
|
||
Face used for highlighting current source in the sources buffer. If
|
||
the face @code{ecb-default-highlight-face} is used then the display of
|
||
all ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-highlight-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt source-in-directories-buffer-face
|
||
Face for source files in the directories buffer.
|
||
@end defopt
|
||
|
||
@defopt sources-general-face
|
||
Basic face for the ECB sources buffer. This defines the basic face the
|
||
whole sources buffer should displayed with. If the face
|
||
@code{ecb-default-general-face} is used then the display of all
|
||
ECB-tree-buffers can be changed by modifying only the face
|
||
@code{ecb-default-general-face}.
|
||
|
||
Changes take first effect after finishing and reactivating ECB!
|
||
@end defopt
|
||
|
||
@defopt source-read-only-face
|
||
Face for read-only sources.
|
||
@end defopt
|
||
|
||
@defopt symboldef-prototype-face
|
||
Which face should be used for the symbol prototype in the symboldef-buffer.
|
||
|
||
The prototype can be the function prototype in case of a function or method or
|
||
- in case of a variable - the type of the variable (in case of a typed
|
||
language).
|
||
@end defopt
|
||
|
||
@defopt symboldef-symbol-face
|
||
Which face should be used for the symbol itself in the symboldef-buffer.
|
||
|
||
There are two choices: Either a face or the special symbol 'use-font-lock-face
|
||
whereas the latter one means that ECB uses that face font-lock uses for
|
||
fontifying the symbol (e.g. font-lock-function-name-face for a function
|
||
symbol or font-lock-variable-name-face for a variable symbol).
|
||
@end defopt
|
||
|
||
@defopt tag-header-face
|
||
Face used for highlighting the tag header after jumping to it by
|
||
clicking onto a node in the methods buffer.
|
||
@end defopt
|
||
|
||
|
||
|
||
@node ecb-faces, ecb-help, ecb-face-options, Customizable options
|
||
@subsection Group ecb-faces
|
||
|
||
@noindent
|
||
This group contains all faces used in ECB:
|
||
|
||
@table @code
|
||
@item ecb-bucket-node-face:
|
||
Face which can be used for displaying bucket tags in the methods
|
||
buffer. See also @code{ecb-bucket-node-display}.
|
||
|
||
@item ecb-default-general-face:
|
||
Basic face for all ECB tree-buffers.
|
||
It's recommended to define here the font-family, the font-size, the basic
|
||
color etc.
|
||
|
||
In GNU Emacs 21.X all faces (even the face
|
||
@code{ecb-default-highlight-face}) used in the ECB tree-buffers inherit
|
||
from this face. Therefore the default attributes like font etc. of a
|
||
face used in a tree-buffer can be very easily changed with face
|
||
@code{ecb-default-general-face}.
|
||
|
||
With XEmacs there is no inheritance-feature but the options
|
||
@code{ecb-directories-general-face}, @code{ecb-sources-general-face},
|
||
@code{ecb-methods-general-face} and @code{ecb-history-general-face}
|
||
offer the choice to use the face @code{ecb-default-general-face} so
|
||
also with XEmacs the basic face-settings can be easily changed just by
|
||
customizing the face @code{ecb-default-general-face}!
|
||
|
||
@item ecb-default-highlight-face:
|
||
Define basic face for highlighting the selected node in an ECB
|
||
tree-buffer.
|
||
|
||
In GNU Emacs 21.X all highlighting faces in the ECB tree-buffers
|
||
inherit from this face. Therefore the default attributes like font
|
||
etc. of a face used in a tree-buffer for highlighting the current
|
||
tag can be very easily changed with face
|
||
@code{ecb-default-highlight-face}.
|
||
|
||
With XEmacs there is no inheritance-feature but the options
|
||
@code{ecb-directory-face}, @code{ecb-source-face},
|
||
@code{ecb-method-face} and @code{ecb-history-face} offer the choice to
|
||
use the face @code{ecb-default-highlight-face} so also with XEmacs the
|
||
basic face-settings can be easily changed just by customizing the face
|
||
@code{ecb-default-highlight-face}!
|
||
|
||
@item ecb-directories-general-face:
|
||
Basic face for the ECB directories buffer. It<49>s recommended to define
|
||
here the font-family, the font-size, the basic color etc.
|
||
|
||
@item ecb-directory-face:
|
||
Define face used for highlighting current directory in the directories
|
||
buffer.
|
||
|
||
@item ecb-directory-not-accessible-face
|
||
Define a face for not accessible dirs in the directories buffer.
|
||
|
||
@item ecb-history-bucket-node-dir-soure-path-face:
|
||
Face used for displaying the source-path part in a directory-bucket.
|
||
|
||
In GNU Emacs 21.X this face inherits from the face
|
||
@code{ecb-history-bucket-node-face}.
|
||
|
||
With XEmacs and GNU Emacs 20.X there is no inheritance-feature so if the
|
||
buckets in the ECB-history-buffer should be displayed with the same basic
|
||
attributes set by @code{ecb-history-bucket-node-face} this set of basic
|
||
attributes have to be set in
|
||
@code{ecb-history-bucket-node-dir-soure-path-face} too!
|
||
|
||
@item ecb-history-bucket-node-face:
|
||
Face used for displaying a bucket-node in the ECB-history-buffer.
|
||
|
||
In GNU Emacs 21.X this face inherits from the face
|
||
@code{ecb-bucket-node-face}. With XEmacs and GNU Emacs 20.X there is no
|
||
inheritance-feature so if the buckets in the ECB-history-buffer should be
|
||
displayed with the same basic attributes set by @code{ecb-bucket-node-face}
|
||
this set of basic attributes have to be set in
|
||
@code{ecb-history-bucket-node-face} too!
|
||
|
||
@item ecb-history-dead-buffer-face:
|
||
Face used for history entries pointing to dead buffers.
|
||
|
||
In GNU Emacs 21.X this face inherits from the face
|
||
@code{ecb-history-general-face}. With XEmacs and GNU Emacs 20.X there is no
|
||
inheritance-feature so if the buckets in the ECB-history-buffer should be
|
||
displayed with the same basic attributes set by
|
||
@code{ecb-history-general-face} this set of basic attributes have to be set in
|
||
@code{ecb-history-dead-buffer-face} too!
|
||
|
||
@item ecb-history-face:
|
||
Define face used for highlighting current history-entry in the history
|
||
buffer.
|
||
|
||
@item ecb-history-general-face:
|
||
Basic face for the ECB history buffer. It<49>s recommended to define here
|
||
the font-family, the font-size, the basic color etc.
|
||
|
||
@item ecb-history-indirect-buffer-face:
|
||
Face used for history entries pointing to dead buffers.
|
||
|
||
In GNU Emacs 21.X this face inherits from the face
|
||
@code{ecb-history-general-face}. With XEmacs and GNU Emacs 20.X there is no
|
||
inheritance-feature so if the buckets in the ECB-history-buffer should be
|
||
displayed with the same basic attributes set by
|
||
@code{ecb-history-general-face} this set of basic attributes have to be set in
|
||
@code{ecb-history-indirect-buffer-face} too!
|
||
|
||
@item ecb-method-face:
|
||
Define face used for highlighting current method, class or variable in
|
||
the methods buffer.
|
||
|
||
@item ecb-methods-general-face:
|
||
Basic face for the ECB methods buffer. It<49>s recommended to define here
|
||
the font-family, the font-size, the basic color etc.
|
||
|
||
@item ecb-method-non-semantic-face:
|
||
Define face used for displaying tags of sources not supported by semantic.
|
||
|
||
@item ecb-mode-line-data-face
|
||
Define face for the data in the mode-line. See
|
||
@code{ecb-mode-line-data}.
|
||
|
||
@item ecb-mode-line-prefix-face
|
||
Define face for the prefix in the mode-line. See
|
||
@code{ecb-mode-line-prefixes}.
|
||
|
||
@item ecb-mode-line-win-nr-face
|
||
Define face for the window-number in the mode-line. See
|
||
@code{ecb-mode-line-display-window-number}.
|
||
|
||
@item ecb-source-face:
|
||
Define face used for highlighting current source in the sources
|
||
buffer.
|
||
|
||
@item ecb-source-in-directories-buffer-face:
|
||
Define a face for displaying sources in the directories buffer.
|
||
|
||
@item ecb-sources-general-face:
|
||
Basic face for the ECB sources buffer. It<49>s recommended to define here
|
||
the font-family, the font-size, the basic color etc.
|
||
|
||
@item ecb-source-read-only-face
|
||
Define a face for read-only sources
|
||
|
||
@item ecb-symboldef-prototype-face
|
||
Define face used for the prototype of symbol in the symboldef-buffer.
|
||
|
||
@item ecb-symboldef-symbol-face
|
||
Define a face used for the symbol itself in the symboldef-buffer
|
||
|
||
@item ecb-tag-header-face:
|
||
Define face used for highlighting the tag header after jumping to it
|
||
by clicking onto a node in the methods buffer.
|
||
|
||
@item ecb-tree-guide-line-face:
|
||
Define face for the guide-lines in the tree-buffers. See the option
|
||
@code{ecb-tree-buffer-style} for a explanation of guide-lines.
|
||
|
||
@item ecb-type-tag-class-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-enum-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-group-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-interface-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-struct-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-typedef-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@item ecb-type-tag-union-face:
|
||
Define face used with option @code{ecb-type-tag-display}.
|
||
|
||
@end table
|
||
|
||
Just call @code{customize-face <face-name>} to customize these faces
|
||
for your personal taste. Or customize the related option in the group
|
||
@ref{ecb-face-options}.
|
||
|
||
|
||
@node ecb-help, ecb-eshell, ecb-faces, Customizable options
|
||
@subsection Group ecb-help
|
||
|
||
@noindent
|
||
This group contains settings for the ECB online help:
|
||
|
||
|
||
@defopt help-html-path
|
||
Path where the ECB online help in HTML format resides. This must be
|
||
the location of the @file{ecb.html} which comes with the ECB
|
||
distribution. If is installed by unpacking the archive available on
|
||
the ECB website then this is the subdir @code{ecb-help-html-subdir} of
|
||
the installation directory of ECB. If it is installed as
|
||
XEmacs-package (e.g. via the package manager of XEmacs) then this is
|
||
probably either the directory ``../../html/'' or
|
||
``../../etc/ecb/html/'' (both relative to the Elisp directory of ECB).
|
||
|
||
The path can either be an absolute path or a path relative to the directory
|
||
where the Elisp files of ECB are.
|
||
|
||
Normally there should be no need to change this option!
|
||
@end defopt
|
||
|
||
|
||
@defopt help-info-path
|
||
Path where the ECB online help in info format resides. This must be
|
||
the location of the @file{ecb.info} which comes with the ECB
|
||
distribution. If is installed by unpacking the archive available on
|
||
the ECB website then this is the subdir @code{ecb-help-info-subdir} of
|
||
the installation directory of ECB. If it is installed as
|
||
XEmacs-package (e.g. via the package manager of XEmacs) then this is
|
||
probably the directory ``../../info/'' (relative to the Elisp directory
|
||
of ECB).
|
||
|
||
The path can either be an absolute path or a path relative to the directory
|
||
where the Elisp files of ECB are.
|
||
|
||
Normally there should be no need to change this option!
|
||
@end defopt
|
||
|
||
|
||
@defopt show-help-format
|
||
The format @code{ecb-show-help} shows its online help. Allowed values
|
||
are 'info (for the Info format) and 'html (for HTML format). If the
|
||
value is 'html then @code{browse-url-browser-function} says which
|
||
browser is used.
|
||
|
||
Note: If you got ECB as a standard XEmacs-package maybe the
|
||
HTML-online-documentation is not included.
|
||
@end defopt
|
||
|
||
@node ecb-eshell, ecb-speedbar, ecb-help, Customizable options
|
||
@subsection Group ecb-eshell
|
||
|
||
@noindent
|
||
This group contains settings for eshell integration within the ECB:
|
||
|
||
@defopt eshell-auto-activate
|
||
Startup the eshell and display it in the compile-window. If current
|
||
layout does not display a compile-window (see
|
||
@code{ecb-compile-window-height}) then nothing is done.
|
||
@end defopt
|
||
|
||
@defopt eshell-buffer-sync
|
||
Synchronize eshell with the default-directory of current source-buffer.
|
||
|
||
This option takes only effect if a permanant compile-window is used in the
|
||
current layout.
|
||
|
||
If 'always then the synchronization takes place always a buffer changes in the
|
||
edit window and if after this the default-directory of the new edit-buffer is
|
||
different from the default-directory of the current eshell-buffer. If value is
|
||
nil then never a synchronization will take place. If a list of major-modes
|
||
then only if the @code{major-mode} of the new buffer belongs NOT to this list.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync}.
|
||
@end defopt
|
||
|
||
@defopt eshell-buffer-sync-delay
|
||
Time Emacs must be idle before the eshell-buffer of ECB is synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately. A
|
||
small value of about 0.25 seconds saves CPU resources and you get even though
|
||
almost the same effect as if you set no delay.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync-delay}.
|
||
@end defopt
|
||
|
||
@defopt eshell-enlarge-when-eshell
|
||
Enlarge the compile-window if it is selected by @code{eshell}. This
|
||
takes only effect if the command @code{eshell} is called!
|
||
@end defopt
|
||
|
||
@defopt eshell-fit-window-to-command-output
|
||
Fit the compile-window after an eshell-command to the output. This is
|
||
done by the function @code{ecb-eshell-fit-window-to-output} which is
|
||
added to @code{eshell-post-command-hook} ie. which is running autom.
|
||
after each eshell-command.
|
||
@end defopt
|
||
|
||
@node ecb-speedbar, ecb-non-semantic, ecb-eshell, Customizable options
|
||
@subsection Group ecb-speedbar
|
||
|
||
@defopt speedbar-before-activate-hook
|
||
Hook running directly before ECB activates the integrated speedbar.
|
||
|
||
For example this hook can be used to change the expansion-mode of the
|
||
integrated speedbar via @code{speedbar-change-initial-expansion-list}.
|
||
Example: (speedbar-change-initial-expansion-list ``buffers'').
|
||
@end defopt
|
||
|
||
@defopt speedbar-buffer-sync
|
||
Synchronize the speedbar-buffer of ECB automatically with current
|
||
edit buffer.
|
||
|
||
If 'always then the synchronization takes place always a buffer changes in the
|
||
edit window, if nil then never. If a list of major-modes then only if the
|
||
@code{major-mode} of the new buffer belongs NOT to this list.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync}.
|
||
|
||
IMPORTANT NOTE: Every time the synchronization is done the hook
|
||
@code{ecb-speedbar-buffer-sync-hook} is evaluated.
|
||
@end defopt
|
||
|
||
@defopt speedbar-buffer-sync-delay
|
||
Time Emacs must be idle before the speedbar-buffer of ECB is synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately. A
|
||
small value of about 0.25 seconds saves CPU resources and you get even though
|
||
almost the same effect as if you set no delay.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
@code{ecb-basic-buffer-sync-delay}.
|
||
@end defopt
|
||
|
||
@defopt speedbar-buffer-sync-hook
|
||
ook run at the end of @code{ecb-speedbar-buffer-sync}.
|
||
See documentation of @code{ecb-speedbar-buffer-sync} for conditions when
|
||
synchronization takes place and so in turn these hooks are evaluated.
|
||
|
||
Preconditions for such a hook:
|
||
|
||
@itemize
|
||
|
||
@item Current buffer is the buffer of the currently selected
|
||
edit-window.
|
||
|
||
@item The speedbar-buffer is displayed in a visible window of the
|
||
ecb-frame (so no check for visibilty of the speedbar-buffer in
|
||
the ecb-frame is necessary in a hook function)
|
||
@end itemize
|
||
|
||
Postcondition for such a hook:
|
||
Point must stay in the same edit-window as before evaluating the hook.
|
||
|
||
Important note: If the option @code{ecb-speedbar-buffer-sync} is not
|
||
nil the function @code{ecb-speedbar-buffer-sync} is running either
|
||
every time Emacs is idle or even after every command (see
|
||
@code{ecb-speedbar-buffer-sync-delay}). So if the speedbar-buffer is
|
||
displayed in a window of the ecb-frame (see preconditions above)
|
||
these hooks can be really called very often! Therefore each
|
||
function of this hook should/must check in an efficient way at
|
||
beginning if its task have to be really performed and then do
|
||
them only if really necessary! Otherwise performance of Emacs
|
||
could slow down dramatically!
|
||
@end defopt
|
||
|
||
@node ecb-non-semantic, ecb-winman, ecb-speedbar, Customizable options
|
||
@subsection Group ecb-non-semantic
|
||
|
||
@noindent
|
||
This group contains settings for parsing and displaying non-semantic files:
|
||
|
||
@defopt auto-save-before-etags-methods-rebuild
|
||
Automatic saving of current buffer before rebuilding its methods.
|
||
|
||
This option is only relevant for sources which are supported and
|
||
parsed by etags (see @code{ecb-process-non-semantic-files}). Because
|
||
etags is an external tool a source-buffer can only be reparsed if the
|
||
buffer is saved to disk. So the command
|
||
@code{ecb-rebuild-methods-buffer} checks for sources which are not
|
||
supported by semantic or imenu if either this option is t or if the
|
||
major-mode of the source-buffer is contained in this list: In both
|
||
cases ECB saves the current source-buffer before it re-runs etags for
|
||
reparsing the source. If nil or if the major-mode is not contained
|
||
then no automatic saving will be done!
|
||
|
||
For all source supported by semantic or by imenu this option takes no
|
||
effect.
|
||
@end defopt
|
||
|
||
@defopt non-semantic-exclude-modes
|
||
Exclude modes from parsing with imenu or etags. Per default, ECB tries
|
||
to parse all file-types not supported by semantic with imenu or etags
|
||
or some other method (for details see the option
|
||
@code{ecb-non-semantic-parsing-function}). If a file-type can not be
|
||
parsed by semantic, imenu or etags than this simply results in an
|
||
empty method-buffer for this file. But nevertheless you will get a
|
||
message ``Sorry, no support for a file of that extension'' which comes
|
||
from the speedbar-library and can not switched off. Therefore if a
|
||
@code{major-mode} is known as not parse-able by semantic, imenu or etags
|
||
it can be added to this option and then it will be excluded from being
|
||
tried to parsed.
|
||
@end defopt
|
||
|
||
@defopt non-semantic-methods-initial-expand
|
||
Initially expand all tags for not by semantic supported sources.
|
||
This option can be customized on a major-mode basis, i.e. if a
|
||
@code{major-mode} is contained in this option then all tags for this
|
||
modes will be initially expanded - otherwise not.
|
||
@end defopt
|
||
|
||
@defopt non-semantic-parsing-function
|
||
Define mode-dependent parsing functions for non-semantic files. This
|
||
is an alist where the car is a major-mode symbol and the cdr is a
|
||
function-symbol of a function which should be used for parsing a
|
||
non-semantic buffer, i.h. a buffer for which no semantic grammar
|
||
exists. Such a function gets one argument - the filename of current
|
||
buffer - and has to generate and return a tag/tag list which is
|
||
understandable by @code{speedbar-insert-generic-list}. speedbar has
|
||
already included two functions @code{speedbar-fetch-dynamic-imenu} and
|
||
@code{speedbar-fetch-dynamic-etags} which can be used for parsing
|
||
buffers with imenu rsp. etags.
|
||
|
||
This option takes only effect if @code{ecb-process-non-semantic-files}
|
||
is not nil: Then ECB checks for non-semantic buffers if current
|
||
@code{major-mode} is contained in this option and if yes, then the
|
||
specified parsing function is called; if not then the cars of the
|
||
elements of @code{speedbar-dynamic-tags-function-list} are called in
|
||
that sequence they are listed in this variable. See option
|
||
@code{speedbar-dynamic-tags-function-list} for further details.
|
||
|
||
In most cases imenu-parsing is preferable over etags-parsing because
|
||
imenu operates on Emacs-buffers and needs no external tool and
|
||
therefore parsing works also if current contents of a buffer are not
|
||
saved to disk. But maybe sometimes etags may return better parsing
|
||
results
|
||
|
||
IMPORTANT: if imenu-parsing should be used then the option
|
||
@code{speedbar-use-imenu-flag} must be set to not nil!
|
||
@end defopt
|
||
|
||
@defopt process-non-semantic-files
|
||
Display content of non-semantic-files in the ECB-methods-buffer. See
|
||
also @code{ecb-non-semantic-parsing-function}.
|
||
@end defopt
|
||
|
||
@defopt rebuild-non-semantic-methods-before-hook
|
||
Hook running at beginning of the function
|
||
@code{ecb-rebuild-methods-buffer-for-non-semantic}. This function is
|
||
always called by the command @code{ecb-rebuild-methods-buffer} for not
|
||
semantic supported source-types.
|
||
|
||
Every function of this hook gets one argument: The complete filename
|
||
of the current source-buffer in the edit-window. The Method-buffer is
|
||
only rebuild by @code{ecb-rebuild-methods-buffer-for-non-semantic} if
|
||
either the hook contains no function (the default) or if no function
|
||
of this hook returns nil! See @code{run-hook-with-args-until-failure}
|
||
for description how these function are processed.
|
||
@end defopt
|
||
|
||
@node ecb-winman, ecb-mode-line, ecb-non-semantic, Customizable options
|
||
@subsection Group ecb-winman
|
||
|
||
@noindent
|
||
This group contains settings for supporting several window-managers:
|
||
|
||
@defopt winman-escreen-number
|
||
Number of the escreen which is reserved for ECB. If you go to the
|
||
escreen with this number you go always to the escreen with activated
|
||
ECB. All other escreen-numbers are escreens with deactivated ECB!
|
||
@end defopt
|
||
|
||
@defopt winman-winring-name
|
||
Name of the winring-window-configuration reserved for ECB. If you go
|
||
to the window-configuration with this name you go always to the
|
||
window-configuration with activated ECB. All other
|
||
window-configuration are configurations with deactivated ECB!
|
||
@end defopt
|
||
|
||
@node ecb-mode-line, ecb-version-control, ecb-winman, Customizable options
|
||
@subsection Group ecb-mode-line
|
||
|
||
@noindent
|
||
This group contains settings for the modelines of the
|
||
ECB-tree-buffers:
|
||
|
||
@defopt mode-line-data
|
||
Data shown in the modelines of the special ECB-buffers. Everey element
|
||
of this list is a cons-cell where the car is used to define a
|
||
buffer-name and the cdr to define the modeline-data for that buffer.
|
||
For details about how to defining a buffer-name see
|
||
@code{ecb-mode-line-prefixes} - its completely the same.
|
||
|
||
The cdr is the data for ths modeline and can either be the symbol
|
||
@code{sel-dir} or @code{sel-source} whereas the former one displays
|
||
the current selected directory as modeline-data and the latter one the
|
||
current selected source-file (without path).
|
||
|
||
In addition to these two predefined values for every special
|
||
ECB-buffer a plain string (which is displayed) or a function can be
|
||
specified which gets three args (name of the buffer, current selected
|
||
directory and current selected source-file) and must return a string
|
||
which will be displayed in the modeline (or nil if no data should be
|
||
displayed). Such a function can add the text-property @code{help-echo}
|
||
to the result-string. Then this help-string will be displayed when the
|
||
user moves the mouse over this section of the modeline.
|
||
|
||
If a special ECB-buffer should not display special data in its
|
||
modeline then this buffer-name should either not being added to this
|
||
option or added with ``No data'' (= nil as cdr).
|
||
|
||
The whole modeline of the special ECB-buffer consists of the prefix of
|
||
@code{ecb-mode-line-prefixes} and the data of
|
||
@code{ecb-mode-line-data} - eventually prepended by the window-number,
|
||
see @code{ecb-mode-line-display-window-number}.
|
||
@end defopt
|
||
|
||
@defopt mode-line-data-face
|
||
Face used for the data in the mode-line. See
|
||
@code{ecb-mode-line-data}. For XEmacs the face should inherit from the
|
||
face @code{modeline} (see @code{set-face-parent})!
|
||
@end defopt
|
||
|
||
|
||
@defopt mode-line-display-window-number
|
||
Display in the modeline of every special ECB-window the window-number.
|
||
The left-top-most window in a frame has the window-number 0 and all
|
||
other windows are numbered with increasing numbers in the sequence,
|
||
functions like @code{other-window} or @code{next-window} would walk
|
||
through the frame.
|
||
|
||
This can be used to jump to windows by number with commands like:
|
||
|
||
@lisp
|
||
@group
|
||
(defun my-switch-to-window-number (number)
|
||
``Switch to the nth window''
|
||
(interactive ``P'')
|
||
(if (integerp number)
|
||
(select-window (nth number (window-list)))))
|
||
@end group
|
||
@end lisp
|
||
|
||
Currently this feature is only available for GNU Emacs 21.X, because
|
||
neither GNU Emacs < 21 nor XEmacs can evaluate dynamically forms in
|
||
the mode-line.
|
||
@end defopt
|
||
|
||
@defopt mode-line-prefixes
|
||
Prefixes shown in the modelines of the special ECB-buffers. The
|
||
displayed prefix then looks like: ``[ <PREFIX>[: ]]'', means if a
|
||
prefix is defined for an special ECB-buffer then a single space is
|
||
prepended and if there is additional text to display (e.g. the current
|
||
directory in the sources buffer, see @code{ecb-mode-line-data}) then
|
||
also the string ``: '' is appended.
|
||
|
||
Everey element of this list is a cons-cell where the car is used to
|
||
define a buffer-name and the cdr to define the modeline-prefix for
|
||
that buffer.
|
||
|
||
The buffer-name can either be defined as plain string or with a symbol
|
||
which contains the buffer-name as value. The latter one is recommended
|
||
to define a prefix for one of the builtin ECB-tree-buffers because
|
||
then simply the related option-symbol can be used. To add a prefix for
|
||
the builtin directories tree-buffer just set the symbol
|
||
@code{ecb-directories-buffer-name} as car.
|
||
|
||
The cdr is the prefix for a buffer and can either be a string which
|
||
used as it is or a function-symbol which is called with three argument
|
||
(the buffer-name, the current selected directory and the current
|
||
selected source-file) and must return either nil (for no prefix) or a
|
||
string which is then used a prefix. Such a function can add the
|
||
text-property @code{help-echo} to the result-string. Then this
|
||
help-string will be displayed when the user moves the mouse over this
|
||
section of the modeline.
|
||
|
||
If a special ECB-buffer should not have a prefix in its modeline then
|
||
this buffer-name should either not being added to this option or added
|
||
with ``No prefix'' (= nil as cdr).
|
||
@end defopt
|
||
|
||
@defopt mode-line-prefix-face
|
||
Face used for the prefix in the mode-line. See
|
||
@code{ecb-mode-line-prefixes}. For XEmacs the face should inherit from
|
||
the face @code{modeline} (see @code{set-face-parent})!
|
||
@end defopt
|
||
|
||
@defopt mode-line-win-nr-face
|
||
Face used for the window-number in the mode-line. See
|
||
@code{ecb-mode-line-display-window-number}. For XEmacs the face should
|
||
inherit from the face @code{modeline} (see @code{set-face-parent})!
|
||
@end defopt
|
||
|
||
@node ecb-version-control, ,ecb-mode-line, Customizable options
|
||
@subsection Group ecb-version-control
|
||
|
||
@noindent
|
||
This group contains settings for the version-control-support of ECB:
|
||
|
||
@defopt vc-directory-exclude-regexps
|
||
Which directories should be excluded from VC-state-check. If a
|
||
directory matches any of the regexps of this option the VC-state of
|
||
its sources will not be checked - This option takes only effect if
|
||
@code{ecb-vc-enable-support} is not nil.
|
||
@end defopt
|
||
|
||
|
||
@defopt vc-enable-support
|
||
Enable support for version-control (VC) systems. If on then in the
|
||
directories-buffer (if the value of the option
|
||
@code{ecb-show-sources-in-directories-buffer} is on for current
|
||
layout), the sources-buffer and the history-buffer all file-items are
|
||
displayed with an appropriate icon in front of the item-name to
|
||
indicate the VC-state of this item. If off then no
|
||
version-control-state checking is done.
|
||
|
||
Because this check can be take some time if files are managed by a not
|
||
local Version-control-server ECB performs this check stealthy (see
|
||
@code{ecb-stealthy-tasks-delay}) so normally there should no
|
||
performance-decrease or additional waiting-time for the user. But to
|
||
get sure this option offers three choices: @code{t},
|
||
@code{unless-remote} and @code{nil}. See the option
|
||
@code{ecb-prescan-directories-for-emptyness} for an explanation for
|
||
these three choices.
|
||
|
||
The option @code{ecb-vc-directory-exclude-regexps} offers are more
|
||
fine granularity to exclude the sources of certain directories from
|
||
the VC-state-check.
|
||
|
||
See @code{ecb-vc-supported-backends} and @code{ecb-vc-state-mapping}
|
||
how to customize the VC-support itself.
|
||
@end defopt
|
||
|
||
@defopt vc-state-mapping
|
||
Mapping between VC-states from the backends and ECB-known VC-states.
|
||
ECB understands the following state-values:
|
||
|
||
@table @code
|
||
@item up-to-date
|
||
The working file is unmodified with respect to the latest version on
|
||
the current branch, and not locked.
|
||
|
||
@item edited
|
||
The working file has been edited by the user. If locking is used for
|
||
the file, this state means that the current version is locked by the
|
||
calling user.
|
||
|
||
@item needs-patch
|
||
The file has not been edited by the user, but there is a more recent
|
||
version on the current branch stored in the master file.
|
||
|
||
@item needs-merge
|
||
The file has been edited by the user, and there is also a more recent
|
||
version on the current branch stored in the master file. This state
|
||
can only occur if locking is not used for the file.
|
||
|
||
@item added
|
||
The working file has already been added/registered to the VC-system
|
||
but not yet commited.
|
||
|
||
@item unlocked-changes
|
||
The current version of the working file is not locked, but the working
|
||
file has been changed with respect to that version. This state can
|
||
only occur for files with locking; it represents an erroneous
|
||
condition that should be resolved by the user.
|
||
|
||
@item ignored
|
||
The version-control-system ignores this file (e.g. because included in
|
||
a .cvsignore-file in case of CVS).
|
||
|
||
@item unknown
|
||
The state of the file can not be retrieved; probably the file is not
|
||
under a version-control-system.
|
||
|
||
@end table
|
||
|
||
All state-values a check-vc-state-function of
|
||
@code{ecb-vc-supported-backends} can return must have a mapping to one
|
||
of the ECB-state-values listed above. If for a certain
|
||
backend-VC-state no mapping can be found then per default 'edited is
|
||
assumed!
|
||
|
||
The default value of this option maps already the possible returned
|
||
state-values of @code{vc-state} and @code{vc-recompute-state} (both
|
||
GNU Emacs) and @code{vc-cvs-status} (Xemacs) to the
|
||
ECB-VC-state-values.
|
||
@end defopt
|
||
|
||
@defopt vc-supported-backends
|
||
Define how to to identify the VC-backend and how to check the state.
|
||
The value of this option is a list containing cons-cells where the car is a
|
||
function which is called to identify the VC-backend for a DIRECTORY and the
|
||
cdr is a function which is called to check the VC-state of the FILEs contained
|
||
in DIRECTORY.
|
||
|
||
Identify-backend-function: It gets a full directory-name as argument - always
|
||
without ending slash (rsp. backslash for native Windows-XEmacs) - and has to
|
||
return a unique symbol for the VC-backend which manages that directory (e.g.
|
||
'CVS for the CVS-system or 'RCS for the RCS-system) or nil if the file is not
|
||
managed by a version-control-system.
|
||
|
||
Check-vc-state-function: It gets a full filename (ie. incl. the complete
|
||
directory-part) and has to return a symbol which indicates the VC-state of
|
||
that file. The possible returned values of such a check-vc-state-function have
|
||
to be mapped with @code{ecb-vc-state-mapping} to the allowed ECB-VC-state values.
|
||
|
||
ECB runs for a certain DIRECTORY all identify-backend-functions in that order
|
||
they are listed in this option. For the first which returns a value unequal
|
||
nil the associated check-state-function is used to retrieve the VC-state of
|
||
all sourcefiles in that DIRECTORY.
|
||
|
||
There is no need for the identify-backend-function or the
|
||
check-vc-state-function to cache any state because ECB automatically caches
|
||
internally all necessary informations for directories and files for best
|
||
possible performance.
|
||
|
||
To prepend ECB from checking the VC-state for any file set
|
||
@code{ecb-vc-enable-support} to nil.
|
||
|
||
Default value: Support for CVS, RCS, SCCS, Subversion, Git, Bazaar, Monotone
|
||
and Mercurial. To identify the VC-backend the functions
|
||
@code{ecb-vc-dir-managed-by-CVS}, @code{ecb-vc-dir-managed-by-RCS} rsp.
|
||
@code{ecb-vc-dir-managed-by-SCCS} rsp. @code{ecb-vc-dir-managed-by-SVN} rsp.
|
||
@code{ecb-vc--dir-managed-by-GIT} rsp. @code{ecb-vc-dir-managed-by-BZR} rsp.
|
||
@code{ecb-vc-dir-managed-by-MTN} rsp. @code{ecb-vc-dir-managed-by-HG}are used.
|
||
|
||
For all eight backends the function @code{ecb-vc-state} of the
|
||
VC-package is used by default (which uses a heuristic and
|
||
therefore faster but less accurate approach), but there is also
|
||
@code{ecb-vc-recompute-state} available which is an alias for
|
||
@code{vc-recompute-state} (which returns accurate state-values by calling the
|
||
backend which can be slow especialy for remote root-repositories!)
|
||
|
||
Example: If @code{ecb-vc-recompute-state} (to get real state-values not
|
||
only heuristic ones) should be used to check the state for CVS-managed files
|
||
and @code{ecb-vc-state} for all other backends then an element
|
||
(ecb-vc-dir-managed-by-CVS . ecb-vc-recompute-state) should be added at the
|
||
beginning of this option.
|
||
@end defopt
|
||
|
||
|
||
|
||
@node Submitting problem report, Upgrading, Customizing, Top
|
||
@chapter Submitting a problem report
|
||
|
||
@cindex Bug report
|
||
@cindex Problem report
|
||
If you run into problems with ECB you should first take a look into
|
||
|
||
@itemize @minus
|
||
@item @ref{FAQ} or
|
||
@item @ref{Conflicts and bugs} or
|
||
@item @ref{Common use-cases} or
|
||
@item the appropriate section of this online-manual.
|
||
@end itemize
|
||
|
||
If your problem(s) still remain you can/should send a problem report
|
||
to the ECB mailing list @email{ecb-list@@lists.sourceforge.net}. ECB
|
||
offers you a command which does all necessary for you to send a
|
||
problem report. Just call @code{ecb-submit-problem-report}! Please
|
||
read the documentation of this command, see @ref{Interactive ECB
|
||
commands}.
|
||
|
||
@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.
|
||
|
||
If you think there are problems concerning parsing-results for certain
|
||
sources supported by semantic then you should call
|
||
@code{ecb-dump-semantic-toplevel} for the problematic source-buffer
|
||
@strong{BEFORE} you call @code{ecb-submit-problem-report} because this
|
||
``dump''-command generates for the current-buffer a new buffer with
|
||
name ``*ecb-tag-dump*'' which contains all semantic-tags for this
|
||
source. The contents of this ``*ecb-tag-dump*'' will then autom. be
|
||
added to the problem-report generated by
|
||
@code{ecb-submit-problem-report}!
|
||
|
||
This command creates a problem-report buffer for you. After that you
|
||
get a menu ``Mail'' (dependent on the mail-package used, the menu can
|
||
have a different name) with commands to send the problem report. But
|
||
for this the variable @code{mail-user-agent} must be configured right for
|
||
your system. If you can<61>t get working this mechanism you can simply
|
||
copy the whole problem-report buffer after filling it out and sending
|
||
it with your standard mail-client to
|
||
@email{ecb-list@@lists.sourceforge.net}!
|
||
|
||
Please read also the documentation of the option @code{ecb-debug-mode} and
|
||
switch on the debug mode of ECB (also available in the Help-menu of
|
||
ECB!) before submitting a problem-report!
|
||
|
||
@node Upgrading, Common use-cases, Submitting problem report, Top
|
||
@chapter Upgrading and downloading packages
|
||
|
||
This chapter describes all aspects of upgrading to a newer version of
|
||
ECB.
|
||
|
||
The first section describes how to download and install a new
|
||
package from the web, where ``package'' means either ECB itself or the
|
||
required library CEDET
|
||
|
||
After installing a new ECB-version ECB checks if the values of the
|
||
customized ECB-options are still compatible. If not ECB does some
|
||
smart things. This is the topic of the second section.
|
||
|
||
@menu
|
||
* Downloading new versions:: How to download newer versions of packages
|
||
* Auto. option-upgrading:: ECB can auto. upgrade your options
|
||
@end menu
|
||
|
||
@node Downloading new versions, Auto. option-upgrading, Upgrading, Upgrading
|
||
@section Downloading new versions of ECB and/or CEDET
|
||
|
||
@cindex Download
|
||
|
||
@strong{Please note}: THE PACKAGE-DOWNLOAD-FEATURE OF ECB IS COMPLETELY
|
||
DEACTIVATED SINCE VERSION 2.33! Please got to the website of ECB and download
|
||
and install ``by hand'':
|
||
|
||
@enumerate
|
||
|
||
@item Download ECB
|
||
|
||
Go to
|
||
@ifhtml
|
||
@uref{http://ecb.sourceforge.net}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://ecb.sourceforge.net}
|
||
@end ifnothtml
|
||
and download the latest release (or if you are brave and tough the latest
|
||
CVS-snapshot) from the download section.
|
||
|
||
Save the archive (either *.tar.gz or *.zip) in a suitable location of your disk.
|
||
|
||
@item Extract the downloaded ECB-archive
|
||
|
||
Extract the archive with a suitable extraction-tool. The archive will extract
|
||
into a new directory @file{ecb-<version>} whereas <version> is either the
|
||
version number of the downloaded release or ``latest'' in case of the
|
||
CVS-snapshot. (example for a release: The archive extracts into a new
|
||
subdirectory @file{ecb-2.33}.
|
||
|
||
The newly created subdirectory contains all files of ECB in the needed
|
||
subdirectory structure.
|
||
|
||
@strong{Note}: Do not change the subdirectory structure of the extracted archive -
|
||
this will prevent ECB from working correctly!
|
||
|
||
@item Install and setup ECB
|
||
|
||
See @ref{Installation}.
|
||
|
||
@item Start ECB
|
||
|
||
ECB will perform some requirements checks, especially for CEDET.
|
||
@strong{Remark}: By setting the option @code{ecb-version-check} to
|
||
@code{nil} you can prevent ECB from checking correct versions of CEDET but
|
||
it's strongly recommended not to do this!
|
||
|
||
@item (Optional) Download and install a newer version of CEDET
|
||
|
||
If the version-check in (4) fails then you have to install a newer version of
|
||
CEDET which fulfill the version-number ECB reports to you after its version
|
||
check.
|
||
|
||
See the instruction of CEDET how to do this. You will find CEDET at
|
||
@ifhtml
|
||
@uref{http://cedet.sourceforge.net}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://cedet.sourceforge.net}
|
||
@end ifnothtml
|
||
|
||
For setting up CEDET see @ref{Setting up CEDET/semantic}.
|
||
|
||
If you have installed a new CEDET-version you @strong{MUST} re-byte-compile
|
||
ECB unless you run ECB not byte-compiled!
|
||
|
||
@end enumerate
|
||
|
||
@node Auto. option-upgrading, , Downloading new versions, Upgrading
|
||
@section Automatic upgrading of options
|
||
|
||
@menu
|
||
* User interface:: Options and commands you should know
|
||
* Background information:: Maybe some interesting informations
|
||
@end menu
|
||
|
||
@node User interface, Background information, Auto. option-upgrading, Auto. option-upgrading
|
||
@subsection User interface for option-upgrading
|
||
|
||
There are two interactive commands (@pxref{Interactive ECB commands}):
|
||
|
||
@itemize @minus
|
||
@item @code{ecb-upgrade-options}:
|
||
Does all necessary beginning with a incompatibility-check for all
|
||
options, upgrading/resetting incompatible options and ending with the
|
||
display of all upgraded or reset options.
|
||
|
||
@item @code{ecb-display-upgraded-options}:
|
||
Displays an information-buffer which options have been upgraded or
|
||
reset. Offers two buttons where the user can decide if the upgraded
|
||
options should also being saved by ECB for future settings or if the
|
||
buffer should be killed.
|
||
@end itemize
|
||
|
||
If the option @code{ecb-auto-compatibility-check} has a non-nil value
|
||
(which is the default) then ECB does all this stuff automatically at
|
||
startup. This is very recommended!
|
||
|
||
If you are interested in some background information, read
|
||
@ref{Background information}!
|
||
|
||
@node Background information, , User interface, Auto. option-upgrading
|
||
@subsection Background information
|
||
|
||
Big packages like ECB will be enhanced and developed continuously so
|
||
sometimes a new version must be released. Such packages offer in
|
||
general a lot of customizable options so probably some of these
|
||
options change the type or are renamed because the old type and/or
|
||
name of the option makes no sense in the new release.
|
||
|
||
Especially options which have changed the type of their value are now
|
||
a problem for the user which want to upgrade to the latest
|
||
ECB-version: If the user has saved a certain value for option X in its
|
||
file @file{.emacs} but the type of this saved value doesn't match the
|
||
new defined type in the defcustom-form after an ECB-upgrade then there
|
||
can occur serious problems like ECB can not be started anymore or even
|
||
Emacs can not be started without errors.
|
||
|
||
Until now there was only one way to fix these problems: The user must
|
||
manually edit his file @file{.emacs} and remove all entries for
|
||
options which have now another type. After this and after restarting
|
||
Emacs the new default-values of the type-changed options in the new
|
||
ECB-release are active and the user can go on using Emacs and ECB. But
|
||
this approach to fix the incompatible-option-problem has two serious
|
||
drawbacks:
|
||
|
||
@enumerate
|
||
@item
|
||
The user must manually edit the customize-section in his file
|
||
@file{.emacs}. This should normally not be done and if then only by
|
||
old-handed Emacs-users.
|
||
|
||
@item
|
||
The customized value of the option X in the old-release (with the old
|
||
type) is lost because after removing the related entry from the
|
||
file @file{.emacs} the new default-value is active, so the user must
|
||
re-customize the option X.
|
||
@end enumerate
|
||
|
||
OK, this is one half of the option-upgrade-problem but a new ECB-release
|
||
can also rename a option from name X to name Y because the new name Y makes
|
||
much more sense and/or is more mnemonic. If only the name has changed but
|
||
not the type this is not a serious problem like above but also annoying
|
||
because the customized value of the old-option X takes no effect in the new
|
||
release but instead the default-value of the new-option Y is now active.
|
||
But nevertheless this problem has the drawback number 2 (see above).
|
||
|
||
The last category of upgrade-problems is a renamed option which has also
|
||
changed its type.
|
||
|
||
@noindent
|
||
ECB has a solution for all these problems:
|
||
|
||
@itemize @bullet
|
||
|
||
@item
|
||
It checks all customized values of all ECB-options if they are still
|
||
type-compatible. If not then it tries to upgrade the old-value to the
|
||
new value-type and if this is not possible then it resets the option
|
||
to the new default value and offers then to store it via customize in
|
||
the .emacs-file (or in any file which is used for customized options).
|
||
But ECB does not touch any customization-file without asking the user!
|
||
|
||
@item
|
||
It offers a special constant @code{ecb-upgradable-option-alist} which
|
||
allows the ECB-maintainers to define special transformings for renamed
|
||
options so even the value of an old-option X can be savely transformed
|
||
to the new-option Y and the old setting is not lost.
|
||
@end itemize
|
||
|
||
All these checks and transformings are done at beginning of activating
|
||
ECB - if the option @code{ecb-auto-compatibility-check} is not nil. If
|
||
ECB has recognized incompatible or renamed options it does its
|
||
upgrading/reseting-job so all ECB-options have correct types so ECB
|
||
can start correct. After ECB is started it displays a list of all
|
||
upgraded or reseted option with their old and new values.
|
||
|
||
|
||
@node Common use-cases, Elisp programming, Upgrading, Top
|
||
@chapter Handling of common use-cases
|
||
|
||
@c TODO: Move some section to the Usage-chapter!!
|
||
|
||
This chapter lists some common (and also some non-common) use-cases of ECB and
|
||
gives a detailed description for each one. This contains also some tips and
|
||
tricks how to deal best with some situations.
|
||
|
||
@menu
|
||
* 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
|
||
@end menu
|
||
|
||
@node Changing faces, Small screens, Common use-cases, Common use-cases
|
||
@section Changing faces in the ECB tree-buffers
|
||
|
||
@cindex Faces
|
||
There are two basic faces:
|
||
|
||
@itemize @bullet
|
||
@item @code{ecb-default-general-face}:
|
||
Basic face for displaying an ECB-tree-buffer.
|
||
|
||
It<EFBFBD>s recommended to define the font-family, the font-size, the basic
|
||
color etc. with this face.
|
||
|
||
In GNU Emacs 21.X all faces (even the face
|
||
@code{ecb-default-highlight-face}) used in the ECB tree-buffers
|
||
inherit from this face. Therefore the default attributes like font
|
||
etc. of a face used in a tree-buffer can be very easily changed with
|
||
face @code{ecb-default-general-face}.
|
||
|
||
With XEmacs there is no inheritance-feature but the options
|
||
@code{ecb-directories-general-face}, @code{ecb-sources-general-face},
|
||
@code{ecb-methods-general-face} and @code{ecb-history-general-face}
|
||
offer the choice to use the face @code{ecb-default-general-face} so
|
||
also with XEmacs the basic face-settings can be easily changed just by
|
||
customizing the face @code{ecb-default-general-face}.
|
||
|
||
@item @code{ecb-default-highlight-face}:
|
||
Basic face for highlighting the current node in an ECB-tree-buffer.
|
||
|
||
In GNU Emacs 21.X all highlighting faces used in the ECB tree-buffers
|
||
inherit from this face. Therefore the default attributes like font
|
||
etc. of a highlighting face used in a tree-buffer can be very easily
|
||
changed with face @code{ecb-default-highlight-face}.
|
||
|
||
With XEmacs there is no inheritance-feature but the options
|
||
@code{ecb-directory-face}, @code{ecb-source-face},
|
||
@code{ecb-method-face} and @code{ecb-history-face} offer the choice to
|
||
use the face @code{ecb-default-highlight-face} so also with XEmacs the
|
||
basic face-settings can be easily changed just by customizing the face
|
||
@code{ecb-default-highlight-face}.
|
||
|
||
@end itemize
|
||
|
||
With these faces you can change the basic attributes easily and fast
|
||
for ALL ECB-tree-buffers. But you are also able to display each
|
||
ECB-tree-buffer with different faces, see the different options for
|
||
every tree-buffer mentioned above.
|
||
|
||
@strong{Please note} (only for XEmacs users): Cause of the lack of the
|
||
font-inheritance feature using ONE other font for the ECB-methods
|
||
buffer can NOT be achieved just by setting
|
||
@code{ecb-methods-general-face} to @code{ecb-default-general-face} and
|
||
changing the font of this default face. In addition you have to set
|
||
the same font also for the face @code{ecb-bucket-node-face} like in
|
||
the following example:
|
||
|
||
@example
|
||
(defconst my-ecb-font
|
||
"-outline-Courier-normal-normal-13-97-96-96-c-*-iso8859-1")
|
||
(set-face-font 'ecb-default-general-face my-ecb-font)
|
||
(set-face-font 'ecb-bucket-node-face my-ecb-font)
|
||
@end example
|
||
|
||
This code sets the new defined font @code{my-ecb-font} as font for
|
||
all@footnote{Of course @code{ecb-directories-general-face},
|
||
@code{ecb-sources-general-face}, @code{ecb-methods-general-face} and
|
||
@code{ecb-history-general-face} must be set to
|
||
@code{ecb-default-general-face}!} ECB-tree-buffers (incl. the methods
|
||
buffer).
|
||
|
||
@node Small screens, Big screens, Changing faces, Common use-cases
|
||
@section Working with small screens
|
||
|
||
@cindex Small screen
|
||
If your screen is very small so you need every square-centimeter for
|
||
displaying the buffer which you want to edit, ECB offers you a special
|
||
layouts, where only the ECB-methods buffer is displayed on top or on
|
||
left-side. Here comes what you should/can do to work best with ECB in
|
||
such a situation:
|
||
|
||
@itemize @bullet
|
||
@item First customize your ECB:
|
||
|
||
@enumerate
|
||
@item
|
||
Customize @code{ecb-layout-name} to layout-name ``top2'' (on top) or
|
||
``left9'' (on left-side)
|
||
|
||
@item
|
||
Ensure that @code{ecb-compile-window-height} is nil.
|
||
|
||
@item
|
||
Optional: Adjust the @code{ecb-windows-height} rsp. @code{ecb-windows-width}.
|
||
|
||
@item
|
||
Save your changes.
|
||
@end enumerate
|
||
|
||
@item To edit your buffers:
|
||
Call @code{ecb-toggle-ecb-windows} (also available via the menu ``ECB'' and
|
||
by @kbd{C-c . lw}) or @code{ecb-hide-ecb-windows} to hide the ECB-method buffer
|
||
so you get all the place of your screen for editing.
|
||
|
||
@item To browse and select functions:
|
||
Call @code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows} to
|
||
make the ECB-method buffer visible if not already. If you want select
|
||
a method/variable with the keyboard instead with the mouse you should
|
||
read the section @ref{Using the keyboard} in this online help!
|
||
@end itemize
|
||
|
||
The possibility of hiding temporally the ECB windows like described
|
||
above is also useful for all the other layouts.
|
||
|
||
|
||
@node Big screens, Simulating speedbar, Small screens, Common use-cases
|
||
@section Working with big screens
|
||
|
||
ECB offers a layout type ``left-right'' with special ECB-tree-windows
|
||
on the left and right side of the edit-area. The layouts
|
||
``leftright1'' and ``leftright2''are examples for this layout type.
|
||
See @ref{Creating a new ECB-layout} and @ref{The layout-engine}
|
||
for details about how to create or program more layouts of this type.
|
||
|
||
Such a layout is eventually the best choice for big screens because
|
||
the several ECB-tree-windows are bigger and can display more
|
||
informations without scrolling.
|
||
|
||
With such a layout it can could be senseful to reduce the value of the
|
||
option @code{ecb-windows-width} compared to layouts of type left or
|
||
right. A value of max. 0.25 should be enough.
|
||
|
||
@node Simulating speedbar, Integrating speedbar, Big screens, Common use-cases
|
||
@section Simulating speedbar without an extra frame
|
||
|
||
@cindex Speedbar
|
||
You can simulate a speedbar-like layout within ONE frame by doing the
|
||
following:
|
||
|
||
@enumerate
|
||
@item
|
||
Customize @code{ecb-layout-name} to layout name ``left9'', ``left12'',
|
||
``left13'' or ``left14'' dependent to what you like.
|
||
|
||
@item
|
||
Optional: Ensure that @code{ecb-compile-window-height} is nil.
|
||
|
||
@item
|
||
Optional: Adjust the @code{ecb-windows-width}.
|
||
|
||
@item
|
||
Optional: Customize @code{ecb-toggle-layout-sequence} and toggle very fast
|
||
between several layouts by @code{ecb-toggle-layout}. See the doc-strings!
|
||
|
||
@item
|
||
Optional: Customize @code{ecb-show-sources-in-directories-buffer} to
|
||
not nil if the chosen layout (see 1. and 4.) contains a
|
||
directories-tree-buffer.
|
||
|
||
@item
|
||
Save your changes.
|
||
@end enumerate
|
||
|
||
But not only simulating speedbar is possible but also full integrating
|
||
it into the ECB and the ECB-frame, @xref{Integrating speedbar}.
|
||
|
||
@node Integrating speedbar, Large directories, Simulating speedbar, Common use-cases
|
||
@section Integrating speedbar in the ECB-frame
|
||
|
||
It is very easy to integrate speedbar into ECB. There are two
|
||
different ways to do this:
|
||
|
||
@enumerate
|
||
@item
|
||
You can either use speedbar in the directories-, sources- or
|
||
methods-window of ECB instead of the built-in directory-, sources- or
|
||
methods-browser of ECB. This can be done via the option
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer}.
|
||
|
||
@item
|
||
Or you can integrate an extra speedbar-window into a layout
|
||
independent of the existence of a directory-, sources- or
|
||
methods-window. For this you can either use the built-in layout
|
||
``left-dir-plus-speedbar'' or you have to create your own layout
|
||
interactively with the command @code{ecb-create-new-layout}. This way
|
||
is not described in more details because there is nothing more to
|
||
describe - just create your layout.
|
||
@end enumerate
|
||
|
||
In general integrating speedbar into the ECB-frame makes sense for
|
||
people...
|
||
|
||
@itemize @bullet
|
||
@item
|
||
...who like the speedbar way of handling directories and source-files
|
||
but also like the ECB-way of displaying the buffer-contents (like
|
||
methods and variables in a source-file). This people should use the
|
||
option @code{ecb-use-speedbar-instead-native-tree-buffer} and set it
|
||
to @code{dir}.
|
||
|
||
@item
|
||
...who like the speedbar way of browsing things like directories,
|
||
files, file-contents etc. but who dislike the extra speedbar-frame.
|
||
@end itemize
|
||
|
||
Note: It is not necessary to integrate speedbar if you only want
|
||
parsing sources not supported by semantic. From version 1.94 on ECB
|
||
supports native parsing and displaying of such sources
|
||
(@pxref{Non-semantic sources})!
|
||
|
||
Regardless the group you belong, with the speedbar-integration feature
|
||
of ECB you can combine both worlds, the speedbar- and the ECB-world:
|
||
|
||
@enumerate
|
||
@item Choose a layout which either contains a directories- or a
|
||
sources-window but not both of them@footnote{Only one of them is
|
||
needed if you use speedbar because speedbar displays directories and
|
||
sources in one window. But if you like wasting space then you can also
|
||
use a layout with both windows...}.
|
||
|
||
Because speedbar has also display-modes for buffers and info-nodes and
|
||
some other useful things (which can be changed by the speedbar-command
|
||
@code{speedbar-change-initial-expansion-list} we recommend layouts
|
||
like ``left15'' or ``leftright3'' for using with speedbar.
|
||
|
||
@item Set the option
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} to not nil. After
|
||
this the chosen window of ECB will contain a full featured speedbar
|
||
(the only difference to standard speedbar is not residing in an extra
|
||
frame).
|
||
@end enumerate
|
||
|
||
Note: If you belong to the first group of people (s.a.) a similar
|
||
effect and usability is available by setting
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} to nil and setting
|
||
@code{ecb-show-sources-in-directories-buffer} to not nil, because this
|
||
combination displays also directories and sources in one window.
|
||
|
||
So with the option @code{ecb-use-speedbar-instead-native-tree-buffer}
|
||
you have the choice which way of displaying and handling ``things''
|
||
(directories, sources, methods...) you want (the speedbar- or the
|
||
ECB-way).
|
||
|
||
During speedbar is running within ECB (i.e.
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} is not nil) the
|
||
speedbar-command @code{speedbar} is disabled and the speedbar-command
|
||
@code{speedbar-get-focus} switches between the speedbar-window and the
|
||
edit-window@footnote{The standard behavior is switching between the
|
||
speedbar-frame and the attached frame, but this make obviously no
|
||
sense during running speedbar with ECB.}.
|
||
|
||
@strong{IMPORTANT}: ECB can only integrate speedbar-versions >=
|
||
0.14beta1! If you use lower versions of speedbar
|
||
@code{ecb-use-speedbar-instead-native-tree-buffer} has no effect.
|
||
|
||
@node Large directories, Remote directories, Integrating speedbar, Common use-cases
|
||
@section Working with large directories
|
||
|
||
If @code{ecb-source-path} contains directories with many files and
|
||
subdirs, especially if these directories are mounted net-drives
|
||
(``many'' means here something > 500, dependent on the speed of the
|
||
net-connection and the machine), actualizing the sources- and/or
|
||
directories- buffer of ECB (if displayed in current layout!) can slow
|
||
down dramatically. If this is a problem the contents of certain
|
||
directories and also the contents of the sources-buffer can be cached
|
||
which increases the speed a lot. See the option
|
||
@code{ecb-cache-directory-contents}.
|
||
|
||
IMPORTANT: The full speed-advantage of this cache-mechanism is only
|
||
available if @code{ecb-show-sources-in-directories-buffer} is
|
||
@code{nil}, i.e. sources of a directory are displayed in the
|
||
ECB-sources-window. The reason is that only with a sources window the
|
||
tree-buffer contents for the sources can be cached (i.e. the
|
||
buffer-content of the ECB-sources-window) whereas with sources
|
||
displayed in the directories buffer only the disk-contents of a
|
||
directory are cached - which increases speed too but not so much as
|
||
with sources displayed in the extra window ECB-sources.
|
||
|
||
The cache of a directory can be only refreshed by a POWER-click (with
|
||
mouse or keyboard) onto the related directory-node in the
|
||
directories-buffer of ECB (@pxref{Using the mouse}).
|
||
|
||
See also the option @code{ecb-cache-directory-contents-not}. Here are
|
||
some useful settings for both of these options:
|
||
|
||
@itemize @bullet
|
||
@item Cache all directories with more than 500 entries:
|
||
Set @code{ecb-cache-directory-contents} to ((``.*'' . 500)) and set
|
||
@code{ecb-cache-directory-contents-not} to nil.
|
||
|
||
@item Cache only all directories > 200 beginning with /usr/
|
||
Set @code{ecb-cache-directory-contents} to ((``^/usr/.*'' . 200)) and
|
||
set @code{ecb-cache-directory-contents-not} to nil.
|
||
|
||
@item Cache all directories > 500 but NOT these beginning with /usr/:
|
||
Set @code{ecb-cache-directory-contents} to ((``.*'' . 500)) and set
|
||
@code{ecb-cache-directory-contents-not} to (``^/usr/.*'').
|
||
@end itemize
|
||
|
||
Another way for getting a faster overlook for large directories with
|
||
many source-entries is to apply an online-filter to the
|
||
sources-buffer. This can be done via the command
|
||
@code{ecb-sources-filter} or via the popup-menu of the sources-buffer.
|
||
|
||
@node Remote directories, Version-control support, Large directories, Common use-cases
|
||
@section Working with remote directories
|
||
|
||
The term ``remote'' means directories which are remote in the sense of
|
||
TRAMP@footnote{TRAMP stands for 'Transparent Remote (file) Access,
|
||
Multiple Protocol'. This package provides remote file editing, similar
|
||
to ANGE-FTP.}, ANGE-FTP@footnote{This package attempts to make
|
||
accessing files and directories using FTP from within Emacs as simple
|
||
and transparent as possible.} or EFS@footnote{A system for transparent
|
||
file-transfer between remote hosts using the FTP protocol within
|
||
Emacs}. Each of these Emacs-addons is intended to make editing
|
||
directories and files on remote machines as transparent as possible.
|
||
|
||
@subsection General remarks
|
||
|
||
ECB supports such remote directoires out of the box and completely
|
||
transparently, i.e. you can add remote directories to the option
|
||
@code{ecb-source-path} without any restriction. ECB will handle these
|
||
directories transparently with the appropriate tool - either TRAMP,
|
||
ANGE-FTP or EFS. So when working with such a remote directory is
|
||
possible without ECB it will be possible too with active ECB - at
|
||
least as long you are ``connected''!
|
||
|
||
@strong{Caution}: Suppose you have added a remote dir (e.g.
|
||
``user@@host.at.a.server:/dir/'') to @code{ecb-source-path} and you
|
||
start ECB when you are offline, means there can be no connection
|
||
established to the remote computer (e.g. ``host.at.a.server''). Each
|
||
time ECB has to process a remote path ECB pings via the ping-program
|
||
the remote host (in the example above it would ping the host
|
||
``host.at.a.server'') to test if it is accessible. If not then this
|
||
path will be ignored by ECB@footnote{This avoids long lasting and
|
||
annoying blocking of ECB when a remote-path is not accessible: Without
|
||
a ping ECB would always try to open this directory through the
|
||
appropriate library (e.g. TRAMP) and it would depend on the
|
||
timeout-mechanism of this library (e.g. TRAMP has 60 seconds) how long
|
||
ECB would be blocked. First after this timeout ECB could start
|
||
working! A fast ``pre''-ping avoids this problem!}. Ensure that ECB
|
||
calls your ping-program (see @code{ecb-ping-program}) with the right
|
||
options (see @code{ecb-ping-options}). To avoid to many pings to the
|
||
same host ECB caches the ping result so there should be no performance
|
||
decrease. But to ensure still correct accessible-results and to avoid
|
||
using outdated cache-results ECB discards the cached value of the
|
||
accessible-state of a certain host after a customizable time-interval
|
||
(please read the documentation of
|
||
@code{ecb-host-accessible-check-valid-time}!).
|
||
|
||
|
||
@subsection Excluding remote directories from time-consuming tasks
|
||
|
||
ECB performs some tasks stealthily and interruptable by the user (see
|
||
the option @code{ecb-stealthy-tasks-delay} for additional
|
||
explanations) because these tasks are time-consuming and could
|
||
otherwise ECB block. Especially for remote directories these special
|
||
tasks can cause annoying blocks of Emacs (@pxref{Stealthy background
|
||
tasks}).
|
||
|
||
Therefore it is probably the best to switch on each of the stealthy
|
||
tasks with the @code{unless-remote} which is the default activation
|
||
(@pxref{Stealthy background tasks}). So a certain stealthy task will
|
||
be swtiched on for all local directories (and also for all mounted
|
||
drives in the LAN) but not for real remote directories used via TRAMP,
|
||
ANGE-FTP or EFS.
|
||
|
||
@subsection Caching the contents of remote directories
|
||
|
||
ECB caches per default the contents of remote directories to avoid
|
||
annoying delays. The cache is done via the option
|
||
@code{ecb-cache-directory-contents} which contains an entry which
|
||
covers the syntax of remote directories. If you do not want this
|
||
caching (which is strongly recommened) you have to remove this entry
|
||
from this option.
|
||
|
||
@node Version-control support, Using eshell, Remote directories, Common use-cases
|
||
@section Supporting Version control systems
|
||
|
||
Beginning with version 2.30 ECB supports Version-control systems (in
|
||
the following named VC-systems). This means the special tree-buffers
|
||
of ECB display files managed by a VC-system with an appropriate
|
||
image-icon@footnote{Of course only when Emacs is capable to display
|
||
images; otherwise a suitable ascii-icon will be displayed.} in front
|
||
of the filename.
|
||
|
||
The following four options allow full control over this feature (see
|
||
also @ref{ecb-version-control}:
|
||
|
||
@table @code
|
||
@item ecb-vc-enable-support
|
||
Enable or disable this feature.
|
||
@item ecb-vc-supported-backends
|
||
The most important option for this feature. Allows to specify how ECB
|
||
should test if a directory is managed by a VC-system (how to identify
|
||
the VC-backend of a directory) and - if yes - how it should check the
|
||
VC-state of a certain file. The former ones are called
|
||
@dfn{identify-backend-functions} and the latter ones
|
||
@dfn{check-state-functions}.
|
||
@item ecb-vc-directory-exclude-regexps
|
||
Allows excluding certain directories (on a regexp-basis) from the
|
||
VC-support even if they are managed by a VC-system.
|
||
@item ecb-vc-state-mapping
|
||
Defines the mapping between the state-values returned by a
|
||
check-state-function (a function set in
|
||
@code{ecb-vc-supported-backends} and used for getting the VC-state of
|
||
a file, e.g. @code{vc-state}) and the allowed state-values ECB can
|
||
understand.
|
||
@end table
|
||
|
||
Probably the default settings will fit your needs but to get sure you
|
||
should carefully read the documentation of these options!
|
||
|
||
The following subsection give you important informations about
|
||
identify-backend-functions, check-state-functions, about working with
|
||
remote repositories.
|
||
|
||
@menu
|
||
* 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
|
||
@end menu
|
||
|
||
@node Identifying backends, Checking the state, Version-control support, Version-control support
|
||
@subsection How ECB identifies the VC-backend of a dir
|
||
|
||
ECB tries all functions added as identify-backend-funtions to the
|
||
option @code{ecb-vc-supported-backends} until one of them returns not
|
||
@code{nil} but a symbol which identifies the backend (e.g.
|
||
@code{CVS}). After this check ECB stores the result of this check
|
||
(i.e. either the identified backend or the fact that the directory is
|
||
not managed by a VC-system) for that directory in a special cache, so
|
||
the identify-backend-process will be performed only once per
|
||
directory. If for a directory a VC-backend could be identified ECB
|
||
stores not only the backend itself for that directory but also the
|
||
associated check-state-function defined in
|
||
@code{ecb-vc-supported-backends} (@pxref{Checking the state}).
|
||
|
||
You can add arbitrary functions to this options as long as they get one
|
||
directory-argument and return either nil or a backend-symbol. Per default ECB
|
||
offers the following functions to identify the VC-backend CVS, RCS, SCCS, Git,
|
||
Monotone or Subversion@footnote{For this the most recent version of the VC-package
|
||
(incl. the libraries vc-git.el, vc-mono.el and vc-svn.el) is needed - as
|
||
contained in Emacs >= 22 and XEmacs >= 21.4.22}:
|
||
|
||
@table @code
|
||
@item ecb-vc-dir-managed-by-CVS DIRECTORY
|
||
Return @code{CVS} if DIRECTORY is managed by CVS. nil if not.
|
||
|
||
@item ecb-vc-dir-managed-by-RCS DIRECTORY
|
||
Return @code{RCS} if DIRECTORY is managed by RCS. nil if not.
|
||
|
||
@item ecb-vc-dir-managed-by-SCCS DIRECTORY
|
||
Return @code{SCCS} if DIRECTORY is managed by SCCS. nil if not.
|
||
|
||
@item ecb-vc-dir-managed-by-MTN DIRECTORY
|
||
return @code{MTN} if directory is managed by Monotone. nil if not.
|
||
|
||
@item ecb-vc-dir-managed-by-BZR DIRECTORY
|
||
return @code{BZR} if directory is managed by Bazaar. nil if not.
|
||
|
||
@item ecb-vc-dir-managed-by-GIT DIRECTORY
|
||
Return @code{GIT} if directory is managed by Git. nil if not.
|
||
Because with Git only the top-most directory of a source-tree has a subdir
|
||
.git this function tries recursively upwards if there is a .git-subdir.
|
||
|
||
@item ecb-vc-dir-managed-by-SVN DIRECTORY
|
||
Return @code{SVN} if DIRECTORY is managed by Subversion. nil if not.
|
||
Returns always nil if the library vc-svn.el can not be found.
|
||
|
||
@end table
|
||
|
||
If ECB should support another VC-backend than CVS, RCS, SCCS, Monotone, Git or
|
||
Subversion you have to write your own identify-backend-funtion for the used
|
||
VC-backend (e.g. Clearcase)!
|
||
|
||
@node Checking the state, Remote repositories, Identifying backends, Version-control support
|
||
@subsection How ECB checks the VC-state of a file
|
||
|
||
After ECB has identified the VC-backend of a directory it will display
|
||
the VC-state (e.g. up-to-date, edited, needs-mergs etc...) with a
|
||
suitable image-icon in the tree-windows of the ECB-file-browser. To
|
||
get this state for a certain file ECB uses that check-state-function
|
||
stored in the cache for the directory of that file (@pxref{Identifying
|
||
backends}).
|
||
|
||
You can add any arbitrary functions as check-state-function to
|
||
@code{ecb-vc-supported-backends} as long as they get one
|
||
filename-argument and return a state-symbol (e.g. @code{up-to-date}.
|
||
ECB can understand a certain set of state-values which are then
|
||
mapped to suitable image-icons which will in turn be displayed in
|
||
front of the filename in the file-browser. Because the values a
|
||
check-state-function return can differ from that state-values ECB
|
||
understands, ECB offers an option to define a appropriate
|
||
state-mapping. The name of this option is @code{ecb-vc-state-mapping}.
|
||
See the documentation of this option to get a list of all state-value
|
||
ECB understands.
|
||
|
||
Per default ECB uses the function @code{vc-state} of the
|
||
VC-package@footnote{The VC-package of Emacs offers a standardised and uniform
|
||
interface for several backends; per default CVS, RCS, SCCS, Subversion, Git
|
||
and Monotone are supported by the VC-package.} to check the state for the
|
||
backends CVS, RCS, SCCS, Subversion, Git and Monotone. So the default-value of
|
||
@code{ecb-vc-state-mapping} contains a mapping between these values
|
||
@code{ecb-vc-state} can return and that state-values ECB understands.
|
||
|
||
If ECB should support other VC-backends than CVS, RCS, SCCS, Monotone, Git and
|
||
Subversion (e.g. Clearcase) you should add that new backend to the VC-package
|
||
(see the initial comments of vc.el how to do this) then ECB will automatically
|
||
support that new backend. Alternatively it may be sufficient if you write your
|
||
own check-state-function for this backend and add the needed mapping to
|
||
@code{ecb-vc-state-mapping} if necessary.
|
||
|
||
@subsubsection Getting heuristic state-values or real ones for a backend
|
||
|
||
The interface of Emacs' VC-package offers two different ways to
|
||
get the VC-state of a file:
|
||
|
||
@itemize @bullet
|
||
@item The real, fresh and expensive approach
|
||
|
||
VC has a function @code{vc-recompute-state} which always performs a real
|
||
backend command (e.g. ``cvs status'' for CVS) to get a fresh and real state
|
||
for a file. As you can imagine this operation can be very expensive and long
|
||
lasting depending on the location of the repository. But for CVS the
|
||
CVS-backend of VC offers with the option @code{vc-cvs-stay-local} a way to
|
||
tell Emacs to stay local even for the sake of getting a real
|
||
state@footnote{For other backends you have to check the VC-manual if there is
|
||
equivalent option}.
|
||
|
||
ECB offers @code{ecb-vc-recompute-state} for this approach which is an alias
|
||
for @code{vc-recompute-state}.
|
||
|
||
@item The heuristic approach:
|
||
|
||
The function @code{vc-state} always returns a ``heuristic'' state
|
||
which should be used when a fresh and real state is not necessary.
|
||
With @code{vc-state} the option @code{vc-cvs-stay-local} will never
|
||
take effect.
|
||
|
||
ECB offers @code{ecb-vc-state} for this approach - see below for the
|
||
difference between @code{vc-state} and @code{ecb-vc-state}.
|
||
@end itemize
|
||
|
||
Example CVS:
|
||
|
||
VC/CVS actually does it this way (regardless if ECB is active or
|
||
not): When you visit a file, it always uses just the heuristic to get the
|
||
state (comparing file times), regardless of the setting of
|
||
@code{vc-cvs-stay-local}. This is because the "fresh-but-slow" state is
|
||
determined by calling "cvs status" on the file, and this was deemed
|
||
unacceptably slow if done at visiting time under any conditions.
|
||
|
||
The state is updated by calling @code{vc-recompute-state} prior to
|
||
@code{vc-next-action} (C-x v v) which either checks a file in or out.
|
||
IF @code{vc-cvs-stay-local} is nil, then this does in fact call "cvs
|
||
status" to get the "fresh-but-slow-state", but if
|
||
@code{vc-cvs-stay-local} is t, then it just compares the file times
|
||
again.
|
||
|
||
But under certain conditions (e.g. if called for files not already
|
||
visited or for files their VC-state has been changed from outside
|
||
Emacs, e.g. by checking in the file via command line) @code{vc-state}
|
||
does not compute a new heuristic state but returns a cached one
|
||
(cached by the VC-package itself not by ECB) which does not reflect
|
||
the current VC-state. Example: if you have edited a file within Emacs
|
||
and then checked in from outside Emacs @code{vc-state} returns a wrong
|
||
state until you call @code{revert-buffer} for this file. Therefore ECB
|
||
offers the check-state-function @code{ecb-vc-state} which does the
|
||
same as @code{vc-state} but it clears the internal caches of the
|
||
VC-package for that file before calling @code{vc-state}.
|
||
|
||
The bottom line for you is this: If you use @code{ecb-vc-state} in
|
||
@code{ecb-vc-supported-backends} to get the version control state, then you
|
||
get the same policy that VC uses and you get always a ``correct'' heuristic
|
||
state (as correct as possible a heuristic state can be). There should no harm
|
||
if you use @code{ecb-vc-recompute-state} (which is an alias for
|
||
@code{vc-recompute-state}) as a replacement function if you want to get fresh
|
||
and real state-values, but then (a) you must make sure to set
|
||
@code{vc-cvs-stay-local} to nil, and (b) fetching the state over the network
|
||
under all conditions was deemed unacceptably slow in VC.
|
||
|
||
@node Remote repositories, Refreshing the VC-state, Checking the state, Version-control support
|
||
@subsection Important informations about remote repositories
|
||
|
||
At least CVS can be used in a mode called ``Client/Server'' which
|
||
means the root repository is located on a remote machine. We call a
|
||
repository which can not being mounted by the client-machine (which
|
||
contains the working directory) a @dfn{remote repository}. In most
|
||
cases getting the fresh and real VC-state for such repositories will
|
||
be unacceptable slow or often users will work offline means with no
|
||
connection available to the remote host. To avoid problems like these
|
||
ECB offers first an option @code{ecb-vc-directory-exclude-regexps} to
|
||
exclude such directories with a remote repository from the VC-support
|
||
of ECB and secondary the identify-backend-funtion
|
||
@code{ecb-vc-dir-managed-by-CVS} behaves smart with that respect
|
||
(@pxref{Identifying backends}). See also
|
||
@code{ecb-vc-xemacs-exclude-remote-cvs-repository}!
|
||
|
||
@subsubsection Remote paths and the VC-support of ECB
|
||
|
||
ECB supports working with remote directories like TRAMP- or
|
||
EFS-directories (@pxref{Remote directories}). Do not confuse remote
|
||
directories with remote repositories. A local directory located on
|
||
your disk and set in @code{ecb-source-path} can have a remote
|
||
repository if managed by a VC-system. A remote directory means a path
|
||
in the format of TRAMP, ANGE-FTP or EFS set in @code{ecb-source-path}.
|
||
Its very likely that getting the VC-state of files contained in such a
|
||
remote directory would be extremly expensive and therefore ECB would
|
||
be blocked quite long even if the VC-check is performed stealthy
|
||
(@pxref{Stealthy background tasks}).
|
||
|
||
To avoid problems with such remote directories ECB prevents per
|
||
default such directories from being processed by the VC-support of
|
||
ECB. But if a user is dying to having the VC-state being displayed in
|
||
the tree-buffers ECB offers two ways to switch on the VC-support - see
|
||
the option @code{ecb-vc-enable-support}: This option is set per
|
||
default to the value @code{unless-remote} which means remote paths
|
||
will not be processed but it can be set to @code{t} which means
|
||
process all directories regardless if remote or not. It's strongly
|
||
recommended to use @code{unless-remote}!
|
||
|
||
@node Refreshing the VC-state, Adding new backends, Remote repositories, Version-control support
|
||
@subsection How to refresh ECB-state-display when changed outside
|
||
|
||
If all actions concerning version controlling of a file are performed
|
||
within Emacs with commands offeres by VC then the displayed state for
|
||
such a file in the tree-buffers of ECB will be always correct - in
|
||
that sense that ECB will always display that state which the
|
||
check-state-function for the file will return. At least with GNU Emacs
|
||
for the backends CVS, RCS, SCCS and Subversion this will be true. With
|
||
XEmacs only for CVS. For other backends see @ref{Adding new backends}.
|
||
|
||
But if the VC-state of a file will be changed outside of Emacs
|
||
(unfortunately PCL-CVS must be called ``outside'' too because PCL-CVS
|
||
doesn't use the functions of the VC-package of Emacs for checking-in
|
||
or -out) then ECB can not automatically recognize this and therefore
|
||
it can not aurtomatically update the displayed state-image-icon. You
|
||
have to tell ECB for which files in the tree-buffers the VC-state
|
||
should be recomputed. This can be done via the popup-menus of the
|
||
ECB-tree-buffers - The following popup-commands are offered in the
|
||
submenu ``Version Control'':
|
||
|
||
@table @asis
|
||
@item ECB-directories-buffer (if sources are displayed within):
|
||
``Recompute state for file'' and ``Recompute state for dir'' whereas
|
||
the latter one recomputes the VC-state for all files of that directory
|
||
the file belongs.
|
||
@item ECB-sources-buffer
|
||
``Recompute state for file'' and ``Recompute state for dir'' whereas
|
||
the latter one recomputes the VC-state for all files currently
|
||
displayed in the sources-buffer.
|
||
@item ECB-history-buffer
|
||
``Recompute state for file'' and ``Recompute state for whole history''
|
||
whereas the latter one recomputes the VC-state for all file-entries currently
|
||
displayed in the history-buffer.
|
||
@end table
|
||
|
||
@strong{Caution}: The state will only recomputed right under all
|
||
situations if you use either @code{ecb-vc-state} or
|
||
@code{vc-recompute-state} as check-state-function in
|
||
@code{ecb-vc-supported-backends} (@pxref{Checking the state}).
|
||
|
||
Of course all these commands update the VC-state in all visible
|
||
tree-buffers the file is currently displayed (e.g. often a file is
|
||
displayed in the sources- and the history-buffer)!
|
||
|
||
For general informations about the usage of popup-menus in ECB see
|
||
@ref{Using the mouse} (subsection ``The right mouse button'').
|
||
|
||
In addition to these popup-commands using the POWER- rsp. Shift-click
|
||
(@pxref{Using the mouse}) onto a directory in the directory-window of
|
||
ECB refreshes the VC-state-values of all files contained in this
|
||
directory too.
|
||
|
||
@node Adding new backends, Known VC-problems, Refreshing the VC-state, Version-control support
|
||
@subsection Necessary steps and informations for adding new backends
|
||
|
||
There are mainly three necessary steps for adding a new@footnote{i.e.
|
||
not already supported by the VC-package because all these backends are
|
||
automatically supported by ECB too!} backend BE which should be
|
||
supported by ECB:
|
||
|
||
@enumerate
|
||
@item Adding an identify-backend-function to @code{ecb-vc-supported-backends}
|
||
ECB needs a function how to identify the new backend BE for a certain
|
||
directory. If there exists already a library (other then VC)
|
||
supporting this backend then this library propably contains already
|
||
such a function which can be used or can be used at least with a small
|
||
elisp-wrapper. If no elisp-library for backend BE exists then you have
|
||
probably write the full identify-backend-function for your self. This
|
||
function has to be added to @code{ecb-vc-supported-backends}.
|
||
|
||
@item Adding an check-state-function to @code{ecb-vc-supported-backends}
|
||
Associated to the new identify-backend-function mentioned in step 1 a
|
||
new check-state-function is needed which can be used by ECB to get the
|
||
VC-state for a file. See @ref{Checking the state} for a description
|
||
about the needed interface of such a function. In combinatio with the
|
||
identify-backend-function from step 1 this function has to be added to
|
||
@code{ecb-vc-supported-backends}.
|
||
|
||
@item Enabling automatic state-update after checkin/out
|
||
|
||
This step is not essential if you do not need the displayed VC-state
|
||
automatically updated after a checkin/out of a file via the commands
|
||
available for backend BE (e.g. clearcase.el offers for the backend
|
||
Clearcase elisp-commands to checkin and checkout a file which then
|
||
should also update the displayed state in the ECB-tree-buffers. All
|
||
you need is a way to tell these commands that they should clear the
|
||
ECB-VC-cache for the file and then restart the ECB-VC-check-mechanism.
|
||
This should be done after these commands have finished their original
|
||
job.
|
||
|
||
ECB enables this per default for all backends supported by the
|
||
VC-package with the following code. Maybe this is a good starting
|
||
point.
|
||
|
||
@example
|
||
@group
|
||
(defvar ecb-checkedin-file nil
|
||
"Stored the filename of the most recent checked-in file. Is only set by the
|
||
after-advice of `vc-checkin' and `ecb-vc-checkin-hook' \(resets it to nil).
|
||
Evaluated only by `ecb-vc-checkin-hook'.
|
||
|
||
This is the communication-channel between `vc-checkin' and
|
||
`ecb-vc-checkin-hook' so this hook-function gets the filename of the
|
||
checked-in file.")
|
||
|
||
(defadvice vc-checkin (after ecb)
|
||
"Simply stores the filename of the checked-in file in `ecb-checkedin-file'
|
||
so it is available in the `vc-checkin-hook'."
|
||
(setq ecb-checkedin-file (ecb-fix-filename (ad-get-arg 0))))
|
||
|
||
(defun ecb-vc-checkin-hook ()
|
||
"Ensures that the ECB-cache is reset and the entry for the most recent
|
||
checkedin file is cleared. Uses `ecb-checkedin-file' as last checked-in file."
|
||
(when ecb-checkedin-file
|
||
(ecb-vc-cache-remove ecb-checkedin-file)
|
||
(ecb-vc-reset-vc-stealthy-checks)
|
||
(setq ecb-checkedin-file nil)))
|
||
@end group
|
||
@end example
|
||
|
||
@end enumerate
|
||
|
||
@node Known VC-problems, ,Adding new backends, Version-control support
|
||
@subsection Currently known problems with the VC-support
|
||
|
||
There are no reported problems concerning the Version Control support of ECB.
|
||
|
||
@node Using eshell, Grepping directories, Version-control support, Common use-cases
|
||
@section Optimal using of eshell in ECB
|
||
|
||
@cindex eshell
|
||
ECB offers a very smart integration of the ``eshell'' if you are using
|
||
a compile window (@pxref{Temp- and compile-buffers})@footnote{Of
|
||
course you can use eshell also if there is no compile-window. Then it
|
||
is just displayed in the edit-area and there is no special
|
||
integration.}
|
||
|
||
Here is a short summary of provided features:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Ability to jump to the eshell buffer within the compilation window by
|
||
simply call @code{eshell} (bound to @kbd{C-c . e}). If the eshell
|
||
isn't running it will be started.
|
||
|
||
@item
|
||
Expands the compilation window when you run commands. So for example
|
||
it allows you to view the eshell in minimized mode and then when you
|
||
run ``ls'' the window automatically expands (but always depending on
|
||
the output of the command you run).
|
||
|
||
@item
|
||
Synchronizes the current directory of the eshell with the current
|
||
buffer in the current active edit-window of ECB.
|
||
|
||
@item
|
||
Provides smart window layout of the eshell buffer. This makes sure
|
||
that the eshell is taking up the exact amount of space and that
|
||
nothing is hidden.
|
||
@end itemize
|
||
|
||
Here comes a detailed explanation of these features and how to use it
|
||
(all these features are only available if you use a persistent
|
||
compile-window, i.e. if @code{ecb-compile-window-height} is not nil):
|
||
|
||
You do not have to learn a new command for the eshell-start - just
|
||
call @code{eshell} (for convenience also bound to @kbd{C-c . e}) and
|
||
the eshell will displayed in the compile-window of ECB (if eshell is
|
||
not already alive then it will be started automatically).
|
||
|
||
|
||
ECB tries to display the contents of the eshell-buffer as best as
|
||
possible, means ECB can autom. enlarge and shrink the compile-window
|
||
so the contents of the eshell are fitting the window. See option
|
||
@code{ecb-eshell-enlarge-when-eshell} and
|
||
@code{ecb-eshell-fit-window-to-command-output}. Normally this is done
|
||
autom. but you can also you the standard compile-window
|
||
enlarging-command of ECB: @code{ecb-toggle-compile-window-height}.
|
||
|
||
ECB tries also to recenter the eshell-buffer as best as possible.
|
||
Normally this is done autom. but you can do it on demand with the
|
||
command @code{ecb-eshell-recenter}.
|
||
|
||
If option @code{ecb-eshell-buffer-sync} is true then ECB always
|
||
synchronizes the command prompt of eshell with the directory of
|
||
current source-buffer of the current active edit-window.
|
||
|
||
With the option @code{ecb-eshell-auto-activate} you can start eshell
|
||
autom. in the compile-window when ECB is started but of course if a
|
||
compile-window exists.
|
||
|
||
@node Grepping directories, Working with JDEE, Using eshell, Common use-cases
|
||
@section Grepping directories with ECB
|
||
|
||
ECB offers in the popup-menus in the directories- and
|
||
sources-tree-buffer commands for easy (recursive) grepping the current
|
||
directory under point (directory-buffer) rsp. the current-directory
|
||
(sources-buffer). In every case just the function of the options
|
||
@code{ecb-grep-function} rsp. @code{ecb-grep-find-function} is called
|
||
and the @code{default-directory} is tempor. set to the chosen
|
||
directory so the grep will performed in this directory regardless of
|
||
the @code{default-directory} of current buffer in the edit-window.
|
||
|
||
Other smart things beyond that are not done by ECB, see also
|
||
@code{ecb-grep-function}!
|
||
|
||
So, how to exclude some subdirectories or files from the grep?
|
||
|
||
Basically this has to be done with the ``-prune'' option of the
|
||
find-utility: If the standard-grep facility of Emacs is used then this
|
||
is not easy but with the command @file{igrep.el} there is a convenient
|
||
way to exclude things like CVS- or RCS-directories from the find-call:
|
||
See the variable @code{igrep-find-prune-clause} of the library
|
||
@file{igrep.el}.
|
||
|
||
@node Working with JDEE, Compile-window on demand, Grepping directories, Common use-cases
|
||
@section Working best with ECB and JDEE
|
||
|
||
ECB is completely language independent, i.e. it works with any
|
||
language supported by semantic (e.g. C, C++, Java, Elisp etc.).
|
||
|
||
But there are some special integrations for the great
|
||
Java-Development-Environment JDEE:
|
||
|
||
@itemize @bullet
|
||
@item Displaying contents of class under point
|
||
|
||
With the command @code{ecb-jde-display-class-at-point} you can display
|
||
the contents of the class which contains the definition of the
|
||
``thing'' at point (which can be a method, variable etc.).
|
||
|
||
@item Creating new source-files
|
||
|
||
The popup-menus in the directories- and the sources-buffer offer a
|
||
command ``Create Source'' which allows easy creating new java-sources
|
||
by calling the command @code{jde-gen-class-buffer}.
|
||
|
||
@item Adding user-extensions to the popup-menus
|
||
|
||
The options @code{ecb-directories-menu-user-extension} and
|
||
@code{ecb-sources-menu-user-extension}@footnote{If you need a dynamic
|
||
way of menu-extension then you should have a look at the options
|
||
@code{ecb-directories-menu-user-extension-function} and
|
||
@code{ecb-sources-menu-user-extension-function}.} allow adding often
|
||
used JDEE-commands to the popup-menus of the directories- or
|
||
sources-buffer. One example is to add building the project of current
|
||
directory. Here is a function which could be added to
|
||
@code{ecb-directories-menu-user-extension}:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-dir-popup-jde-build (node)
|
||
"Build project in directory."
|
||
(let ((project-file
|
||
(expand-file-name jde-ant-buildfile (tree-node-get-data node))))
|
||
(jde-ant-build project-file "build")))
|
||
@end group
|
||
@end example
|
||
|
||
Of course you can add entries to the option
|
||
@code{ecb-methods-menu-user-extension} and
|
||
@code{ecb-methods-menu-user-extension} too.
|
||
|
||
@end itemize
|
||
|
||
|
||
|
||
@node Compile-window on demand, Non-semantic sources, Working with JDEE, Common use-cases
|
||
@section Displaying the compile-window on demand
|
||
|
||
If you like displaying all output of compile/grep/etc. an all
|
||
temp-buffers like *Help*-buffers in an extra compile-window
|
||
(@pxref{Temp- and compile-buffers}) but you dislike wasting the space
|
||
of this compile-window if you are just editing then you can get a
|
||
compile-window ``on demand''. Just do the following:
|
||
|
||
@enumerate
|
||
@item
|
||
Customize @code{ecb-compile-window-height} to not nil and save it for
|
||
future sessions. This gives you an extra compile-window at the
|
||
bottom.
|
||
|
||
@item
|
||
Add the following to your .emacs:
|
||
|
||
@example
|
||
(add-hook 'ecb-activate-hook
|
||
(lambda ()
|
||
(let ((compwin-buffer (ecb-get-compile-window-buffer)))
|
||
(if (not (and compwin-buffer
|
||
(ecb-compilation-buffer-p compwin-buffer)))
|
||
(ecb-toggle-compile-window -1)))))
|
||
@end example
|
||
|
||
This hides the extra compile-window directly after the start of ECB
|
||
because there is no need for a compile-window at this moment. But the
|
||
hiding will not be done if there is a compile-window and if a
|
||
``compile-buffer'' in the sense of @code{ecb-compilation-buffer-p} is
|
||
displayed in this compile-window. Without this additional check the
|
||
compile-window would always be hidden after the ECB-start even when
|
||
ECB is reactivated after a deactivation by the window-manager-support
|
||
of ECB (@pxref{Window-managers and ECB}); but in these cases we want
|
||
to preserve the state before deactivation as good as possible (see
|
||
also option @code{ecb-split-edit-window-after-start}).
|
||
|
||
@end enumerate
|
||
|
||
This is all you have to do. Now if you run @code{compile} (or
|
||
@code{grep} or other compile-modes) or display temp-buffers like
|
||
*Help*-buffers then ECB autom. displays the compile-window at the
|
||
bottom and display the output there.
|
||
|
||
If you have finished with using the compile- or temp-output (e.g.
|
||
fixing errors) then you can throw away the compile-window just by
|
||
@code{ecb-toggle-compile-window} - ECB will reactivate it autom.
|
||
before next compilation or help-buffer-display.!
|
||
|
||
@node Non-semantic sources, Hide-show, Compile-window on demand, Common use-cases
|
||
@section Parsing and displaying non-semantic sources
|
||
|
||
ECB is mostly designed to display parsing information for files
|
||
supported by semantic. But beginning with version 1.94 it also
|
||
supports other parsing engines like imenu and etags, so also files not
|
||
supported by semantic but by imenu/etags can be displayed in the
|
||
Method-buffer of ECB. See @ref{Definition of semantic- and
|
||
non-semantic-sources} for a description of ``semantic-sources'' and
|
||
``non-semantic-sources''.
|
||
|
||
If support of non-semantic-sources is enabled then ECB will display
|
||
the contents of all sources which can be displayed by speedbar too.
|
||
This comes from the fact that ECB uses speedbar-logic to parse sources
|
||
with imenu or etags.
|
||
|
||
In most cases imenu-parsing is preferable over etags-parsing because
|
||
imenu operates on Emacs-buffers and needs no external tool and
|
||
therefore parsing works also if current contents of a buffer are not
|
||
saved to disk.
|
||
|
||
This section describes all important aspects about parsing and
|
||
displaying file-contents of file-types not supported by semantic but
|
||
by imenu and/or etags.
|
||
|
||
@subsection Enabling parsing and displaying of non-semantic-sources
|
||
|
||
Enabling is simply done with the option @code{ecb-process-non-semantic-files}.
|
||
|
||
ECB offers an option @code{ecb-non-semantic-parsing-function} to
|
||
specify on a major-mode basis which parsing-method should be used:
|
||
imenu or etags. Normally there should be no need to change this option
|
||
but read the documentation of this option (@pxref{ecb-non-semantic})
|
||
for further details.
|
||
|
||
IMPORTANT:
|
||
|
||
@itemize
|
||
@item
|
||
If imenu-parsing should be used then the option
|
||
@code{speedbar-use-imenu-flag} must be set to not @code{nil}!
|
||
|
||
@item
|
||
If some non-semantic-sources are not parsed (i.e. there is an empty
|
||
Methods-buffer) and you think that they should then maybe they are neither
|
||
supported by imenu nor by etags or you have to check the options
|
||
@code{ecb-non-semantic-parsing-function} and
|
||
@code{speedbar-dynamic-tags-function-list} and - especially for etags -
|
||
@code{speedbar-fetch-etags-parse-list}, @code{speedbar-fetch-etags-arguments}
|
||
and @code{speedbar-fetch-etags-command}.
|
||
|
||
@item
|
||
Even with support for semantic-, imenu- and etags-parsing there will
|
||
remain some file-types rsp. @code{major-modes} which are not
|
||
parse-able, neither by semantic, imenu nor etags. This is no problem
|
||
because these files simply have an empty Methods-buffer. But
|
||
nevertheless you will get a message ``Sorry, no support for a file of
|
||
that extension'' which comes from the speedbar-library and can not
|
||
switched off. Therefore if a @code{major-mode} is known as not
|
||
parse-able by semantic, imenu or etags it can be added to the option
|
||
@code{ecb-non-semantic-exclude-modes} and then it will be excluded
|
||
from being tried to parsed and this (annoying) message will not occur.
|
||
@end itemize
|
||
|
||
@subsection Automatic rescanning/reparsing of non-semantic-sources
|
||
|
||
In contrast to semantic (see @code{global-semantic-idle-scheduler-mode})
|
||
there is no built-in mechanism for autom. reparsing
|
||
non-semantic-sources and then updating the contents of the
|
||
Methods-buffer.
|
||
|
||
For non-semantic-sources you have always at least to call
|
||
@code{ecb-rebuild-methods-buffer} (bound to @kbd{C-c . r}) or saving
|
||
the source-file (if @code{ecb-auto-update-methods-after-save} is true)
|
||
to update the Method-buffer@footnote{Maybe future versions of ECB (>
|
||
1.94) will offer an autom. mechanism for this.}.
|
||
|
||
Depending on the parsing-mechanism the following options have to be
|
||
switched on so ECB can rebuild the methods-buffer for
|
||
non-semantic-sources:
|
||
|
||
@itemize @bullet
|
||
@item imenu:
|
||
|
||
The imenu-option @code{imenu-auto-rescan} must be enabled and
|
||
@code{imenu-auto-rescan-maxout} has to be set big enough to auto-parse
|
||
big files too! But this results not directly in an autom. updated
|
||
Method-buffer. This is first done after calling the command
|
||
@code{ecb-rebuild-methods-buffer} or saving the source-file (if
|
||
@code{ecb-auto-update-methods-after-save} is true).
|
||
|
||
@item etags:
|
||
|
||
Only if @code{ecb-auto-save-before-etags-methods-rebuild} is switched on
|
||
the command @code{ecb-rebuild-methods-buffer} rebuilds the
|
||
method-buffer with current source-contents. See description of this
|
||
option for an explanation.
|
||
@end itemize
|
||
|
||
Tip: If you want to program your own real. automatic
|
||
rescan/reparse/rebuild mechanism for non-semantic-sources you can do:
|
||
|
||
Adding to @code{after-change-functions} a function F which either runs
|
||
itself @code{ecb-rebuild-methods-buffer-for-non-semantic} or which
|
||
adds only another function FF to an idle-timer and the function FF
|
||
runs @code{ecb-rebuild-methods-buffer-for-non-semantic}. The latter
|
||
approach has the advantage that the reparse/rebuild is not performed
|
||
immediately after every change but first after Emacs is idle for a
|
||
senseful interval (e.g. 4 seconds) after last change. Of course the
|
||
function FF has to cancel its own idle-timer at the end, so the next
|
||
idle-timer is first started again after the next change (i.e. by
|
||
function F which is still contained in @code{after-change-functions}.
|
||
|
||
@subsection Customizing the display of the tags
|
||
|
||
For non-semantic-sources ECB uses does no special organizing of tags
|
||
in groups and sub-tags but it completely uses the tag-hierarchy the
|
||
imenu- and etags-parsers of speedbar return. So the displayed tag
|
||
hierarchy can only be customized with some options speedbar offers for
|
||
this:
|
||
|
||
@code{speedbar-tag-hierarchy-method},
|
||
@code{speedbar-tag-group-name-minimum-length},
|
||
@code{speedbar-tag-split-minimum-length} and
|
||
@code{speedbar-tag-regroup-maximum-length}. See the speedbar
|
||
documentation for details about these options.
|
||
|
||
With the option @code{ecb-method-non-semantic-face} you can define the
|
||
face used for displaying the tags in the Method-buffer for
|
||
non-semantic-sources.
|
||
|
||
@code{ecb-non-semantic-methods-initial-expand} can be useful too.
|
||
|
||
|
||
@node Hide-show, Window-managers and ECB, Non-semantic sources, Common use-cases
|
||
@section Using hide-show from the methods-buffer-menu
|
||
|
||
The popup-menu of the Methods-buffer offer two entries for either
|
||
hiding or showing the block which is related to the selected tag
|
||
(that tag for which the popup-menu was opened):
|
||
|
||
@itemize @bullet
|
||
@item ``Jump to tag and hide block'':
|
||
Jumps to the tag and calls @code{hs-hide-block} from the
|
||
hideshow-library which is shipped with (X)Emacs. After that the block
|
||
is hidden, i.e. only the header-line of that tag (method, variable
|
||
etc.) is visible, the rest is hidden behind the ``...''.
|
||
|
||
@item ``Jump to tag and show block'':
|
||
Jumps to the tag and calls @code{hs-show-block}. This shows the related
|
||
hidden block if the block was hidden via @code{hs-hide-block} or the
|
||
menu-entry ``Jump to tag and hide block'' (s.a.).
|
||
@end itemize
|
||
|
||
For this feature the library @file{hideshow.el} is used which should
|
||
normally being included in the (X)Emacs-distribution. If this library
|
||
is not loaded into Emacs, ECB does this automatically before the first
|
||
call to one of these menu-entries.
|
||
|
||
IMPORTANT: If in some @code{major-mode} hiding and showing does not
|
||
work as you expect it to work then you must probably add an entry for
|
||
this @code{major-mode} to the hideshow-variable
|
||
@code{hs-special-modes-alist}. See the documentation of this variable
|
||
for further details. One example of such a @code{major-mode} is
|
||
@code{jde-mode} of the Java Development Environment JDEE; just add an
|
||
entry for it like the already contained entries for @code{c++-mode} or
|
||
@code{java-mode} and hiding and showing will work for you with JDEE
|
||
too.
|
||
|
||
@node Window-managers and ECB, Virtual folders in History, Hide-show, Common use-cases
|
||
@section Support of several Emacs-window-managers
|
||
|
||
@cindex winring
|
||
@cindex escreen
|
||
@cindex window-manager
|
||
There are several window-managers available which offer an easy
|
||
interface to jump between different window-configurations within the
|
||
same frame. A window configuration is the layout of windows and
|
||
associated buffers within a frame. There is always at least one
|
||
configuration, the current configuration. You can create new
|
||
configurations and cycle through the layouts in either direction.
|
||
Window configurations are often named or numbered, and you can jump to
|
||
and delete named rsp. numbered configurations.
|
||
|
||
Without special support by ECB these window-managers would not work in
|
||
combination with ECB!
|
||
|
||
ECB currently supports the following managers:
|
||
|
||
@itemize @bullet
|
||
@item winring.el:
|
||
Written by Barry A. Warsaw @email{bwarsaw@@python.org}, available at
|
||
@ifhtml
|
||
@uref{http://www.python.org/emacs/winring}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://www.python.org/emacs/winring}
|
||
@end ifnothtml
|
||
|
||
@item escreen.el:
|
||
Written by Noah Friedman @email{friedman@@splode.com}, available at
|
||
@ifhtml
|
||
@uref{http://www.splode.com/~friedman/software/emacs-lisp/#ui}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://www.splode.com/~friedman/software/emacs-lisp/#ui}
|
||
@end ifnothtml
|
||
@end itemize
|
||
|
||
@strong{IMPORTANT}: With one of these window-managers installed and
|
||
active you can run applications like Gnus, VM or BBDB in the same
|
||
frame as ECB! Just use different window-configurations (winring.el) or
|
||
escreens (escreen.el) for ECB and the other applications. Especially
|
||
with winring.el you can give every configuration a descriptive name
|
||
like ``ECB'' or ``Gnus''; afterwards you can jump to a
|
||
window-configuration by name!
|
||
|
||
When you go back to the ECB-window-configuration (winring.el) or the
|
||
ECB-escreen (escreen.el) with any of the special
|
||
window-manager-commands then the state of ECB will be restored exactly
|
||
as you have left it when going to another window-configuration rsp.
|
||
escreen. This includes the whole splitting state of the edit-area and
|
||
the visibilty of the ecb-windows and of the compile-window!
|
||
|
||
The rest of this section describes how to enable the special
|
||
ECB-support for these window-managers and how to use them.
|
||
|
||
@subsection Enabling of the support
|
||
|
||
Every support must be enabled explicitly:
|
||
@itemize @bullet
|
||
@item winring:
|
||
Call @code{ecb-winman-winring-enable-support}. This @strong{MUST} be
|
||
done @strong{BEFORE} the first call to any winring-command, so also
|
||
before calling @code{winring-initialize}!
|
||
|
||
@item escreen:
|
||
Call @code{ecb-winman-escreen-enable-support}. This @strong{MUST} be
|
||
done @strong{BEFORE} the first call to any escreen-command, so also
|
||
before calling @code{escreen-install}!
|
||
@end itemize
|
||
|
||
If a window-manager-support should be enabled autom. after Emacs-start
|
||
just put the following into your @file{.emacs}:
|
||
|
||
@lisp
|
||
@group
|
||
(ecb-winman-winring-enable-support)
|
||
(winring-initialize)
|
||
|
||
;; or - if you like escreen more
|
||
|
||
(ecb-winman-escreen-enable-support)
|
||
(escreen-install)
|
||
@end group
|
||
@end lisp
|
||
|
||
@subsection Usage of a window-manager in combination with ECB
|
||
|
||
After enabling the support of one of the supported window-managers
|
||
just go on as described in the commentary or introduction of the
|
||
respective library-file(s) of the window-manager. Here is a short
|
||
description:
|
||
|
||
@itemize @bullet
|
||
@item winring:
|
||
First you have to define how to identify the ECB-window-configuration,
|
||
i.e. the configuration with activated ECB. This done with the option
|
||
@code{ecb-winman-winring-name}. There is always only one
|
||
window-configurations with name @code{ecb-winman-winring-name}!
|
||
|
||
Then run @code{winring-initialize}. If ECB is active then the
|
||
resulting window-configuration is the ECB-window-configuration.
|
||
Otherwise you can create the ECB-window-configuration when you first
|
||
time call @code{winring-new-configuration} with name equal to
|
||
@code{ecb-winman-winring-name}. In general you can run all commands of
|
||
the winring-library. If you jump to the ECB-window-configuration then
|
||
ECB will be autom. activated and if you leave the
|
||
ECB-window-configuration then ECB will autom. deactivated.
|
||
|
||
@item escreen:
|
||
First you have to define how to identify the ECB-escreen
|
||
i.e. that escreen with activated ECB. This done with the option
|
||
@code{ecb-winman-escreen-number}. There is always only one
|
||
escreen with number @code{ecb-winman-escreen-number}!
|
||
|
||
Then run @code{escreen-install} (deactivates ECB if currently
|
||
running). After that you can call @code{escreen-create-screen} and
|
||
@code{escreen-goto-screen}@footnote{And of course all other
|
||
@code{escreen-goto-*} commands!}. These commands autom. activate ECB
|
||
if creating or selecting the escreen with number
|
||
@code{ecb-escreen-number} (default = 1) and autom. deactivate ECB if
|
||
leaving the ECB-escreen.
|
||
@end itemize
|
||
|
||
@subsection Disabling the support
|
||
|
||
There is normally no need to do this but nevertheless it can be done
|
||
by @code{ecb-winman-escreen-disable-support} rsp.
|
||
@code{ecb-winman-winring-disable-support}.
|
||
|
||
@node Virtual folders in History, , Window-managers and ECB, Common use-cases
|
||
@section Something like virtual folders with the ECB-history
|
||
|
||
For example, there is a large project with a huge number of files, and there
|
||
are various tasks in this project (e.g. several different bug-fixing tasks).
|
||
So it could be convenient to group buffers according to various tasks, or with
|
||
other words: something like virtual folders for the buffers. It can be
|
||
fulfiled through using indirect buffers.
|
||
|
||
See the following example:
|
||
|
||
@example
|
||
task_1-aaa.pl
|
||
task_1-bbb.c
|
||
task_1-ccc.sh
|
||
task_2-aaa.pl
|
||
task_2-eee.c
|
||
task_2-ccc.sh
|
||
task_3-xxx.java
|
||
task_3-ccc.sh
|
||
@end example
|
||
|
||
This means create indirect buffers@footnote{Remember the most important
|
||
feature of indirect buffers: Changes made in one of them will immediately take
|
||
effect in all others with the same base-buffer} with a name-part which can be
|
||
used for grouping together buffers with same name-part (here e.g. task_1- ...
|
||
task_3-). In the example above you would create three indirect buffers for the
|
||
filebuffer ccc.sh because this source is needed in all three tasks, two
|
||
indirect buffers for aaa.pl because it is needed in the task-1 and task-2 and
|
||
so on for the rest of the buffers. Make all this indirect buffers with the
|
||
command @code{clone-indirect-buffer}@footnote{Currently only available with
|
||
GNU Emacs}, which creates real clones means the indirect buffers have the same
|
||
major-mode etc. as the base-buffer (see the manual of Emas).
|
||
|
||
Now remember to the option @code{ecb-history-make-buckets} which allows a.o.
|
||
to define a list of regular expressions to bucketize the buffers of the
|
||
history. Use this to make one bucket for each task. So in our example a value
|
||
|
||
@example
|
||
("^task_1-.+" "^task_2-.+" "^task_3-.+")
|
||
@end example
|
||
|
||
for @code{ecb-history-make-buckets} would satiesfy our needs.
|
||
|
||
This option allows to define several criterias for building buckets in the
|
||
history-buffer all the history entries are sorted in (e.g. by major-mode,
|
||
directory, file-extension or regular expressions).
|
||
|
||
After that the history-window would display something like the following:
|
||
|
||
@example
|
||
[-] [^task_1-.+]
|
||
| task_1-aaa.pl
|
||
| task_1-bbb.c
|
||
`- task_1-ccc.sh
|
||
[-] [^task_2-.+]
|
||
| task_2-aaa.pl
|
||
| task_2-eee.c
|
||
`- task_2-ccc.sh
|
||
[-] [^task_3-.+]
|
||
| task_3-xxx.java
|
||
`- task_3-ccc.sh
|
||
@end example
|
||
|
||
Hopefully this example could give an impression how the combination of usage
|
||
of indirect buffers and bucketizing the history-window can be used for
|
||
using one sources for different sake and grouping together what belongs
|
||
together.
|
||
|
||
@node Elisp programming, Conflicts and bugs, Common use-cases, Top
|
||
@chapter Entry points for Elisp programmers
|
||
|
||
This chapter describes how ECB can be used/programmed/driven by an
|
||
Elisp-program. This contains:
|
||
|
||
@menu
|
||
* 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
|
||
@end menu
|
||
|
||
@node List of variables, List of hooks, Elisp programming, Elisp programming
|
||
@section Variables for Elisp-programs
|
||
|
||
Variables an Elisp-program can use beyond those ones mentioned in
|
||
@ref{The layout-engine}:
|
||
|
||
@itemize @bullet
|
||
@item @code{ecb-source-path-functions}
|
||
@end itemize
|
||
|
||
Look at the documentation of these variables to get a description.
|
||
|
||
@node List of hooks, tree-buffer, List of variables, Elisp programming
|
||
@section Available hooks of ECB
|
||
|
||
The following hooks are available:
|
||
|
||
@cindex Hooks
|
||
@itemize @bullet
|
||
@item @code{ecb-activate-before-new-frame-created-hook}
|
||
@item @code{ecb-activate-before-layout-draw-hook}
|
||
@item @code{ecb-activate-hook}
|
||
@item @code{ecb-after-directory-change-hook}
|
||
@item @code{ecb-before-activate-hook}
|
||
@item @code{ecb-before-deactivate-hook}
|
||
@item @code{ecb-common-tree-buffer-after-create-hook}
|
||
@item @code{ecb-basic-buffer-sync-hook}
|
||
@item @code{ecb-analyse-buffer-sync-hook}
|
||
@item @code{ecb-symboldef-buffer-sync-hook}
|
||
@item @code{ecb-speedbar-buffer-sync-hook}
|
||
@item @code{ecb-eshell-buffer-sync-hook}
|
||
@item @code{ecb-deactivate-hook}
|
||
@item @code{ecb-directories-buffer-after-create-hook}
|
||
@item @code{ecb-hide-ecb-windows-after-hook}
|
||
@item @code{ecb-hide-ecb-windows-before-hook}
|
||
@item @code{ecb-history-buffer-after-create-hook}
|
||
@item @code{ecb-methods-buffer-after-create-hook}
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item @code{ecb-show-ecb-windows-after-hook}
|
||
@item @code{ecb-show-ecb-windows-before-hook}
|
||
@item @code{ecb-sources-buffer-after-create-hook}
|
||
@end itemize
|
||
|
||
Look at the documentation of these hooks to get a detailed description.
|
||
|
||
@node tree-buffer, Adviced functions, List of hooks, Elisp programming
|
||
@section The library tree-buffer.el
|
||
|
||
The library tree-buffer.el is an ECB-independent library written
|
||
completely in emacs lisp and can be used also by other applications
|
||
than ECB. But the main purpose of tree-buffer.el is to offer a small
|
||
but powerful API to create new tree-buffers for ECB, add new
|
||
tree-nodes to a tree-buffer and thus use such a tree-buffer to display
|
||
arbitrary information structured by a tree.
|
||
|
||
This chapter is for emacs-lisp-programmers and describes how to create
|
||
a new tree-buffer, how to add new tree-nodes to a tree-buffer
|
||
(includes removing and updating already existing tree-nodes) and how
|
||
to use the offered tree-buffer- and tree-node-APIs.
|
||
|
||
@menu
|
||
* 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
|
||
@end menu
|
||
|
||
@node Introduction, A new tree-buffer, tree-buffer, tree-buffer
|
||
@subsection General description of tree-buffers
|
||
|
||
This subchapter is a general introduction in the main concepts of a
|
||
tree-buffer.
|
||
|
||
@subsubsection What is a tree-buffer?
|
||
|
||
A @dfn{tree-buffer} is meant to display certain informations (e.g. a
|
||
directory-tree) in a tree-structure consisting of @dfn{tree-nodes}.
|
||
Every line in a tree-buffer displays exactly one tree-node. Each node
|
||
has exactly one parent-node and can have any arbitrary number of
|
||
@dfn{children}-nodes. If a tree-node has no children then it is called
|
||
a @dfn{leaf}. A tree-node contains several ``slots'' wheras the most
|
||
important ones are the ``name'', ``displayed-name'' and ``data''. See
|
||
@ref{A new tree-node} for a detailed explanation.
|
||
|
||
The difference between a natural tree like a fir and a tree-buffer 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. Each
|
||
tree-buffer has exactly one root-node which is created automatically
|
||
by `tree-buffer-create'.
|
||
|
||
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
|
||
<root-node> ------------------------[root-node (invisible)]
|
||
[+] <parent-node-1> -------.
|
||
[-] <parent-node-2> -------|
|
||
[-] <expanded> --------|
|
||
<leaf-node-1> -----|
|
||
<leaf-node-2> -----|-----[tree-nodes]
|
||
<leaf-node-3> -----|
|
||
<leaf-node-4> -----|
|
||
[+] <collapsed> -------<2D>
|
||
|
|
||
`-----------------[expand/collapse-symbol]
|
||
@end group
|
||
@end example
|
||
|
||
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{Tree-buffer keybindings}.} (e.g. clicking onto
|
||
``leaf-node-1'' or ``parent-node-1'' in the example above). Which
|
||
action is triggered by which key depends on what you specify at
|
||
creation-time of the tree-buffer - see @ref{A new tree-buffer} for
|
||
details.
|
||
|
||
The creation-interface of a tree-buffer allows defining special
|
||
popup-menus when clicking with the right mouse-button (of course also
|
||
possible via keyboard, see @ref{Tree-buffer keybindings}) 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).
|
||
|
||
@subsubsection General recipe for a tree-buffer
|
||
|
||
The following sequence of tasks is the general recipe for a
|
||
tree-buffer beginning from creation and ending with the display.
|
||
|
||
@enumerate
|
||
@item Create the tree-buffer
|
||
Creating a new tree-buffer has to be done with
|
||
@code{tree-buffer-create} for non ECB-tree-buffers and with the macro
|
||
@code{defecb-tree-buffer-creator} when the tree-buffer should be used
|
||
as an ECB-tree-buffer, so it is an ECB-window. See @ref{A new
|
||
tree-buffer} for all details.
|
||
|
||
@item Add tree-nodes to the tree-buffer
|
||
Adding nodes to the new tree-buffer (means make the new tree-buffer
|
||
the current buffer and call @code{tree-node-new} for a new tree-node
|
||
(note that a root-node for this tree-buffer has been autom. created by
|
||
@code{tree-buffer-create}!). The first tree-node you add to a
|
||
tree-buffer must have always the root-node (avaliable via
|
||
@code{tree-buffer-get-root}) as parent-node. The next nodes can have
|
||
either one of the fromerly added nodes or the root-node too. All
|
||
tree-nodes haveing the root-node as parent will be displayed at the
|
||
toplevel of the tree-buffer. See @ref{A new tree-node} for all
|
||
details.
|
||
|
||
@item Display the tree-buffer with current nodes and state
|
||
When you are finished building up the tree-node-structure call
|
||
@code{tree-buffer-update} to display the current tree-structure (again
|
||
after making the tree-buffer the current-buffer). See @ref{Updating a
|
||
tree-buffer} for all details.
|
||
@end enumerate
|
||
|
||
@strong{IMPORTANT}: First a call of @code{tree-buffer-update} updates
|
||
the @strong{display} of a tree-buffer, means shows all the tree-nodes
|
||
in an emacs-buffer! Neither creating a tree-buffer nor adding
|
||
tree-nodes display anything; this just builds the internal
|
||
tree-structure.
|
||
|
||
@strong{IMPORTANT}: See @ref{Programming special windows} for details
|
||
about programming ECB-windows (special windows) regardless if they
|
||
were build as tree or not. There you can find a.o. how to
|
||
automatically synchronizing a special window with the current
|
||
edit-buffer.
|
||
|
||
@node A new tree-buffer, A new tree-node, Introduction, tree-buffer
|
||
@subsection How to create a new tree-buffer
|
||
|
||
The creator-function for a new tree-buffer depends on the fact if the
|
||
new tree-buffer should be used as an ECB-window or not. For a new
|
||
ECB-window the macro @code{defecb-tree-buffer-creator} has to be
|
||
used, otherwise the function @code{tree-buffer-create}. In the end
|
||
both methods use @code{tree-buffer-create} because the BODY-argument
|
||
of @code{defecb-tree-buffer-creator} must contain a call to this
|
||
function!.
|
||
|
||
This section describes all arguments of @code{tree-buffer-create}.
|
||
|
||
Except the first argument @var{NAME} all arguments are key-arguments
|
||
of the form :arg-name arg-value, so for example a call looks like
|
||
|
||
@example
|
||
(tree-buffer-create <buffer-name> :frame <frame-object> ...).
|
||
@end example
|
||
|
||
These key-arguments (all except the first argument @code{NAME}) can be
|
||
arranged in any arbitrary order but all of them are not-optional! The
|
||
key-arg-name is always a : followed by the lowercase version of the
|
||
mentioned argument below (e.g. @code{FRAME} --> :frame,
|
||
@code{MOUSE-ACTION-TRIGGER} --> :mouse-action-trigger).
|
||
|
||
Here is a description of the arguments of @code{tree-buffer-create} -
|
||
also available as docstring for this function (via @kbd{C-h f}). The
|
||
description below contains also some examples for complex-arguments!
|
||
|
||
@table @code
|
||
|
||
@item @code{NAME}
|
||
Buffername of the new tree-buffer.
|
||
|
||
@item @var{FRAME}
|
||
Frame in which the tree-buffer is displayed and valid. All
|
||
key-bindings and interactive functions of the tree-buffer work only if
|
||
called in @var{FRAME} otherwise nothing is done!
|
||
|
||
@item @var{MOUSE-ACTION-TRIGGER}
|
||
When a mouse-action is triggered. Allowed values:
|
||
@code{button-release} and @code{button-press}.
|
||
|
||
@item @var{IS-CLICK-VALID-FN}
|
||
@code{tree-buffer-create} rebinds @kbd{mouse-1}, @kbd{mouse-2},
|
||
@kbd{RET} (and @kbd{TAB}) and also in combination with shift and
|
||
control (not with @kbd{TAB}). @var{IS-CLICK-VALID-FN} is called first
|
||
if a node or an expand-symbol is clicked. This function is called with
|
||
five arguments:
|
||
|
||
@itemize @minus
|
||
@item mouse-button:
|
||
The clicked mouse-button or RET or TAB (0 = RET or TAB, 1 = mouse-1, 2
|
||
= mouse 2)
|
||
@item shift-pressed:
|
||
Non nil if the SHIFT-key was pressed during mouse-click or RET.
|
||
@item control-pressed:
|
||
Non nil if the CONTROL-key was pressed during mouse-click or RET.
|
||
@item meta-pressed:
|
||
Non nil if the META-key was pressed during mouse-click or RET.
|
||
@item tree-buffer-name:
|
||
The buffer-name of the tree-buffer where the node has been clicked.
|
||
@end itemize
|
||
|
||
The function must return not nil iff exactly this click/hit is
|
||
accepted. If the function returns nil then really nothing is done by
|
||
the tree-buffer after this click/hit!
|
||
|
||
Here is an example (call @kbd{C-h f} to see what it does) for this
|
||
callback-function:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-interpret-mouse-click (mouse-button
|
||
shift-pressed
|
||
control-pressed
|
||
meta-pressed
|
||
tree-buffer-name)
|
||
(if (eq mouse-button 0)
|
||
(list (if control-pressed 2 1) shift-pressed meta-pressed
|
||
'keyboard)
|
||
(if (and (not (eq mouse-button 1)) (not (eq mouse-button 2)))
|
||
nil
|
||
(case ecb-primary-secondary-mouse-buttons
|
||
(mouse-1--mouse-2
|
||
(if control-pressed
|
||
nil
|
||
(list mouse-button shift-pressed meta-pressed 'mouse)))
|
||
(mouse-1--C-mouse-1
|
||
(if (not (eq mouse-button 1))
|
||
nil
|
||
(list (if control-pressed 2 1) shift-pressed meta-pressed
|
||
'mouse)))
|
||
(mouse-2--C-mouse-2
|
||
(if (not (eq mouse-button 2))
|
||
nil
|
||
(list (if control-pressed 2 1) shift-pressed meta-pressed
|
||
'mouse)))
|
||
(otherwise nil)))))
|
||
@end group
|
||
@end example
|
||
|
||
This example would be passed as parameter as follows:
|
||
|
||
@example
|
||
(tree-buffer-create "myname"
|
||
:is-click-valid-fn 'ecb-interpret-mouse-click
|
||
...)
|
||
@end example
|
||
|
||
@item @var{NODE-SELECTED-FN}
|
||
Function to call if a node has been selected. This function
|
||
is called with the following parameters:
|
||
|
||
@itemize @minus
|
||
@item node: The selected node
|
||
@item mouse-button (0 = RET, 1 = mouse-1, 2 = mouse 2)
|
||
@item shift-pressed
|
||
@item control-pressed
|
||
@item meta-pressed
|
||
@item tree-buffer-name
|
||
@end itemize
|
||
|
||
For the last four arguments see the description above. This function
|
||
has to ensure that the expandable- and expanded-state of the selected
|
||
node is correct after returning.
|
||
|
||
Here is an example (call @kbd{C-h f} to see what it does) for this
|
||
callback-function:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-tree-buffer-node-select-callback (node
|
||
mouse-button
|
||
shift-pressed
|
||
control-pressed
|
||
meta-pressed
|
||
tree-buffer-name)
|
||
(let* ((ecb-button-list (ecb-interpret-mouse-click mouse-button
|
||
shift-pressed
|
||
control-pressed
|
||
meta-pressed
|
||
tree-buffer-name))
|
||
(ecb-button (nth 0 ecb-button-list))
|
||
(shift-mode (nth 1 ecb-button-list))
|
||
(meta-mode (nth 2 ecb-button-list))
|
||
(keyboard-p (equal (nth 3 ecb-button-list) 'keyboard))
|
||
(maximized-p (ecb-buffer-is-maximized-p tree-buffer-name)))
|
||
;; now we dispatch to the right action
|
||
(when ecb-button-list
|
||
(cond ((ecb-string= tree-buffer-name ecb-directories-buffer-name)
|
||
(ecb-directory-clicked node ecb-button nil shift-mode
|
||
meta-mode))
|
||
((ecb-string= tree-buffer-name ecb-sources-buffer-name)
|
||
(ecb-source-clicked node ecb-button nil shift-mode
|
||
meta-mode))
|
||
((ecb-string= tree-buffer-name ecb-history-buffer-name)
|
||
(ecb-history-clicked node ecb-button nil shift-mode
|
||
meta-mode))
|
||
((ecb-string= tree-buffer-name ecb-methods-buffer-name)
|
||
(ecb-method-clicked node ecb-button nil shift-mode
|
||
meta-mode))
|
||
((ecb-string= tree-buffer-name ecb-analyse-buffer-name)
|
||
(ecb-analyse-node-clicked node ecb-button nil shift-mode
|
||
meta-mode))
|
||
(t nil)))))
|
||
@end group
|
||
@end example
|
||
|
||
This example would be passed as parameter as follows:
|
||
|
||
@example
|
||
(tree-buffer-create "myname"
|
||
:node-selected-fn 'ecb-tree-buffer-node-select-callback
|
||
...)
|
||
@end example
|
||
|
||
@strong{IMPORTANT}: This callback must not modify the slot
|
||
@var{EXPANDED} of the passed node because this is done automatically
|
||
by the tree-buffer-library!
|
||
|
||
@item @var{NODE-EXPANDED-FN}
|
||
Function to call if a node is expandable, point stays onto the
|
||
expand-symbol and node is not already expanded. This function is
|
||
called with the following parameters:
|
||
|
||
@itemize @minus
|
||
@item node: The selected node
|
||
@item mouse-button (0 = TAB, 1 = mouse-1, 2 = mouse 2)
|
||
@item shift-pressed
|
||
@item control-pressed
|
||
@item meta-pressed
|
||
@item tree-buffer-name
|
||
@end itemize
|
||
|
||
This function should add all children nodes to this node if not
|
||
already done (if possible). This function has to ensure that the
|
||
expandable- and expanded state of the selected node is correct after
|
||
returning!
|
||
|
||
@strong{IMPORTANT}: This callback must not modify the slot
|
||
@var{EXPANDED} of the passed node because this is done automatically
|
||
by the tree-buffer-library!
|
||
|
||
@item @var{NODE-COLLAPSED-FN}
|
||
Function to call if a node is expandable, point stays onto the
|
||
expand-symbol and node is already expanded. This function is called
|
||
with the following parameters:
|
||
|
||
@itemize @minus
|
||
@item node: The selected node
|
||
@item mouse-button (0 = TAB, 1 = mouse-1, 2 = mouse 2)
|
||
@item shift-pressed
|
||
@item control-pressed
|
||
@item meta-pressed
|
||
@item tree-buffer-name
|
||
@end itemize
|
||
|
||
This function is only a callback to inform the owner/user of this
|
||
tree-buffer that this node has been collapsed. This function must not
|
||
modify the expandable- or expanded state of the selected node!
|
||
|
||
Often a sensefull value for this parameter is the function
|
||
@code{ignore}.
|
||
|
||
@strong{IMPORTANT}: This callback must not modify the slot
|
||
@var{EXPANDED} of the passed node because this is done automatically
|
||
by the tree-buffer-library!
|
||
|
||
@item @var{NODE-MOUSE-OVER-FN}
|
||
Function to call when the mouse is moved over a node. This function is
|
||
called with three arguments: NODE, WINDOW, NO-PRINT, each of them
|
||
related to the current tree-buffer. If NO-PRINT is nil then the
|
||
function must print the text itself in any manner. This function must
|
||
always return the text which either is printed by the function itself
|
||
or by the caller (if NO-PRINT is not nil). The current buffer for this
|
||
function is the tree-buffer itself. With XEmacs this function is only
|
||
called if the tree-buffer track-mouse mechanism is activated (see the
|
||
function @code{tree-buffer-activate-follow-mouse}). With GNU Emacs >=
|
||
21 this function is called by the @code{help-echo} property added to
|
||
each node.
|
||
|
||
Here is an example (call @kbd{C-h f} to see what it does) for this
|
||
callback-function:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-mouse-over-analyse-node (node &optional window no-message
|
||
click-force)
|
||
(let ((str (when (or click-force
|
||
(ecb-show-minibuffer-info
|
||
node window
|
||
(car ecb-analyse-show-node-info)))
|
||
(if (equal (cdr ecb-analyse-show-node-info)
|
||
'full-info)
|
||
(ecb-analyse-gen-tag-info
|
||
(car (tree-node->data node)))
|
||
(tree-node->name node)))))
|
||
(prog1 str
|
||
(unless no-message
|
||
(ecb-nolog-message str)))))
|
||
@end group
|
||
@end example
|
||
|
||
@item @var{MOUSE-HIGHLIGHT-FN}
|
||
If nil then in this tree-buffer no node is highlighted when the mouse
|
||
moves over it. If t then each node is highlighted when the mouse moves
|
||
over it. If a function then it is called with the node as argument and
|
||
if it returns not nil then the node will be highlighted when the mouse
|
||
moves over it - otherwise no highlighting takes place.
|
||
|
||
@item @var{NODE-DATA-EQUAL-FN}
|
||
Function used by the tree-buffer to test if the data of two tree-nodes
|
||
are equal. The function is called with two args: The DATA-slots of the
|
||
two tree-nodes (see @ref{A new tree-node} for details about the
|
||
data-slots).
|
||
|
||
Here is an example (call @kbd{C-h f} to see what it does) for this
|
||
callback-function:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-analyse-compare-node-data (left right)
|
||
"Return not nil when LEFT and RIGHT are identical node-datas."
|
||
(and (equal (nth 2 left) (nth 2 right))
|
||
(ecb-compare-methods-buffer-node-data (car left)
|
||
(car right))))
|
||
@end group
|
||
@end example
|
||
|
||
Often a suitable value for this parameter is @code{equal}.
|
||
|
||
@item @var{MAYBE-EMPTY-NODE-TYPES}
|
||
Nil or a list of node-types (a node-type is an integer which must be
|
||
set with @code{tree-node-new}). Nodes with one of these types are
|
||
treated as empty if they are not expandable (i.e. they have no
|
||
children) and will be displayed with the empty-symbol ([x]); for other
|
||
nodes see next argument.
|
||
|
||
@item @var{LEAF-NODE-TYPES}
|
||
Nil or a list of node-types (see above). Nodes with one of these types
|
||
are treated as leafs and will be displayed with the leaf-symbol (*).
|
||
|
||
Summary for @var{MAYBE-EMPTY-NODE-TYPES} and @var{LEAF-NODE-TYPES}:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Expandable nodes will always be displayed either with the open- or
|
||
with the close-symbol.
|
||
|
||
@item
|
||
Not-expandable nodes with a node-type contained in
|
||
@var{MAYBE-EMPTY-NODE-TYPES} will be displayed with the empty-symbol.
|
||
|
||
@item
|
||
Not-expandable nodes with a node-type contained in
|
||
@var{LEAF-NODE-TYPES} will be displayed with the leaf-symbol.
|
||
|
||
@item
|
||
All other nodes will be displayed with no symbol just with correct
|
||
indentation.
|
||
@end itemize
|
||
|
||
@item @var{MENU-CREATOR}
|
||
Nil or function which has to return nil or a list of conses, each cons
|
||
for a known node-type of this tree-buffer (the node-type of a node is
|
||
an integer). Example: ((0 . menu-for-type-0) (1 . menu-for-type-1)).
|
||
The cdr of a cons must be a menu in the same format
|
||
@code{tree-buffer-create-menu} expects as argument - see the
|
||
documentation of this function for details. This function gets two
|
||
arguments: The name of the tree-buffer and the node for which a
|
||
popup-menu should be opened.
|
||
|
||
Here is an example for such a menu-creator-callback:
|
||
|
||
@example
|
||
@group
|
||
(defconst ecb-analyse-nodedata-tag-with-pos 0)
|
||
(defconst ecb-analyse-nodedata-tag-without-pos 1)
|
||
(defconst ecb-analyse-nodedata-no-tag 2)
|
||
|
||
(defconst ecb-analyse-nodetype-bucket 0)
|
||
(defconst ecb-analyse-nodetype-context 1)
|
||
(defconst ecb-analyse-nodetype-arguments 2)
|
||
(defconst ecb-analyse-nodetype-completions 3)
|
||
(defconst ecb-analyse-nodetype-localvars 4)
|
||
(defconst ecb-analyse-nodetype-prefix 5)
|
||
(defconst ecb-analyse-nodetype-assignee 6)
|
||
(defconst ecb-analyse-nodetype-function 7)
|
||
(defconst ecb-analyse-nodetype-function-arg 8)
|
||
|
||
(defun ecb-analyse-create-menu (node)
|
||
"Return a popup-menu suitable for NODE."
|
||
(let* ((data (tree-node->data node))
|
||
(tag-p (not (equal (nth 1 data) ecb-analyse-nodedata-no-tag)))
|
||
(tag-with-pos-p (equal (nth 1 data)
|
||
ecb-analyse-nodedata-tag-with-pos))
|
||
(nodetype (nth 2 data)))
|
||
(delq nil (list (if (equal nodetype ecb-analyse-nodetype-completions)
|
||
'(ecb-analyse-complete "Complete"))
|
||
(if tag-p
|
||
'(ecb-analyse-show-tag-info "Show tag info"))
|
||
(if tag-with-pos-p
|
||
'(ecb-analyse-jump-to-tag "Jump to tag"))))))
|
||
|
||
(defun ecb-analyse-menu-creator (tree-buffer-name node)
|
||
"Creates the popup-menus for the analyse-buffer."
|
||
(let ((nodetype (tree-node->type node)))
|
||
(unless (equal nodetype ecb-analyse-nodetype-bucket)
|
||
(mapcar (function (lambda (type)
|
||
(cons type (ecb-analyse-create-menu node))))
|
||
`(,ecb-analyse-nodetype-context
|
||
,ecb-analyse-nodetype-arguments
|
||
,ecb-analyse-nodetype-completions
|
||
,ecb-analyse-nodetype-localvars
|
||
,ecb-analyse-nodetype-prefix
|
||
,ecb-analyse-nodetype-assignee
|
||
,ecb-analyse-nodetype-function
|
||
,ecb-analyse-nodetype-function-arg)))))
|
||
@end group
|
||
@end example
|
||
|
||
This example would be passed as parameter as follows:
|
||
|
||
@example
|
||
(tree-buffer-create "myname"
|
||
:menu-creator 'ecb-analyse-menu-creator
|
||
...)
|
||
@end example
|
||
|
||
@item @var{MENU-TITLES}
|
||
Nil or a list conses, each cons for a node-type. See
|
||
@var{MENU-CREATOR}. The cdr of a cons must be either a string or a
|
||
function which will be called with current node under point and must
|
||
return a string which is displayed as the menu-title.
|
||
|
||
@item @var{MODELINE-MENU-CREATOR}
|
||
Nil or a function which has to return nil or a menu in the same format
|
||
@code{tree-buffer-create-menu} expects as argument - see the
|
||
documentation of this function for details. This function gets one
|
||
argument: The name of the tree-buffer. If the function returns a menu
|
||
then this menu will be displayed when the user clicks with
|
||
mouse-button 3 at the modeline of the tree-buffer. The menu-title will
|
||
be ``Tree-buffer modeline-menu''.
|
||
|
||
@item @var{sticky-parent-p}
|
||
If not nil then with GNU Emacs >= 21 the tree-buffer displays in its
|
||
header-line the unvisible parent-node if there is any. sticky-parent-fn is
|
||
used to get this parent node.
|
||
|
||
@item @var{sticky-indent-string}
|
||
String used for indendation of the sticky node in the header-line so it
|
||
matches the tree-display.
|
||
|
||
@item @var{sticky-parent-fn}
|
||
Function used to get that parent node which should be sticky. This function
|
||
gets as argument a node and should either return nil (if there is not suitable
|
||
parent node) or a node. This node will be displayed as sticky in the
|
||
header-line of the tree-buffer. If nil is returned and sticky-parent-p is not
|
||
nil then just the node under the header-line is displayed. If this argument is
|
||
nil and sticky-parent-p is not nil then always the next unvisible parent node
|
||
will be displayed in the header-line.
|
||
|
||
@item @var{TRUNC-LINES}
|
||
Should lines in this tree buffer be truncated (not nil).
|
||
|
||
@item @var{READ-ONLY}
|
||
Should the treebuffer be read-only (not nil).
|
||
|
||
@item @var{TREE-INDENT}
|
||
Spaces subnodes should be indented. Ignored if @var{TREE-STYLE} is
|
||
@code{image} (see below).
|
||
|
||
@item @var{INCR-SEARCH-P}
|
||
Should the incremental search be enabled in the tree-buffer. Three
|
||
choices: @code{prefix}, @code{substring}, @code{nil}. See the command
|
||
@code{tree-buffer-incremental-node-search}.
|
||
|
||
@item @var{INCR-SEARCH-ADDITIONAL-PATTERN}
|
||
Every search-pattern is prefixed with a regexp to jump over not
|
||
important stuff of a displayed node-name at incr. search.. This is per
|
||
default: beginning spaces and guide characters (|`-) and all
|
||
expand/collapse-buttons [+], [x], rsp. [-]!
|
||
|
||
If this argument is not nil then it must be a cons-cell where car is a
|
||
string which should be a regexp-pattern which is added to the
|
||
basic-prefix pattern (see above) and both of them prefix the
|
||
incr-search-pattern. The cdr is the number of subexpressions in this
|
||
additoonal pattern.
|
||
|
||
@item @var{ARROW-NAVIGATION}
|
||
If not nil then a smart navigation with arrow keys is offered:
|
||
|
||
@itemize @minus
|
||
@item Left-arrow:
|
||
If node is expanded then it will be collapsed otherwise point
|
||
jumps to the next "higher" node in the hierarchical tree (higher means
|
||
the next higher tree-level or - if no higher level available - the next
|
||
higher node on the same level).
|
||
|
||
@item Right-arrow:
|
||
If node is not expanded then it will be expanded.
|
||
|
||
Onto a not expandable node the horizontal arrow-keys go one character in the
|
||
senseful correct direction.
|
||
|
||
@item Up- and down-key:
|
||
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 @var{EXPAND-SYMBOL-BEFORE-P} is not nil) or of
|
||
the displayed node-name. Or with other words: The first
|
||
non-indentation and non-guide-line (see @var{TREE-STYLE}) character of
|
||
a node.
|
||
@end itemize
|
||
|
||
|
||
@item @var{HOR-SCROLL-STEP}
|
||
Number of columns a hor. scroll in the tree-buffer should scroll. If
|
||
not nil then @kbd{M-mouse-1} and @kbd{M-mouse-2} scroll left and right
|
||
and also @kbd{M-<left-arrow>} and @kbd{M-<right-arrow>}. Ignored with
|
||
XEmacs.
|
||
|
||
@item @var{DEFAULT-IMAGES-DIR}
|
||
Full path where the default images for the tree-buffer can be found.
|
||
It should contain an image for every name of
|
||
@code{tree-buffer-tree-image-names}.
|
||
|
||
@item @var{ADDITIONAL-IMAGES-DIR}
|
||
Additional image-dir which should be searched first for images needed
|
||
for current tree-buffer. If the image can not be found in this
|
||
directory then @var{DEFAULT-IMAGES-DIR} is searched. If the image can't even
|
||
found here the related ascii-symbol is used.
|
||
|
||
@item @var{IMAGE-FILE-PREFIX}
|
||
Common prefix for all image-files for this tree-buffer, e.g. ``ecb-''.
|
||
|
||
@item @var{TREE-STYLE}
|
||
There are three different styles available: Image-style (value
|
||
@code{image}): Very nice and modern because image-icons are used to display
|
||
the tree-buffer. For this style the arguments @var{TREE-INDENT} and
|
||
@var{EXPAND-SYMBOL-BEFORE-P} have no effect.
|
||
|
||
Ascii-style with guide-lines (value @code{ascii-guides}) and
|
||
ascii-style without guidelines (value @code{ascii-no-guides}. See
|
||
@ref{Tree-buffer styles} for details about the tree-styles.
|
||
|
||
Both ascii-styles are affected by the args @var{TREE-INDENT} and
|
||
@var{EXPAND-SYMBOL-BEFORE-P}.
|
||
|
||
@item @var{ASCII-GUIDE-FACE}
|
||
If @var{TREE-STYLE} is @code{ascii-guides} then this defines the face
|
||
the guides should be displayed with.
|
||
|
||
@item @var{TYPE-FACER}:
|
||
Nil or a list of one or more conses, each cons for a node-type (a
|
||
node-type is an integer which must be set with @code{tree-node-new}).
|
||
The cdr of a cons can be:
|
||
|
||
@itemize @minus
|
||
@item a face-symbol
|
||
|
||
@item a function-symbol which gets two arguments (see
|
||
@code{tree-buffer-insert-text}). This function can do anything, but
|
||
normally it should face a tree-node.
|
||
|
||
@item the symbol t. Then the tree-buffer assumes that the node-text is
|
||
already faced and therefore it does not face the node, means it does
|
||
nothing then inserting the node-text, if the tree-buffer is updated.
|
||
@end itemize
|
||
|
||
@item @var{EXPAND-SYMBOL-BEFORE-P}
|
||
If not nil then the expand-symbol is displayed before the node-text.
|
||
Ignored when @var{TREE-STYLE} is @code{image} and Emacs can display
|
||
images.
|
||
|
||
@item @var{HIGHLIGHT-NODE-FACE}
|
||
Face used for highlighting current selected node in this
|
||
tree-buffer.
|
||
|
||
@item @var{GENERAL-FACE}
|
||
General face in which the whole tree-buffer should be displayed.
|
||
|
||
@item @var{AFTER-CREATE-HOOK}:
|
||
A function or a list of functions (with no arguments) called directly
|
||
after creating the tree-buffer and defining it's local keymap. For
|
||
example such a function can add additional key-bindings for this
|
||
tree-buffer local keymap (use @code{local-set-key} for this).
|
||
|
||
Here is an example for such a hook:
|
||
|
||
@example
|
||
@group
|
||
(defun ecb-common-after-tree-buffer-create-actions ()
|
||
"Things which should be performed after creating a tree-buffer.
|
||
The tree-buffer is the current buffer."
|
||
(local-set-key (kbd "C-t")
|
||
'ecb-toggle-do-not-leave-window-after-select)
|
||
(if ecb-running-xemacs
|
||
(define-key modeline-map
|
||
'(button2up)
|
||
'ecb-toggle-maximize-ecb-window-with-mouse)
|
||
(local-set-key [mode-line mouse-2]
|
||
'ecb-toggle-maximize-ecb-window-with-mouse)))
|
||
@end group
|
||
@end example
|
||
|
||
@item @var{AFTER-UPDATE-HOOK}:
|
||
A function or a list of functions (with no arguments) called each time
|
||
after the tree-buffer has been updated via @code{tree-buffer-update}.
|
||
|
||
@end table
|
||
|
||
Here is an example how to create a tree-buffer (if you want a
|
||
tree-buffer not for ECB then just strip off the
|
||
@code{defecb-tree-buffer-creator} and just call
|
||
@code{tree-buffer-create}):
|
||
|
||
@example
|
||
@group
|
||
(defecb-tree-buffer-creator ecb-create-analyse-tree-buffer
|
||
ecb-analyse-buffer-name
|
||
"Create the tree-buffer for analyse-display."
|
||
(tree-buffer-create
|
||
ecb-analyse-buffer-name
|
||
:frame ecb-frame
|
||
:mouse-action-trigger ecb-tree-mouse-action-trigger
|
||
:is-click-valid-fn 'ecb-interpret-mouse-click
|
||
:node-selected-fn 'ecb-tree-buffer-node-select-callback
|
||
:node-expanded-fn 'ecb-tree-buffer-node-expand-callback
|
||
:node-collapsed-fn 'ecb-tree-buffer-node-collapsed-callback
|
||
:node-mouse-over-fn 'ecb-mouse-over-analyse-node
|
||
:mouse-highlight-fn 'ecb-analyse-node-mouse-highlighted-p
|
||
:node-data-equal-fn 'ecb-analyse-compare-node-data
|
||
:maybe-empty-node-types nil
|
||
:leaf-node-types nil
|
||
:menu-creator 'ecb-analyse-menu-creator
|
||
:menu-titles (ecb-analyse-gen-menu-title-creator)
|
||
:modeline-menu-creator 'ecb-common-tree-buffer-modeline-menu-creator
|
||
:trunc-lines (ecb-member-of-symbol/value-list
|
||
ecb-analyse-buffer-name
|
||
ecb-tree-truncate-lines)
|
||
:read-only t
|
||
:tree-indent ecb-tree-indent
|
||
:incr-search-p t
|
||
:incr-search-additional-pattern nil
|
||
:arrow-navigation ecb-tree-navigation-by-arrow
|
||
:hor-scroll-step ecb-tree-easy-hor-scroll
|
||
:default-images-dir (car ecb-tree-image-icons-directories)
|
||
:additional-images-dir (ecb-member-of-symbol/value-list
|
||
ecb-analyse-buffer-name
|
||
(cdr ecb-tree-image-icons-directories)
|
||
'car 'cdr)
|
||
:image-file-prefix "ecb-"
|
||
:tree-style ecb-tree-buffer-style
|
||
:ascii-guide-face ecb-tree-guide-line-face
|
||
:type-facer nil
|
||
:expand-symbol-before-p ecb-tree-expand-symbol-before
|
||
:highlight-node-face ecb-analyse-face
|
||
:general-face ecb-analyse-general-face
|
||
:after-create-hook (append
|
||
(list (lambda ()
|
||
(ecb-common-after-create-actions)))
|
||
ecb-common-tree-buffer-after-create-hook
|
||
ecb-analyse-buffer-after-create-hook)
|
||
:after-update-hook nil))
|
||
@end group
|
||
@end example
|
||
|
||
@node A new tree-node, Updating a tree-buffer, A new tree-buffer, tree-buffer
|
||
@subsection How to create a new tree-node
|
||
|
||
When a new tree-buffer has been created, then the most senseful
|
||
programming-task is adding some tree-nodes to it.
|
||
|
||
@subsubsection Content of a tree-node
|
||
|
||
A tree-node is an object which stores in special @dfn{slots} several
|
||
data necessary to link the node with other nodes, to display the node
|
||
and to hold some associated node-data (e.g. a tag created by the
|
||
semantic-library).
|
||
|
||
A tree-node can have the following slots:
|
||
|
||
@table @code
|
||
@item @var{NAME}
|
||
The name of the node. Regardless how the node is displayed; see
|
||
@var{SHRINK-NAME} and @var{DISPLAYED-NAME}.
|
||
|
||
@item @var{TYPE}
|
||
The type of the node; must currently be an interger! The type is used
|
||
to classify the nodes, so for example all nodes of a certain type can
|
||
display the same popup-menu - see @code{tree-buffer-create} or @ref{A
|
||
new tree-buffer} which parts of a tree-buffer are distinguished by
|
||
node-types.
|
||
|
||
@item @var{DATA}
|
||
The data of the node; This can be any arbitrary emacs-lisp-object.
|
||
This slots holds that data asscociated with the node and represented
|
||
by the node in the tree-buffer. Example: Assume a tree-buffer
|
||
displaying a directory-tree where each node just displays as its name
|
||
the name of (sub)directories, but not the full path. The full path is
|
||
stored in the @var{DATA}-slot of a node so when clicking onto this
|
||
node the asscociated directory can be open for example in a
|
||
dired-buffer.
|
||
|
||
@item @var{EXPANDABLE}
|
||
If not nil then the node is expandable means it has children.
|
||
|
||
@item @var{EXPANDED}
|
||
If not nil then the node is currently expanded, means its
|
||
children are visible in the tree-buffers as subnodes of the node.
|
||
|
||
@item @var{PARENT}
|
||
The parent tree-node. This is the link to the father (rsp. mother ;-)
|
||
of the node. It must be a object of type tree-node!
|
||
|
||
@item @var{CHILDREN}
|
||
List of children tree-nodes. They must be all objects of type
|
||
tree-node!
|
||
|
||
@item @var{SHRINK-NAME}
|
||
Decides if the @var{NAME} can be shortened when displayed in a narrow
|
||
tree buffer window. The following values are valid:
|
||
|
||
@itemize @minus
|
||
@item @code{beginning}:
|
||
The @var{NAME} is truncated at the beginning so the end is always
|
||
visible.
|
||
|
||
@item @code{end}:
|
||
The @var{NAME} is truncated at the end. If the tree-node is EXPANDABLE
|
||
the name is truncated so that the expand symbol is visible.
|
||
|
||
@item @code{nil}:
|
||
The @var{NAME} is never truncated. In this case @var{DISPLAYED-NAME}
|
||
is equal to @var{NAME}.
|
||
@end itemize
|
||
|
||
@item @var{INDENTSTR}
|
||
Containes the full indentation-string for the node. So a single node
|
||
can easily be redrawn.
|
||
|
||
@item @var{DISPLAYED-NAME}
|
||
Contains the current displayed name of the node. The
|
||
displayed name can be different from the @var{NAME} according to the value of
|
||
@var{SHRINK-NAME}.
|
||
|
||
@end table
|
||
|
||
@subsubsection Creating a new tree-node and adding it to the tree
|
||
|
||
A new tree-node has to be created with the function
|
||
@code{tree-node-new}. This ``constructor'' accepts the following
|
||
parameter: @var{NAME}, @var{TYPE}, @var{DATA}, @var{NOT-EXPANDABLE},
|
||
@var{PARENT} and @var{SHRINK-NAME}.
|
||
|
||
For all parameters except @var{NOT-EXPANDABLE} the description is
|
||
available in the slot-description in the section above. If
|
||
@var{NOT-EXPANDABLE} is set to not nil then the slot @var{EXPANDABLE}
|
||
will be set to @code{nil}; otherwise to @code{t}.
|
||
|
||
@code{tree-node-new} returns a new tree-node.
|
||
|
||
The new node can either being added implicitely to the tree via the
|
||
optional @var{PARENT}-parameter when calling @code{tree-buffer-new} or
|
||
explicitely by first creating the new node without setting the
|
||
parent-node but later setting the parent-node via the according
|
||
accessor (see next section below). Children should only being added
|
||
with @code{tree-node-add-children} - see next section.
|
||
|
||
@subsubsection Accessing the slots of a tree-node
|
||
|
||
The section above shows which slots a tree-node have.
|
||
|
||
A slot with name XXX is getable with the following piece of code:
|
||
|
||
@lisp
|
||
(tree-node->xxx <a tree node>)
|
||
@end lisp
|
||
|
||
Here is an example how to get the value of the slot @var{DATA}:
|
||
|
||
@example
|
||
(tree-node->data <a tree node>)
|
||
@end example
|
||
|
||
A slot with name XXX is setable with the following piece of code:
|
||
|
||
@lisp
|
||
(setf (tree-node->xxx <a tree node>) <new value>)
|
||
@end lisp
|
||
|
||
Again an example with slot @var{DATA} which sets this slot to the
|
||
string ``~/a_subdir_of_HOME'':
|
||
|
||
@example
|
||
(setf (tree-node->data <a tree node>) "~/a_subdir_of_HOME")
|
||
@end example
|
||
|
||
@strong{IMPORTANT}: Adding new children to a node should always being
|
||
done with the function @code{tree-node-add-children} because this
|
||
functions encapsulates all the necessary stuff needed to add children
|
||
to a node (mainly adding the children itself and setting the node itself as
|
||
parent for every children).
|
||
|
||
See @ref{The tree-buffer-API} for the rest of the API available for
|
||
tree-nodes.
|
||
|
||
@node Updating a tree-buffer, Tree-buffer keybindings, A new tree-node, tree-buffer
|
||
@subsection How to update a tree-buffer-display after changes
|
||
|
||
When finished with adding tree-nodes to the tree-structure you mostly
|
||
want to display the current tree and its state in the buffer/window so
|
||
a user can see the current tree and can use it.
|
||
|
||
Threre are two ways to update a tree-buffer for display:
|
||
|
||
@enumerate
|
||
@item Updating the whole tree-buffer:
|
||
|
||
This is the most used way to update the tree-buffer display. It's
|
||
quite simple, just call @code{tree-buffer-update}. In most cases you
|
||
want to call it without arguments.
|
||
|
||
If you want to display a certain expanded node and as much as possible
|
||
subnodes of this node then pass this node-object as first argument to
|
||
@code{tree-buffer-update}.
|
||
|
||
If you do not have the need to display a completely new tree-structure
|
||
but you want only to display a previously cached display-state then
|
||
pass this cached-state as second argument to
|
||
@code{tree-buffer-update}. See the documentation of this function and
|
||
also @ref{Tree-buffer How to} for a detailled description how to do
|
||
this.
|
||
|
||
@item Updating only a single node of the tree-buffer:
|
||
|
||
Sometimes it can be useful to update only exactly one special node,
|
||
e.g. when your application codes some node-state in the displayed
|
||
node-name (e.g. ECB displays the version-control state of a file as
|
||
part of the related node-name) then it is necessary to update only
|
||
this node if the state has changed.
|
||
|
||
This can be done with the function @code{tree-buffer-update-node}. For
|
||
this function the mentioning in this section can be misleading because
|
||
this function can not only update the node-display but in general the
|
||
slots @var{NAME}, @var{SHRINK-NAME}, @var{TYPE}, @var{DATA} and
|
||
@var{EXPANDABLE}. Do @kbd{C-h f} to see the documentation of this
|
||
function for all details!
|
||
|
||
@end enumerate
|
||
|
||
@node Tree-buffer keybindings, The tree-buffer-API, Updating a tree-buffer, tree-buffer
|
||
@subsection Default and customizable keybindings of a tree-buffer
|
||
|
||
When creating a tree-buffer with @code{tree-buffer-create} the
|
||
following keys will automatically being bound:
|
||
|
||
@table @asis
|
||
|
||
@item @kbd{delete}
|
||
@itemx @kbd{backspace}
|
||
@itemx @kbd{home}
|
||
@itemx @kbd{end}
|
||
@itemx @kbd{a} (and each other key bound to @code{self-insert-command})
|
||
All of these keys are bound to the command
|
||
@code{tree-buffer-incremental-node-search} if the argument
|
||
@var{INCR-SEARCH-P} of @code{tree-buffer-create} was set to not nil.
|
||
See the documentation of @code{tree-buffer-incremental-node-search}
|
||
for all details.
|
||
|
||
@item @kbd{RET}
|
||
@itemx @kbd{C-RET}
|
||
@itemx @kbd{S-RET}
|
||
@itemx @kbd{M-RET}
|
||
@itemx @kbd{C-S-RET}
|
||
@itemx @kbd{mouse-1}
|
||
@itemx @kbd{C-mouse-1}
|
||
@itemx @kbd{S-mouse-1}
|
||
@itemx @kbd{M-mouse-1}
|
||
@itemx @kbd{mouse-2}
|
||
@itemx @kbd{C-mouse-2}
|
||
@itemx @kbd{S-mouse-2}
|
||
@itemx @kbd{M-mouse-2}
|
||
All these keys are bound to an action-dispatcher which works as
|
||
follows:
|
||
|
||
If the callback-function in slot @var{IS-CLICK-VALID-FN} of the
|
||
tree-buffer (@pxref{A new tree-buffer}) returns nil then nothing is
|
||
done.
|
||
|
||
If either @kbd{RET} has been hitted or point is as the node-name (i.e.
|
||
the user has clicked with the mouse-1/2 at the node-name) then the
|
||
callback-function in slot @var{NODE-SELECTED-FN} is called with the
|
||
needed arguments (@pxref{A new tree-buffer}).
|
||
|
||
If point is at the expand/collape-button then depending on the
|
||
expansion-state of the node either the callback in slot
|
||
@var{NODE-EXPANDED-FN} or @var{NODE-COLLAPSED-FN} is called (for
|
||
parameters see again @ref{A new tree-buffer}).
|
||
|
||
@strong{IMPORTANT}: None of these callbacks must modify the slot
|
||
@var{EXPANDED} of the passed node because this is done automatically
|
||
by the action-dispatcher!
|
||
|
||
At the end the dispatcher updates the tree-buffer-display with
|
||
optimized display of the clicked/selected node - see @ref{Updating a
|
||
tree-buffer}. This means @code{tree-buffer-update} is called with that
|
||
node as argument.
|
||
|
||
@item @kbd{TAB}
|
||
Depending on the expansion-state of the node either the callback in
|
||
slot @var{NODE-EXPANDED-FN} or @var{NODE-COLLAPSED-FN} is called (for
|
||
parameters see again @ref{A new tree-buffer}).
|
||
|
||
@strong{IMPORTANT}: None of these callbacks must modify the slot
|
||
@var{EXPANDED} of the passed node because this is done automatically
|
||
by the action-dispatcher!
|
||
|
||
At the end the the tree-buffer-display is updated with optimized
|
||
display of the clicked/selected node - see @ref{Updating a
|
||
tree-buffer}. This means @code{tree-buffer-update} is called with that
|
||
node as argument.
|
||
|
||
@item @kbd{mouse-3}
|
||
Activates the popup-menu for the current tree-buffer for current
|
||
node-type (if defined). See @ref{A new tree-buffer} at argument
|
||
@var{MENU-CREATOR} and @var{MENU-TITLES}. These callbacks are called
|
||
for getting the menu and the menu-title.
|
||
|
||
@item @kbd{modeline-mouse-3}
|
||
Activates the popup-menu for the modeline of the current tree-buffer
|
||
(if defined). See @ref{A new tree-buffer} at argument
|
||
@var{MODELINE-MENU-CREATOR}. This callback is called for getting the
|
||
modeline-menu.
|
||
|
||
@item @kbd{M-m}
|
||
This key is bound to the command
|
||
@code{tree-buffer-show-node-menu-keyboard}: Activates the popup-menu
|
||
of current tree-buffer for current node-type via keyboard. If called
|
||
with a prefix-arg then the library @file{tmm.el} is used for
|
||
displaying the popup-menu - ignored with XEmacs.
|
||
|
||
@item @kbd{<up>}
|
||
@itemx @kbd{<down>}
|
||
@itemx @kbd{<left>}
|
||
@itemx @kbd{<right>}
|
||
These keys are bound to the command @code{tree-buffer-arrow-pressed}
|
||
which implements the smart arrow-key-navigation described in @ref{A
|
||
new tree-buffer} at argument @var{ARROW-NAVIGATION}.
|
||
|
||
@end table
|
||
|
||
In addition to these automatically bound keys you can add further
|
||
keybindings to the local-keymap of the tree-buffer with the parameter
|
||
@var{AFTER-CREATE-HOOK} of @code{tree-buffer-create}. See @ref{A new
|
||
tree-buffer} for an example which binds @kbd{C-t} in this hook.
|
||
|
||
@node The tree-buffer-API, Do not with tree-buffer, Tree-buffer keybindings, tree-buffer
|
||
@subsection All functions available for tree-buffers and tree-nodes
|
||
|
||
This chapter lists the complete API available for tree-buffers and
|
||
tree-nodes.
|
||
|
||
@strong{IMPORTANT}: These are the only functions and macros of
|
||
tree-buffer.el you are allowed to use for programming with
|
||
tree-buffers and tree-nodes. If you use other - not here listed -
|
||
functions, macros or variables of tree-buffer.el then you run the risk
|
||
of unwanted side-effects or program-behaviors!
|
||
|
||
@subsubsection The API for a tree-buffer:
|
||
|
||
See the documentation of these functions (e.g. via @kbd{C-h f}) to get
|
||
the details how to use it.
|
||
|
||
@itemize
|
||
@item @code{tree-buffer-add-image-icon-maybe}
|
||
@item @code{tree-buffer-find-image}
|
||
@item @code{tree-buffer-create}@footnote{If the tree-buffer should be
|
||
used by ECB then you must use @code{defecb-tree-buffer-creator} - see
|
||
the documentation!}
|
||
@item @code{tree-buffer-defpopup-command}
|
||
@item @code{tree-buffer-destroy}@footnote{Not needed when
|
||
@code{defecb-tree-buffer-creator} has been used for creation.}
|
||
@item @code{tree-buffer-empty-p}
|
||
@item @code{tree-buffer-expand-node}
|
||
@item @code{tree-buffer-get-node-at-point}
|
||
@item @code{tree-buffer-node-data-equal-p}
|
||
@item @code{tree-buffer-recenter}
|
||
@item @code{tree-buffer-highlight-node-by-data/name}
|
||
@item @code{tree-buffer-find-displayed-node-by-data/name}
|
||
@item @code{tree-buffer-remove-highlight}
|
||
@item @code{tree-buffer-remove-node}
|
||
@item @code{tree-buffer-clear-tree}
|
||
@item @code{tree-buffer-displayed-nodes-copy}
|
||
@item @code{tree-buffer-search-displayed-node-list}
|
||
@item @code{tree-buffer-number-of-displayed-nodes}
|
||
@item @code{tree-buffer-get-data-store}
|
||
@item @code{tree-buffer-set-data-store}
|
||
@item @code{tree-buffer-get-root}
|
||
@item @code{tree-buffer-set-root}
|
||
@item @code{tree-buffer-update}
|
||
@item @code{tree-buffer-update-node}
|
||
@end itemize
|
||
|
||
@subsubsection The API for a tree-node
|
||
|
||
See the documentation of these functions (e.g. via @kbd{C-h f}) to get
|
||
the details how to use it.
|
||
|
||
@itemize
|
||
@item @code{tree-node-add-children}
|
||
@item @code{tree-node-linelength}
|
||
@item @code{tree-node-map-subtree}
|
||
@item @code{tree-node-new}
|
||
@item @code{tree-node-new-root}
|
||
@item @code{tree-node-remove-child}
|
||
@item @code{tree-node-remove-child-by-data/name}
|
||
@item @code{tree-node-find-child-by-data/name}
|
||
@item @code{tree-node-find-child-by-name}
|
||
@item @code{tree-node-search-subtree-by-data}
|
||
@item @code{tree-node-search-subtree-by-id}
|
||
@item @code{tree-node-sort-children}
|
||
@item @code{tree-node-toggle-expanded}
|
||
@end itemize
|
||
|
||
In addition to these functions the tree-node API contains all accessors
|
||
for a tree-node which are described in @ref{A new tree-node}.
|
||
|
||
@node Do not with tree-buffer, Tree-buffer How to, The tree-buffer-API, tree-buffer
|
||
@subsection Things which are strictly forbidden
|
||
|
||
Variable @code{tree-buffers}: Only for internal use! It contains all
|
||
tree-buffers of current Emacs-instance, means @strong{all}
|
||
tree-buffers of @strong{all} applications which uses currently
|
||
tree-buffers. Every application must store its own collection of
|
||
tree-buffers in an own variable! For example: ECB stores its
|
||
tree-buffer set in @code{ecb-tree-buffers}!
|
||
|
||
Variable @code{tree-buffer-displayed-nodes}: Only for internal use!
|
||
Contains all the current visible nodes of current tree-buffer in
|
||
top-to-bottom order. This variable is buffer-local in each
|
||
tree-buffer! Do not use it directly! When you want to cache the
|
||
current display, then see @ref{Tree-buffer How to} how to do this.
|
||
|
||
@strong{IMPORTANT}: An application may only use the API tree-buffer.el
|
||
provides but no internal variables - see @ref{The tree-buffer-API}!
|
||
|
||
@node Tree-buffer How to, ,Do not with tree-buffer, tree-buffer
|
||
@subsection How to deal with certain programming-requirements
|
||
|
||
This chapter describes in detail how to solve certain
|
||
programming-challenges with tree-buffers.
|
||
|
||
@subsubsection Caching the current tree-buffer display
|
||
|
||
Sometimes it can be useful or important to cache the current display
|
||
of a tree-buffer and display later exactly this cached display-state.
|
||
Here is how to do this:
|
||
|
||
@enumerate
|
||
@item Caching the display:
|
||
You have to do two tasks: First store the current internal structure
|
||
of the tree-buffer; you must do this with the function
|
||
@code{tree-buffer-displayed-nodes-copy}. Then store the
|
||
buffer-contents of that tree-buffer you want to cache; you can do this
|
||
for example with @code{buffer-substring}. For both tasks you must make
|
||
the tree-buffer the current-buffer.
|
||
|
||
@item Displaying a previous tree-buffer-cache:
|
||
Make the tree-buffer the current buffer, call
|
||
@code{tree-buffer-update} and pass as second argument @var{CONTENT}
|
||
the data you have stored in step 1. See the documentation of
|
||
@code{tree-buffer-update} for details.
|
||
|
||
Here is an example:
|
||
|
||
@example
|
||
@group
|
||
(tree-buffer-update
|
||
nil
|
||
(cons (nth 2 cache-elem) ;; the stored buffer-string
|
||
(nth 1 cache-elem) ;; the stored tree-structure
|
||
)))
|
||
@end group
|
||
@end example
|
||
@end enumerate
|
||
|
||
@node Adviced functions, The layout-engine, tree-buffer, Elisp programming
|
||
@section How to deal with the adviced functions
|
||
|
||
ECB needs a bunch of advices so ECB can work correctly. ECB has a
|
||
powerful advice-backbone which allows defining sets of adviced
|
||
functions whereas a set means, that all advices of a certain set are
|
||
always enabled or disabled together.
|
||
|
||
For this ECB contains four macros:
|
||
|
||
@itemize @minus
|
||
@item @code{defecb-advice-set}
|
||
@item @code{defecb-advice}
|
||
@item @code{ecb-with-original-adviced-function-set}
|
||
@item @code{ecb-with-ecb-advice} (for this one see below)
|
||
@end itemize
|
||
|
||
For a detailed explanation of each macro read the documentation with
|
||
@code{describe-function}!
|
||
|
||
An advice in ECB must not being defined by @code{defadvice} but only
|
||
with @code{defecb-advice} which in turn needs a previously defined
|
||
advice-set defined by @code{defecb-advice-set}.
|
||
|
||
So ECB has always full control of all advices. For example ECB
|
||
automatically disables all advices of all advice-sets at load-time of
|
||
ECB and also at deactivation time of ECB. So you can be sure that
|
||
after deactivating ECB all ecb-advices are deactivated/disabled too.
|
||
|
||
In addition to the four macros above ECB offers two further macros
|
||
for running code with disabled some ecb-advices:
|
||
|
||
@itemize @minus
|
||
@item @code{ecb-with-original-basic-functions}
|
||
@item @code{ecb-with-original-permanent-layout-functions}
|
||
@end itemize
|
||
|
||
The advice set @code{ecb-basic-adviced-functions} contains most of the
|
||
ecb-advices. See the contents of this variable to see which advices
|
||
are contained in this set. Use
|
||
@code{ecb-with-original-basic-functions} when you want evaluating
|
||
elisp-code with disabled basic-advices.
|
||
@code{ecb-with-original-basic-functions} is only a shortcut for
|
||
@code{ecb-with-original-adviced-function-set} called for the
|
||
@code{ecb-basic-adviced-functions}-set.
|
||
|
||
Same for @code{ecb-with-original-permanent-layout-functions} which is a
|
||
shortcut for the advice-set @code{ecb-permanent-adviced-layout-functions}.
|
||
|
||
Last but not least ECB contains an advice-set
|
||
@code{ecb-always-disabled-advices}. These advices are always disabled.
|
||
This advice-set can not be enabled by @code{ecb-enable-advices} but
|
||
such an advice has to be activated 'on demand' by the caller. Such an
|
||
advice must be used with the macro @code{ecb-with-ecb-advice} (see the
|
||
docstring) and is also enabled within the BODY of the macro-call.
|
||
|
||
ECB contains some more advice-sets but don't bother about it.
|
||
|
||
@strong{Please Note}: See the value of @code{ecb-adviced-function-sets} which
|
||
advice-sets are defined and see @code{ecb-adviced-functions} for an overview
|
||
for all adviced functions.
|
||
|
||
|
||
@node The layout-engine, , Adviced functions, Elisp programming
|
||
@section How to program new layouts and new special windows
|
||
|
||
There are two aspects concerning this topic:
|
||
|
||
@enumerate
|
||
@item
|
||
Programming a new layout which contains several special ECB-windows
|
||
like directories, sources, methods, history or other special windows
|
||
and arranging them in a new outline.
|
||
|
||
@item
|
||
Creating complete new special windows (e.g. a local-variable window
|
||
for a graphical debugger like JDEbug of JDEE), adding them to a layout
|
||
and synchronizing them with the current active edit-window.
|
||
@end enumerate
|
||
|
||
The former one covers merely the layout-programming aspect which is
|
||
explained in the first subsection of this chapter whereas the latter
|
||
one covers all aspects of creating new special windows and what is
|
||
necessary to synchronize it with the current active edit-window of
|
||
ECB. This is explained in the second subsection which will refers to
|
||
the first subsection.
|
||
|
||
@menu
|
||
* 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
|
||
@end menu
|
||
|
||
@node Programming a new layout, Programming special windows, The layout-engine, The layout-engine
|
||
@subsection How to program a new layout
|
||
|
||
If you just want creating a new layout with the standard ECB-windows
|
||
like directories, sources, methods, history and speedbar it's is
|
||
strongly recommended to define the new layout interactively with the
|
||
command @code{ecb-create-new-layout} (@pxref{Creating a new
|
||
ECB-layout}).
|
||
|
||
If you want creating a new layout and if this layout should contain
|
||
other special windows than the standard ECB-windows then it's still
|
||
recommended to define this layout interactively with
|
||
@code{ecb-create-new-layout} and using the option to give the created
|
||
windows user-defined types. For every user defined type you have then
|
||
just to program the necessary buffer-set function. For all the details
|
||
see @ref{Creating a new ECB-layout}.
|
||
|
||
But if you do not like the interactive way (because you are tough and
|
||
brave) but you want programming the new layout with Elisp then use the
|
||
macro @code{ecb-layout-define} (the following definition has stripped
|
||
the prefix ``ecb-'' for better indexing this manual):
|
||
|
||
@defmac layout-define name type doc &rest create-code
|
||
Creates a new ECB-layout with name @var{NAME}. @var{TYPE} is the type
|
||
of the new layout and is literal, i.e. not evaluated. It can be left,
|
||
right, top or left-right. @var{DOC} is the docstring for the new
|
||
layout-function ``ecb-layout-function-<name>''. @var{CREATE-CODE} is
|
||
all the lisp code which is necessary to define the
|
||
ECB-windows/buffers. This macro adds the layout with @var{NAME} and
|
||
@var{TYPE}to the internal variable @code{ecb-available-layouts}.
|
||
|
||
Preconditions for @var{CREATE-CODE}:
|
||
@enumerate
|
||
@item
|
||
Current frame is splitted at least in one edit-window and the
|
||
``column'' (for layout types left, right and left-right) rsp. ``row''
|
||
(for a top layout) for the special ECB-windows/buffers. The width of
|
||
the ``column'' rsp. the height of the ``row'' is always defined with
|
||
the option @code{ecb-windows-width} rsp. @code{ecb-windows-height}.
|
||
Depending on the value of the option @code{ecb-compile-window-height}
|
||
there is also a compile window at the bottom of the frame which is
|
||
stored in @code{ecb-compile-window}.
|
||
|
||
@item
|
||
All windows are not dedicated.
|
||
|
||
@item
|
||
Neither the edit-window nor the compile-window (if there is one) are
|
||
selected for types left, right and top. For type left-right the left
|
||
column-window is selected
|
||
|
||
@item
|
||
All ECB-advices of the advice-sets @code{ecb-basic-adviced-functions}
|
||
and @code{ecb-permanent-adviced-functions} are disabled.
|
||
@end enumerate
|
||
|
||
Things @var{CREATE-CODE} has to do:
|
||
@enumerate
|
||
@item
|
||
Splitting the ECB-tree-windows-column(s)/row (s.a.) in all the
|
||
ECB-windows the layout should contain (directories, sources, methods
|
||
and history). The split must not be done with other functions than
|
||
@code{ecb-split-hor} and @code{ecb-split-ver}! It is recommended not to
|
||
to use a ``hard'' number of split-lines or -rows but using fractions
|
||
between -0.9 and +0.9! Tip: It is recommended to spilt from right to
|
||
left and from bottom to top or with other words: First create the
|
||
right-most and bottom-most special windows!
|
||
|
||
@item
|
||
Making each special ECB-window a dedicated window. This can be done with
|
||
one of the following functions:
|
||
@itemize @minus
|
||
@item @code{ecb-set-directories-buffer}
|
||
@item @code{ecb-set-sources-buffer}
|
||
@item @code{ecb-set-methods-buffer}
|
||
@item @code{ecb-set-history-buffer}
|
||
@item @code{ecb-set-speedbar-buffer}
|
||
@item @code{ecb-set-analyse-buffer}
|
||
@item @code{ecb-set-symboldef-buffer}
|
||
@end itemize
|
||
Each layout can only contain one of each tree-buffer-type!
|
||
|
||
In addition to these functions there is a general macro:
|
||
@code{defecb-window-dedicator-to-ecb-buffer}: This macro defines a so called
|
||
``window-dedicator'' which is a function registered at ECB and called by ECB
|
||
to perform any arbitrary code in current window and makes the window autom.
|
||
dedicated to the special ecb-buffer at the end. This can be used by third
|
||
party packages like JDEE to create arbitrary ECB-windows besides the standard
|
||
special ecb-windows.
|
||
|
||
To make a special ECB-window a dedicated window either one of the seven
|
||
functions above must be used or a new ``window-dedicator''-function
|
||
has to be defined with @code{defecb-window-dedicator-to-ecb-buffer} and must be used
|
||
within the layout-definition.
|
||
|
||
@item
|
||
Every(!) special ECB-window must be dedicated to a buffer as described in 2.
|
||
|
||
@item
|
||
@var{CREATE-CODE} must work correctly regardless if there is already a
|
||
compile-window (stored in @code{ecb-compile-window}) or not
|
||
(@code{ecb-compile-window} is nil).
|
||
@end enumerate
|
||
|
||
Things @var{CREATE-CODE} can do or can use:
|
||
@enumerate
|
||
@item
|
||
The value of @code{ecb-compile-window} which contains the compile-window (if
|
||
there is one). Using the values of @code{ecb-compile-window-height},
|
||
@code{ecb-windows-width}, @code{ecb-windows-height}.
|
||
@end enumerate
|
||
|
||
Things @var{CREATE-CODE} must NOT do:
|
||
@enumerate
|
||
@item Splitting the edit-window
|
||
@item Creating a compile-window
|
||
@item
|
||
Deleting the edit-window, the compile-window (if there is any) or the
|
||
ECB-windows-column(s)/row (see Precondition 1.)
|
||
@item
|
||
Referring to the value of @code{ecb-edit-window} because this is always nil
|
||
during @var{CREATE-CODE}.
|
||
@end enumerate
|
||
|
||
Postconditions for @var{CREATE-CODE}:
|
||
@enumerate
|
||
@item
|
||
The edit-window must be the selected window and must not be dedicated
|
||
and not be splitted.
|
||
|
||
@item
|
||
Every window besides the edit-window (and the compile-window) must be
|
||
a dedicated window (e.g. a ECB-tree-window).
|
||
@end enumerate
|
||
@end defmac
|
||
|
||
Use this macro to program new layouts within your @file{.emacs} or any
|
||
other file which is loaded into your Emacs. After loading the file(s)
|
||
with all the new layout-definitions you can use it by customizing the
|
||
option @code{ecb-layout-name} to the appropriate name or with the
|
||
command @code{ecb-change-layout}.
|
||
|
||
With the function @code{ecb-layout-undefine} you can remove a layout
|
||
from the list of available layouts:
|
||
|
||
@defun layout-undefine name
|
||
Unbind ecb-layout-function-<NAME> and
|
||
ecb-delete-window-ecb-windows-<NAME> and remove @code{NAME} from
|
||
@code{ecb-available-layouts}.
|
||
@end defun
|
||
|
||
Here is an example for a new layout programmed with
|
||
@code{ecb-layout-define}:
|
||
|
||
@example
|
||
@group
|
||
(ecb-layout-define "my-own-layout" left nil
|
||
;; The frame is already splitted side-by-side and point stays in the
|
||
;; left window (= the ECB-tree-window-column)
|
||
|
||
;; Here is the creation code for the new layout
|
||
|
||
;; 1. Defining the current window/buffer as ECB-methods buffer
|
||
(ecb-set-methods-buffer)
|
||
;; 2. Splitting the ECB-tree-windows-column in two windows
|
||
(ecb-split-ver 0.75 t)
|
||
;; 3. Go to the second window
|
||
(other-window 1)
|
||
;; 4. Defining the current window/buffer as ECB-history buffer
|
||
(ecb-set-history-buffer)
|
||
;; 5. Make the ECB-edit-window current (see Postcondition above)
|
||
(select-window (next-window)))
|
||
@end group
|
||
@end example
|
||
|
||
This layout definition defines a layout with name ``my-own-layout''
|
||
which looks like:
|
||
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
| | |
|
||
| | |
|
||
| | |
|
||
| Methods | |
|
||
| | |
|
||
| | |
|
||
| | Edit |
|
||
| | |
|
||
| | |
|
||
|--------------| |
|
||
| | |
|
||
| History | |
|
||
| | |
|
||
-------------------------------------------------------
|
||
| |
|
||
| Compilation |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@node Programming special windows, Possible layout-outlines, Programming a new layout, The layout-engine
|
||
@subsection All aspects of programming special windows
|
||
|
||
ECB offers a flexible programmable layout-engine for other packages to
|
||
display their own contents and informations in special ECB-windows. An
|
||
example could be a graphical debugger which offers a special window for
|
||
displaying local variables and another special window for messages
|
||
from the debugger-process (like JDEbug of JDEE@footnote{JDEE is
|
||
available at
|
||
@ifhtml
|
||
@uref{http://jdee.sunsite.dk/}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://jdee.sunsite.dk/}
|
||
@end ifnothtml
|
||
}).
|
||
|
||
This section explains all aspects of programming new special windows,
|
||
adding them to a new layout and synchronizing them with edit-window of
|
||
ECB. This can be done best with an easy example which nevertheless
|
||
covers all necessary aspects to be a good example and skeleton for
|
||
complex tools (like a graphical debugger) which want to use the
|
||
layout-engine of ECB do display their own information.
|
||
|
||
@strong{IMPORTANT}: See @ref{tree-buffer} for a full documentation of
|
||
the library tree-buffer.el which can be used for programming a new
|
||
special window as a tree!
|
||
|
||
Here comes the example:
|
||
|
||
@subsubsection The outline of the example layout:
|
||
|
||
@example
|
||
@group
|
||
-------------------------------------------------------
|
||
|Bufferinfo for <filename>: |[prior] |
|
||
|Type: file |[next] |
|
||
|Size: 23456 | |
|
||
|Modes: rw-rw-rw- | |
|
||
|-----------------------------------------------------|
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| edit-window |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
-------------------------------------------------------
|
||
| |
|
||
| compilation-window |
|
||
| |
|
||
-------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
@subsubsection The description of the layout-contents
|
||
|
||
The top-left window always displays informations about the current
|
||
buffer in the selected edit-window. This window demonstrates how
|
||
autom. synchronizing a special window/buffer of a layout with current
|
||
edit-window.
|
||
|
||
The top-right window contains an read-only ``action-buffer'' and
|
||
offers two buttons which can be used with the middle mouse-button to
|
||
scroll the edit-window. This is not very senseful but it demonstrates
|
||
how to control the edit-window with actions performed in a special
|
||
window/buffer of a layout.
|
||
|
||
(If you have not set a compilation-window in
|
||
@code{ecb-compile-window-height} then the layout contains no persistent
|
||
compilation window and the other windows get a little more place).
|
||
|
||
@subsubsection The example code
|
||
|
||
Now let have us a look at the several parts of the Elisp-program
|
||
needed to program this new example layout. ECB contains a library
|
||
@file{ecb-examples.el} which contains the full working code of this
|
||
example. To test this example and to play with it you can load this
|
||
library into Emacs (with @code{load-library} for example) and then
|
||
calling @code{ecb-change-layout} (bound to @kbd{C-c . lc}) and
|
||
inserting ``example-layout1'' as layout-name. An alternative is
|
||
calling @code{ecb-examples-activate} and
|
||
@code{ecb-examples-deactivate}. For details see file
|
||
@file{ecb-examples.el}.
|
||
|
||
The following steps only contain code-skeletons to demonstrate the
|
||
principle. The full working code is available in
|
||
@file{ecb-examples.el}.
|
||
|
||
@subsubsection The bufferinfo buffer of the example
|
||
|
||
The name of the bufferinfo buffer:
|
||
|
||
@lisp
|
||
(defconst ecb-examples-bufferinfo-buffer-name " *ECB buffer info*")
|
||
@end lisp
|
||
|
||
Two helper functions for displaying infos in a special buffer:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-print-file-attributes (buffer filename)
|
||
(ecb-with-readonly-buffer buffer
|
||
(erase-buffer)
|
||
(insert (format "Bufferinfo for %s:\n\n" filename))
|
||
;; insert with the function `file-attributes' some
|
||
;; informations about FILENAME.
|
||
))
|
||
|
||
(defun ecb-examples-print-non-filebuffer (buffer buffer-name)
|
||
(ecb-with-readonly-buffer buffer
|
||
(erase-buffer)
|
||
;; analogous to `ecb-examples-print-file-attributes'
|
||
))
|
||
@end group
|
||
@end lisp
|
||
|
||
|
||
For synchronizing the bufferinfo window with the current source-buffer we
|
||
first introduce some three options which are very typical for a special
|
||
ECB-window which should be synchronized with current buffer in the edit-area.
|
||
|
||
The :type of the first two options is essential and @strong{MUST NOT} be
|
||
defined differently, because the macro @code{defecb-autocontrol/sync-function}
|
||
(s.b.) and the function @code{ecb-activate-ecb-autocontrol-function} (s.b.)
|
||
expects exactly these option-types.
|
||
|
||
The third one for an own hook running after synchronizing is not essential but
|
||
mostly useful for users who wants to do some own stuff.
|
||
|
||
Here come the three options - for detailled docstrings take a look into the
|
||
file @file{ecb-examples.el}:
|
||
|
||
@lisp
|
||
@group
|
||
(defcustom ecb-examples-bufferinfo-buffer-sync 'basic
|
||
"*Synchronize the bufferinfo buffer automatically with current edit buffer.
|
||
|
||
If 'always then the synchronization takes place always a buffer changes in the
|
||
edit window, if nil then never. If a list of major-modes then only if the
|
||
`major-mode' of the new buffer belongs NOT to this list.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
`ecb-basic-buffer-sync'.
|
||
|
||
IMPORTANT NOTE: Every time the synchronization is done the hook
|
||
`ecb-bufferinfo-buffer-sync-hook' is evaluated."
|
||
:group 'ecb-examples-bufferinfo
|
||
:type '(radio :tag "Synchronize ECBs example bufferino buffer"
|
||
(const :tag "use basic value" :value basic)
|
||
(const :tag "Always" :value always)
|
||
(const :tag "Never" nil)
|
||
(repeat :tag "Not with these modes"
|
||
(symbol :tag "mode"))))
|
||
|
||
(defcustom ecb-examples-bufferinfo-buffer-sync-delay 'basic
|
||
"*Time Emacs must be idle before the bufferinfo-buffer is synchronized.
|
||
Synchronizing is done with the current source displayed in the edit window. If
|
||
nil then there is no delay, means synchronization takes place immediately. A
|
||
small value of about 0.25 seconds saves CPU resources and you get even though
|
||
almost the same effect as if you set no delay.
|
||
|
||
If the special value 'basic is set then ECB uses the setting of the option
|
||
`ecb-basic-buffer-sync-delay'"
|
||
:group 'ecb-analyse
|
||
:type '(radio (const :tag "use basic value" :value basic)
|
||
(const :tag "No synchronizing delay" :value nil)
|
||
(number :tag "Idle time before synchronizing" :value 2))
|
||
:set (function (lambda (symbol value)
|
||
(set symbol value)
|
||
(if (and (boundp 'ecb-minor-mode)
|
||
(featurep 'ecb-examples)
|
||
ecb-minor-mode)
|
||
(ecb-activate-ecb-autocontrol-function
|
||
value 'ecb-examples-bufferinfo-buffer-sync))))
|
||
:initialize 'custom-initialize-default)
|
||
|
||
(defcustom ecb-examples-bufferinfo-buffer-sync-hook nil
|
||
"Hook run at the end of `ecb-examples-bufferinfo-buffer-sync'.
|
||
See documentation of `ecb-examples-bufferinfo-buffer-sync' for conditions when
|
||
synchronization takes place and so in turn these hooks are evaluated.
|
||
|
||
..."
|
||
:group 'ecb-analyse
|
||
:type 'hook)
|
||
|
||
@end group
|
||
@end lisp
|
||
|
||
Now we define the synchronizing function. @strong{IMPORTANT}: The main
|
||
synchronizing function must be defined with the macro
|
||
@code{defecb-autocontrol/sync-function}! See the documentation of this
|
||
function for all details.
|
||
|
||
The following function synchronizes the bufferinfo buffer with the current
|
||
buffer of the edit-window if that buffer has changed
|
||
|
||
See the comments in the code for explanations.
|
||
|
||
@lisp
|
||
@group
|
||
(defvar ecb-examples-bufferinfo-last-file-buffer nil)
|
||
|
||
(defecb-autocontrol/sync-function ecb-examples-bufferinfo-buffer-sync
|
||
ecb-examples-bufferinfo-buffer-name ecb-examples-bufferinfo-buffer-sync t
|
||
"Synchronizes the buffer-info buffer with current source if changed.
|
||
Can be called interactively but normally this should not be necessary because
|
||
it will be called autom. by the internal synchronizing mechanism of ECB."
|
||
|
||
;; The macro `defecb-autocontrol/sync-function' does a lot for our
|
||
;; conveniance:
|
||
|
||
;; 1) here we can be sure that the buffer with name
|
||
;; `ecb-examples-bufferinfo-buffer-name' is displayed in a window of
|
||
;; `ecb-frame' because the macro `defecb-autocontrol/sync-function'
|
||
;; encapsulates automatically the following code within
|
||
;; `ecb-do-if-buffer-visible-in-ecb-frame' and this macro binds locally the
|
||
;; variables visible-buffer and visible-window: visible-window:=
|
||
;; (get-buffer-window ecb-examples-bufferinfo-buffer-name) visible-buffer:=
|
||
;; (get-buffer ecb-examples-bufferinfo-buffer-name)
|
||
|
||
;; 2) The macro `defecb-autocontrol/sync-function' automatically takes care of
|
||
;; the setting of option `ecb-examples-bufferinfo-buffer-sync' and runs the
|
||
;; following code only when the related conditions are true
|
||
|
||
;; 3) The generated function has one optional argument FORCE which can be used
|
||
;; in the code below.
|
||
|
||
;; 4) The macro `defecb-autocontrol/sync-function' makes this synchronizing
|
||
;; function interactive
|
||
|
||
;; For details please read the documentation of
|
||
;; `defecb-autocontrol/sync-function'!
|
||
|
||
;; synchronize only when point stays in one of the edit-window.
|
||
(when (ecb-point-in-edit-window-number)
|
||
|
||
;; we need the file-name of indirect-buffers too (if the base-buffer is a
|
||
;; file-buffer), therefore we use `ecb-buffer-file-name' (see the docstring
|
||
;; of this function)
|
||
(let ((filename (ecb-buffer-file-name (current-buffer))))
|
||
|
||
(if (and filename (ecb-buffer-or-file-readable-p filename))
|
||
|
||
;; synchronizing for real filesource-buffers or indirect buffers of
|
||
;; real file buffers
|
||
|
||
;; Let us be smart: We synchronize only if sourcebuffer has changed
|
||
;; or if the argument FORCE is not nil
|
||
(when (or force
|
||
(not (equal (current-buffer)
|
||
ecb-examples-bufferinfo-last-file-buffer)))
|
||
;; set new last-file-buffer so we can check next time if changed
|
||
(setq ecb-examples-bufferinfo-last-file-buffer (current-buffer))
|
||
;; we display the file-infos for current source-buffer
|
||
(ecb-examples-print-file-attributes visible-buffer filename))
|
||
|
||
;; what should we do for non file buffers like help-buffers etc...
|
||
(setq ecb-examples-bufferinfo-last-file-buffer nil)
|
||
(ecb-examples-print-non-filebuffer visible-buffer
|
||
(buffer-name (current-buffer)))))
|
||
|
||
;; Now lets run the hooks in `ecb-examples-bufferinfo-buffer-sync-hook'
|
||
(run-hooks 'ecb-examples-bufferinfo-buffer-sync-hook)))
|
||
@end group
|
||
@end lisp
|
||
|
||
Two conveniance commands for the user:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-maximize-bufferinfo-window ()
|
||
"Maximize the bufferinfo-window.
|
||
I.e. delete all other ECB-windows, so only one ECB-window and the
|
||
edit-window\(s) are visible \(and maybe a compile-window). Works
|
||
also if the ECB-analyse-window is not visible in current layout."
|
||
(interactive)
|
||
(ecb-display-one-ecb-buffer ecb-examples-bufferinfo-buffer-name))
|
||
|
||
(defun ecb-goto-bufferinfo-window ()
|
||
"Make the bufferinfo-window the current window."
|
||
(interactive)
|
||
(ecb-goto-ecb-window ecb-examples-bufferinfo-buffer-name))
|
||
@end group
|
||
@end lisp
|
||
|
||
@subsubsection Synchronizing the bufferinfo-buffer automatically
|
||
|
||
By using the macro @code{defecb-autocontrol/sync-function} for defining our
|
||
synchronizing function we have already registered this function as a
|
||
synchronizing function managed by ECB:
|
||
|
||
The only thing we need is to tell ECB when this function should run - for this
|
||
we have already defined the first two options in our example (s.a.).
|
||
ECB offers to functions for
|
||
|
||
@itemize
|
||
@item @code{ecb-activate-ecb-autocontrol-function}: Activate/start synchronizing
|
||
@item @code{ecb-stop-autocontrol/sync-function}: Stop synchronizing
|
||
@end itemize
|
||
|
||
It's smart to activate the synchronizing function within the
|
||
dedicator-function. See the comment within the following function.
|
||
|
||
The function which makes the bufferinfo-buffer dedicated to a window
|
||
and registers the new special window/buffer at ECB.
|
||
|
||
@lisp
|
||
@group
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-examples-set-bufferinfo-buffer
|
||
ecb-examples-bufferinfo-buffer-name nil
|
||
"Set the buffer in the current window to the bufferinfo-buffer and make this
|
||
window dedicated for this buffer. Makes the buffer read-only."
|
||
|
||
;; activating the synchronization of the bufferinfo-window:
|
||
;; `ecb-activate-ecb-autocontrol-function' takes care of the possible
|
||
;; settings in `ecb-examples-bufferinfo-buffer-sync-delay'. Therefore we do
|
||
;; it here because then changes in ecb-examples-bufferinfo-buffer-sync-delay
|
||
;; are taken into account each time the bufferinfo buffer is set in the
|
||
;; layout (after each hiding/showing the ecb-window, each redrawing the
|
||
;; layout deactivating/activating ECB)
|
||
(ecb-activate-ecb-autocontrol-function ecb-examples-bufferinfo-buffer-sync-delay
|
||
'ecb-examples-bufferinfo-buffer-sync)
|
||
|
||
(switch-to-buffer (get-buffer-create ecb-examples-bufferinfo-buffer-name))
|
||
(setq buffer-read-only t))
|
||
@end group
|
||
@end lisp
|
||
|
||
|
||
This is all what we need for the special bufferinfo buffer. We have
|
||
demonstrated already three of the important functions/macros of the
|
||
layout-engine API of ECB: @code{ecb-with-readonly-buffer},
|
||
@code{defecb-autocontrol/sync-function} and @code{defecb-window-dedicator-to-ecb-buffer}
|
||
(@pxref{The layout-engine API}. Especially the second macro is a MUST for
|
||
programming good synchronizing functions which do not waste CPU-power! We have
|
||
also shown how to start/activate a synchronizing function by
|
||
@code{ecb-activate-ecb-autocontrol-function}. Later we will see how to stop
|
||
it.
|
||
|
||
@subsubsection The action buffer of the example
|
||
|
||
The name of the action-buffer:
|
||
|
||
@lisp
|
||
(defconst ecb-examples-action-buffer-name " *ECB action buffer*")
|
||
@end lisp
|
||
|
||
Two helper functions for creating a readonly action-buffer with a
|
||
special local key-map for the middle-mouse-button and two buttons
|
||
[prior] and [next]:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-insert-text-in-action-buffer (text)
|
||
(let ((p (point)))
|
||
(insert text)
|
||
(put-text-property p (+ p (length text)) 'mouse-face
|
||
'highlight)))
|
||
|
||
(defun ecb-examples-action-buffer-create ()
|
||
(save-excursion
|
||
(if (get-buffer ecb-examples-action-buffer-name)
|
||
(get-buffer ecb-examples-action-buffer-name)
|
||
|
||
(set-buffer (get-buffer-create
|
||
ecb-examples-action-buffer-name))
|
||
|
||
;; we setup a local key-map and bind middle-mouse-button
|
||
;; see ecb-examples.el for the full code
|
||
|
||
;; insert the action buttons [prior] and [next] and
|
||
;; make it read-only
|
||
|
||
(ecb-with-readonly-buffer (current-buffer)
|
||
(erase-buffer)
|
||
(ecb-examples-insert-text-in-action-buffer "[prior]")
|
||
;; analogous for the [next] button
|
||
)
|
||
|
||
(current-buffer))))
|
||
@end group
|
||
@end lisp
|
||
|
||
The function which performs the actions in the action-buffer if
|
||
clicked with the middle-mouse button onto a button [next] or [prior].
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-action-buffer-clicked (e)
|
||
(interactive "e")
|
||
(mouse-set-point e)
|
||
(let ((line (buffer-substring (ecb-line-beginning-pos)
|
||
(ecb-line-end-pos))))
|
||
(cond ((string-match "prior" line)
|
||
(ecb-select-edit-window)
|
||
(call-interactively 'scroll-down))
|
||
((string-match "next" line)
|
||
;; analogous for [next]
|
||
))))
|
||
@end group
|
||
@end lisp
|
||
|
||
Two conveniance-commands for the user:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-maximize-action-window ()
|
||
"Maximize the action-window.
|
||
I.e. delete all other ECB-windows, so only one ECB-window and the
|
||
edit-window\(s) are visible \(and maybe a compile-window). Works
|
||
also if the ECB-analyse-window is not visible in current layout."
|
||
(interactive)
|
||
(ecb-display-one-ecb-buffer ecb-examples-action-buffer-name))
|
||
|
||
(defun ecb-goto-action-window ()
|
||
"Make the action-window the current window."
|
||
(interactive)
|
||
(ecb-goto-ecb-window ecb-examples-action-buffer-name))
|
||
@end group
|
||
@end lisp
|
||
|
||
The function which makes the action-buffer dedicated to a window and
|
||
registers it at ECB.
|
||
|
||
@lisp
|
||
@group
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-examples-set-action-buffer
|
||
ecb-examples-action-buffer-name nil
|
||
"Set the buffer in the current window to the action-buffer
|
||
and make this window dedicated for this buffer."
|
||
(switch-to-buffer (buffer-name (ecb-examples-action-buffer-create))))
|
||
@end group
|
||
@end lisp
|
||
|
||
We do not need more code for the action buffer. All of the code is
|
||
standard emacs-lisp which would also needed if used without ECB.
|
||
|
||
@subsubsection Adding the bufferinfo- and action-buffer to a new layout
|
||
|
||
Now we add the bufferinfo- and the action-buffer to a new layout of
|
||
type top with name ``example-layout1'':
|
||
|
||
@lisp
|
||
@group
|
||
(ecb-layout-define "example-layout1" top
|
||
|
||
;; dedicating the bufferinfo window to the bufferinfo-buffer
|
||
(ecb-examples-set-bufferinfo-buffer)
|
||
|
||
;; creating the action-window
|
||
(ecb-split-hor 0.75)
|
||
|
||
;; dedicate the action window to the action-buffer
|
||
(ecb-examples-set-action-buffer)
|
||
|
||
;; select the edit-window
|
||
(select-window (next-window)))
|
||
@end group
|
||
@end lisp
|
||
|
||
This all what we need to define the new layout. See @ref{Programming a
|
||
new layout} for more details of the pure layout-programming task.
|
||
|
||
@subsubsection Activating and deactivating new layouts
|
||
|
||
Because a set of new special windows integrated in a new layout is
|
||
often just the GUI of a complete tool (like a graphical debugger) we
|
||
demonstrate here the complete activation and deactivation of such a
|
||
tool or at least of the tool-GUI. We decide that the GUI of our
|
||
example ``tool'' needs a compile-window with height 5 lines and the
|
||
height of the special windows ``row'' on top should be exactly 6 lines
|
||
(normally width and height of the special windows should be a fraction
|
||
of the frame, but here we use 6 lines@footnote{You can change the code
|
||
in the file @file{ecb-examples.el} to use a frame-fraction of 0.2
|
||
instead of 6 hard lines, just try it!}
|
||
|
||
Here comes the (de)activation code.
|
||
|
||
The code for saving and restoring the state before activation (the
|
||
full code is available in @file{ecb-examples.el}:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-preactivation-state(action)
|
||
(cond ((equal action 'save)
|
||
;; code for saving the state
|
||
)
|
||
((equal action 'restore)
|
||
;; code for restoring the state
|
||
)))
|
||
@end group
|
||
@end lisp
|
||
|
||
The following function activates the GUI of our example tool:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-activate ()
|
||
"Activate the new layout \"example-layout1\".
|
||
Acivates the function `ecb-examples-bufferinfo-buffer-sync', set
|
||
`ecb-compile-window-height' to 5 and `ecb-windows-height' to 6. The
|
||
preactivation-state is saved and will be restored by
|
||
`ecb-examples-deactivate'."
|
||
(interactive)
|
||
|
||
(assert (featurep 'ecb) nil
|
||
"ECB must be loaded!")
|
||
(assert ecb-minor-mode nil
|
||
"ECB must be activated!")
|
||
(assert (equal (selected-frame) ecb-frame) nil
|
||
"The ECB-frame must be selected!")
|
||
(assert (not (ecb-string= ecb-layout-name "example-layout1")) nil
|
||
"The examples-layout1 is already active!")
|
||
|
||
;; saving the state
|
||
(ecb-examples-preactivation-state 'save)
|
||
|
||
;; switch to our prefered layout
|
||
(setq ecb-windows-height 6)
|
||
(setq ecb-compile-window-height 8)
|
||
(let ((ecb-change-layout-preserves-compwin-state nil))
|
||
;; activating the synchronization of the bufferinfo-window is done in the
|
||
;; dedicator-function (see `ecb-examples-set-bufferinfo-buffer' for the
|
||
;; reason). So the synchronizing will be activated implicitly with the
|
||
;; layout-switch because this redraws the layout and this calls all
|
||
;; dedicator-functions.
|
||
(ecb-layout-switch "example-layout1")))
|
||
@end group
|
||
@end lisp
|
||
|
||
This function deactivates the GUI of our example-tool and restores the
|
||
state as before activation:
|
||
|
||
@lisp
|
||
@group
|
||
(defun ecb-examples-deactivate ()
|
||
"Deactivate the new layout \"example-layout1\".
|
||
Stops `ecb-examples-bufferinfo-buffer-sync' and restore the state
|
||
as before activation."
|
||
(interactive)
|
||
|
||
(assert (featurep 'ecb) nil
|
||
"ECB must be loaded!")
|
||
(assert ecb-minor-mode nil
|
||
"ECB must be activated!")
|
||
(assert (equal (selected-frame) ecb-frame) nil
|
||
"The ECB-frame must be selected!")
|
||
(assert (ecb-string= ecb-layout-name "example-layout1") nil
|
||
"The example-layout1 is not active!")
|
||
|
||
;; we stop here the synchronization.
|
||
(ecb-stop-autocontrol/sync-function 'ecb-examples-bufferinfo-buffer-sync)
|
||
|
||
(ecb-examples-preactivation-state 'restore)
|
||
|
||
(ecb-layout-switch ecb-layout-name))
|
||
@end group
|
||
@end lisp
|
||
|
||
|
||
Now we have all code for the new layout and the new layout-buffers.
|
||
The example is ready for use; just load @file{ecb-examples.el} (s.a.).
|
||
|
||
@node Possible layout-outlines, The layout-engine API, Programming special windows, The layout-engine
|
||
@subsection The wide range of possible layout-outlines
|
||
|
||
In the two previous sections @ref{Programming a new layout} and
|
||
@ref{Programming special windows} we have explained in detail how to
|
||
program new layouts and how to program new special windows/buffers and
|
||
adding them to a new layout.
|
||
|
||
The intention of this section is to be a summary what are the real
|
||
restrictions for a new layout-outline programmed with
|
||
@code{ecb-layout-define}. This is necessary because until now we just
|
||
programmed ``obvious'' layouts, means layout which are in principle
|
||
very similar to the standard ones which means one big edit-window and
|
||
some special windows ``around'' this edit-window. This section will
|
||
show you that a layout can have also very different outlines.
|
||
|
||
OK, here are the real restrictions and conditions for a layout
|
||
programmed with @code{ecb-layout-define}:
|
||
@enumerate
|
||
@item
|
||
It must have exactly one edit-window regardless of its size. The user
|
||
of this layout can later split this edit-window in as many
|
||
edit-windows as he like.
|
||
|
||
@item
|
||
All other windows created within the @var{CREATE-CODE} body of
|
||
@code{ecb-layout-define} (@pxref{Programming a new layout}) must be
|
||
dedicated to their buffers.
|
||
|
||
@item
|
||
All the dedicated windows must (exclusive!) either reside on the left,
|
||
right, top or left-and-right side of the edit-window. This will be
|
||
defined with the @var{TYPE}-argument of @code{ecb-layout-define}
|
||
(@pxref{Programming a new layout}).
|
||
@end enumerate
|
||
|
||
You see, there are only three restrictions/conditions. These and only
|
||
these must be fulfilled at layout-programming.
|
||
|
||
Demonstrating what this really means and how flexible the
|
||
layout-engine of ECB really is, can be done best with some
|
||
``pathological'' layout-outlines. All the following are correct
|
||
layouts (working code is added below each layout):
|
||
|
||
The following is a top layout with three vertical layered special
|
||
windows.
|
||
|
||
@example
|
||
@group
|
||
------------------------------------------------------------------
|
||
| |
|
||
| Upper special window (a tree-buffer) |
|
||
| |
|
||
|----------------------------------------------------------------|
|
||
| |
|
||
| Middle special window (no tree-buffer) |
|
||
| |
|
||
|----------------------------------------------------------------|
|
||
| |
|
||
| Lower special window (a tree-buffer) |
|
||
| |
|
||
|================================================================|
|
||
| |
|
||
| Edit-area |
|
||
| (can be splitted by the user in several edit-windows) |
|
||
------------------------------------------------------------------
|
||
| |
|
||
| Compilation-window (optional) |
|
||
| |
|
||
------------------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
Here is the code for that top layout (all buffers are dummy-buffers):
|
||
|
||
@lisp
|
||
@group
|
||
|
||
;; The "window dedicator to buffer" functions:
|
||
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-set-usw-buffer
|
||
upper-special-window-buffer-name t
|
||
(switch-to-buffer (get-buffer-create "Upper special window")))
|
||
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-set-msw-buffer
|
||
middle-special-window-buffer-name nil
|
||
(switch-to-buffer (get-buffer-create "Middle special window")))
|
||
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-set-lsw-buffer
|
||
lower-special-window-buffer-name t
|
||
(switch-to-buffer (get-buffer-create "Lower special window")))
|
||
|
||
;; The layout itself:
|
||
|
||
(ecb-layout-define "example-layout3" top
|
||
nil
|
||
|
||
;; here we have an edit-window and above one top window which we can
|
||
;; now split in several other windows. Dependent on the value of
|
||
;; `ecb-compile-window-height' we have also a compile-window at the
|
||
;; bottom.
|
||
|
||
(ecb-set-usw-buffer)
|
||
(ecb-split-ver 0.33)
|
||
(ecb-set-msw-buffer)
|
||
(ecb-split-ver 0.5)
|
||
(ecb-set-lsw-buffer)
|
||
|
||
;; select the edit-window.
|
||
(select-window (next-window)))
|
||
@end group
|
||
@end lisp
|
||
|
||
|
||
The following is a left-right layout which has six special windows in
|
||
the left-''column'' and one big special window in the
|
||
right-''column''. For left-right layouts the left-''column'' and the
|
||
right-''column'' have always the same width.
|
||
|
||
@example
|
||
@group
|
||
------------------------------------------------------------------
|
||
| | | | |
|
||
| Left1 | Left5 | | |
|
||
| | | | |
|
||
|-------------| | | |
|
||
| | | | | |
|
||
| | | | | |
|
||
| | | | | |
|
||
| Left2| Left3|-------| Edit-area | Right1 |
|
||
| | | | (can be splitted | |
|
||
| | | | in several edit- | |
|
||
| | | | windows) | |
|
||
|-------------| | | |
|
||
| | | | |
|
||
| Left4 | Left6 | | |
|
||
| | | | |
|
||
------------------------------------------------------------------
|
||
| |
|
||
| Compilation-window (optional) |
|
||
| |
|
||
------------------------------------------------------------------
|
||
@end group
|
||
@end example
|
||
|
||
Here is the code for that left-right layout, again with dummy-buffers
|
||
(depending to your screen-resolution you will need a quite big value
|
||
for @code{ecb-windows-width}, e.g. 0.4):
|
||
|
||
Here is one of the ``window dedicator for buffer''-functions@footnote{The
|
||
``window dedicators'' for all these ecb-windows/buffers are not explicitly
|
||
described - they look all like @code{ecb-set-left1-buffer} - of course with
|
||
different buffer-names!}:
|
||
|
||
@lisp
|
||
@group
|
||
(defvar buffer-name-left1 "left1")
|
||
|
||
;; Note that the third argument muts be not nil if the ecb-window should
|
||
;; display an ecb-buffer of type tree-buffer!
|
||
(defecb-window-dedicator-to-ecb-buffer ecb-set-left1-buffer buffer-name-left1 nil
|
||
(switch-to-buffer (get-buffer-create "Left1")))
|
||
@end group
|
||
@end lisp
|
||
|
||
Here is the layout-definition itself:
|
||
|
||
@lisp
|
||
@group
|
||
(ecb-layout-define "example-layout2" left-right
|
||
nil
|
||
|
||
;; here we have an edit-window and left and right two windows each
|
||
;; with width `ecb-windows-width'. Dependent to the value of
|
||
;; `ecb-compile-window-height' we have also a compile-window at the
|
||
;; bottom.
|
||
|
||
(ecb-set-left1-buffer)
|
||
(ecb-split-hor 0.66 t)
|
||
(ecb-split-ver 0.75)
|
||
(ecb-set-left4-buffer)
|
||
(select-window (previous-window (selected-window) 0))
|
||
(ecb-split-ver 0.25 nil t)
|
||
(ecb-set-left2-buffer)
|
||
(ecb-split-hor 0.5)
|
||
(ecb-set-left3-buffer)
|
||
(select-window (next-window (next-window)))
|
||
(ecb-set-left5-buffer)
|
||
(ecb-split-ver 0.5)
|
||
(ecb-set-left6-buffer)
|
||
(select-window (next-window (next-window)))
|
||
(ecb-set-right1-buffer))
|
||
|
||
;; select the edit-window
|
||
(select-window (previous-window (selected-window) 0)))
|
||
@end group
|
||
@end lisp
|
||
|
||
Especially the last example should demonstrate that even very
|
||
complicated layouts are easy to program with @code{ecb-layout-define}.
|
||
If such layouts are senseful is another topic ;-)
|
||
|
||
@node The layout-engine API, , Possible layout-outlines, The layout-engine
|
||
@subsection The complete layout-engine API of ECB
|
||
|
||
This section lists all functions, macros, variables and user-options
|
||
the layout-engine API of ECB offers foreign packages. Call
|
||
@code{describe-function} rsp. @code{describe-variable} to get a
|
||
detailed description.
|
||
|
||
Functions and macros for programming with layouts and special
|
||
ecb-windows:
|
||
@itemize @minus
|
||
@item @code{defecb-window-dedicator-to-ecb-buffer}
|
||
@item @code{ecb-available-layouts-member-p}
|
||
@item @code{ecb-canonical-ecb-windows-list}
|
||
@item @code{ecb-canonical-edit-windows-list}
|
||
@item @code{ecb-compile-window-live-p}
|
||
@item @code{ecb-compile-window-state}
|
||
@item @code{ecb-do-if-buffer-visible-in-ecb-frame}
|
||
@item @code{ecb-exec-in-window}
|
||
@item @code{ecb-get-current-visible-ecb-buffers}
|
||
@item @code{ecb-layout-define}
|
||
@item @code{ecb-layout-switch}
|
||
@item @code{ecb-layout-undefine}
|
||
@item @code{ecb-point-in-compile-window}
|
||
@item @code{ecb-point-in-ecb-window-number}
|
||
@item @code{ecb-point-in-edit-window-number}
|
||
@item @code{ecb-select-edit-window}
|
||
@item @code{ecb-split-hor}
|
||
@item @code{ecb-split-ver}
|
||
@item @code{ecb-where-is-point}
|
||
@item @code{ecb-with-dedicated-window}@footnote{Normally not needed because
|
||
@code{defecb-window-dedicator-to-ecb-buffer} does all necessary.}
|
||
@end itemize
|
||
|
||
Utility functions/macros:
|
||
@itemize @minus
|
||
@item @code{ecb-display-one-ecb-buffer}
|
||
@item @code{ecb-enlarge-window}
|
||
@item @code{ecb-fix-filename}
|
||
@item @code{ecb-goto-ecb-window}
|
||
@item @code{ecb-window-live-p}
|
||
@item @code{ecb-with-readonly-buffer}
|
||
@end itemize
|
||
|
||
Some other maybe useful functions/macros:
|
||
@itemize @minus
|
||
@item @code{ecb-with-adviced-functions}
|
||
@item @code{ecb-with-original-functions}
|
||
@item @code{ecb-with-some-adviced-functions}
|
||
@end itemize
|
||
|
||
Some useful @strong{READONLY} variables:
|
||
@itemize @minus
|
||
@item @code{ecb-compile-window}
|
||
@item @code{ecb-last-edit-window-with-point}
|
||
@item @code{ecb-last-source-buffer}
|
||
@end itemize
|
||
|
||
@strong{Caution}: DO NOT USE THE VARIABLE @code{ecb-edit-window} IN
|
||
YOUR PROGRAMS!
|
||
|
||
User-options and hooks related to the layout-engine API:
|
||
@itemize @minus
|
||
@item @code{ecb-basic-buffer-sync-hook}
|
||
@item @code{ecb-hide-ecb-windows-after-hook}
|
||
@item @code{ecb-hide-ecb-windows-before-hook}
|
||
@item @code{ecb-redraw-layout-after-hook}
|
||
@item @code{ecb-redraw-layout-before-hook}
|
||
@item @code{ecb-show-ecb-windows-after-hook}
|
||
@item @code{ecb-show-ecb-windows-before-hook}
|
||
@item @code{ecb-windows-height}
|
||
@item @code{ecb-windows-width}
|
||
@item @code{ecb-compile-window-height}
|
||
@end itemize
|
||
|
||
@node Conflicts and bugs, FAQ, Elisp programming, Top
|
||
@chapter Conflicts and bugs of ECB
|
||
|
||
This chapter describes what to do when there are conflicts with other
|
||
packages and also the known (and currently unfixed) bugs of ECB. If
|
||
possible (and in most cases it is possible ;-) then a practicable
|
||
solution or workaround is described.
|
||
|
||
@menu
|
||
* Conflicts:: Conflicts with other packages
|
||
* Bugs:: Known bugs
|
||
@end menu
|
||
|
||
@node Conflicts, Bugs, Conflicts and bugs, Conflicts and bugs
|
||
@section Conflicts with other packages
|
||
|
||
This chapter contains a list of already known conflict between ECB and
|
||
other packages and how to solve them - in most cases ECB already
|
||
contains a suitable workaround.
|
||
|
||
That is followed by a general recipe what you can do when you have
|
||
detected a conflict between ECB and a package is not listed in the
|
||
know-conflicts-section.
|
||
|
||
@subsection Proved workarounds or recommendations for other packages
|
||
|
||
Here is a list of packages which are proved to work properly with ECB
|
||
and if not (i.e. there are conflicts) then helpful
|
||
solutions/hints/workarounds are offered:
|
||
|
||
@subsubsection Package bs.el
|
||
|
||
@cindex bs package
|
||
@cindex bs-show
|
||
The package bs.el offers a nifty buffer-selection buffer. The main
|
||
command of this package is @code{bs-show}. With ECB < 2.20 this
|
||
command does not really working well within activated ECB. But as of
|
||
version 2.20 of ECB there should be no problems using this package.
|
||
|
||
If you add ``*buffer-selection*'' as buffer-name to the option
|
||
@code{ecb-compilation-buffer-names} then ECB will always display the
|
||
buffer-selection buffer of bs in the compile-window (if there is one).
|
||
Otherwise bs will use the edit-area to do its job.
|
||
|
||
@subsubsection Package BBDB
|
||
|
||
@cindex BBDB
|
||
As of ECB 2.21 there should be no conflicts between BBDB and ECB, so
|
||
BBDB can be used even when the ECB-windows are visible.
|
||
|
||
But if you encounter problems then it is recommened to use one of the
|
||
window-managers escreen.el or winring.el (@pxref{Window-managers and
|
||
ECB}). With such a window-manager ECB and BBDB should work together
|
||
very well under all circumstances!
|
||
|
||
@subsubsection Package calendar.el
|
||
|
||
@cindex calendar package
|
||
With activated ECB @code{calendar} does not shrink it<69>s window to the small
|
||
size but splits the window equally. But if you add this to your
|
||
@file{.emacs} it works:
|
||
|
||
@example
|
||
@group
|
||
(add-hook 'initial-calendar-window-hook
|
||
(function (lambda ()
|
||
(when (and ecb-minor-mode
|
||
(ecb-point-in-edit-window))
|
||
;; if no horizontal split then nothing
|
||
;; special to do
|
||
(or (= (frame-width) (window-width))
|
||
(shrink-window (- (window-height) 9))))
|
||
)))
|
||
@end group
|
||
@end example
|
||
|
||
@subsubsection Package cygwin-mount.el
|
||
|
||
@cindex cygwin-mount package
|
||
There can be a conflict between ECB and cygwin-mount.el if the
|
||
following conditions are true:
|
||
|
||
@itemize @minus
|
||
@item You are working with cygwin-mount.el (sounds clear :-)
|
||
@item You have set @code{cygwin-mount-build-mount-table-asynch} to not
|
||
nil
|
||
@item ECB is automatically started after starting Emacs (e.g. with
|
||
@code{ecb-auto-activate} or calling @code{ecb-activate} in
|
||
@code{window-setup-hook})
|
||
@item Your Emacs-setup contains a call of @code{cygwin-mount-activate}.
|
||
@end itemize
|
||
|
||
Under these circumstances Emacs 21.X sometimes eats up the whole CPU (at
|
||
least with Windows XP) and the cygwin-mount-table is never build.
|
||
|
||
But there is an easy work-around: Call @code{cygwin-mount-activate}
|
||
first *AFTER* ECB is activated. This can be done with the hook
|
||
@code{ecb-activate-hook}:
|
||
|
||
@example
|
||
@group
|
||
(add-hook 'ecb-activate-hook
|
||
(function (lambda ()
|
||
(require 'cygwin-mount)
|
||
(setq cygwin-mount-build-mount-table-asynch t)
|
||
(cygwin-mount-activate))))
|
||
|
||
@end group
|
||
@end example
|
||
|
||
@subsubsection Package desktop.el
|
||
|
||
@cindex desktop
|
||
ECB works perfectly with the desktop-saver desktop.el. Normally there should
|
||
be nothing to do for you.
|
||
|
||
But if you encounter problems (e.g. that desktop tries to activate ECB for
|
||
each buffer it loads) then you should add the following entry to the option
|
||
@code{desktop-minor-mode-table}:
|
||
|
||
@example
|
||
(ecb-minor-mode nil)
|
||
@end example
|
||
|
||
If you still encounter problems then you should add entries for all the
|
||
minor-mode of the semantic-package to @code{desktop-minor-mode-table}, so for
|
||
example add also:
|
||
|
||
@example
|
||
@group
|
||
(semantic-decoration-mode nil)
|
||
(semantic-idle-completions-mode nil)
|
||
(semantic-idle-tag-highlight-mode nil)
|
||
(semantic-idle-summary-mode nil)
|
||
(semantic-idle-scheduler-mode nil)
|
||
(senator-isearch-semantic-mode nil)
|
||
(senator-minor-mode nil)
|
||
(semantic-highlight-func-mode nil)
|
||
(semantic-stickyfunc-mode nil)
|
||
(semantic-show-parser-state-mode nil)
|
||
(semantic-show-unmatched-syntax-mode nil
|
||
(semantic-highlight-edits-mode nil
|
||
@end group
|
||
@end example
|
||
|
||
Normally this should not be necessary, because semantic is already prepared to
|
||
work perfectly with desktop.el. But if there are problems it's worth a try.
|
||
Which modes you have to add depends on which modes of semantic you use. But to
|
||
get sure you should add all minor-modes of the semantic-package because these
|
||
modes are normally activated by the related ``global'' command (e.g.
|
||
@code{global-semantic-show-unmatched-syntax-mode}) or by adding the minor-mode
|
||
to the related major-mode-hook.
|
||
|
||
It has also been reported that just disabling the Tip-Of-The-Day
|
||
(option: @code{ecb-tip-of-the-day}) fixes the compatibility-problems
|
||
with desktop.el. Just try it out!
|
||
|
||
@subsubsection Package edebug (Lisp Debugger)
|
||
|
||
@cindex edebug
|
||
It is strongly recommended to run edebug only when the ECB-windows are
|
||
hidden. With visible ECB-windows there will probably serious conflicts
|
||
between the ECB-layout and the edebug-window-manager.
|
||
|
||
@subsubsection Package ediff.el
|
||
|
||
@cindex ediff
|
||
In most cases ECB works very well with ediff (see option
|
||
@code{ecb-run-ediff-in-ecb-frame}). But currently suspending ediff
|
||
with @code{ediff-suspend} and restoring the ediff-session (e.g. with
|
||
command @code{eregistry}) does confuse the window-management of ECB.
|
||
|
||
If you often use ediff in a scenario where you suspend ediff and
|
||
reactivate it later then it is recommended to exit ECB first
|
||
(@code{ecb-deactivate} or @code{ecb-minor-mode})!
|
||
|
||
@subsubsection Package func-menu.el
|
||
|
||
@cindex func-menu package
|
||
This package has been reported to produce some conflicts under some
|
||
circumstances when ECB is activated. Some of them could be reproduced
|
||
by the ECB-maintainer. So the recommendation is to disable
|
||
func-menu-support when using ECB. Normally using func-menu makes no
|
||
sense in combination with ECB because ECB provides the same and even
|
||
more informations as func-menu - so func-menu is redundant ;-)
|
||
|
||
@subsubsection Package Gnus (Newsreader)
|
||
|
||
@cindex Gnus
|
||
As of ECB 2.21 there should be no conflicts between Gnus and ECB, so
|
||
Gnus can be used even when the ECB-windows are visible.
|
||
|
||
But if you encounter problems then it is recommened to use one of the
|
||
window-managers escreen.el or winring.el (@pxref{Window-managers and
|
||
ECB}). With such a window-manager ECB and Gnus should work together
|
||
very well under all circumstances!
|
||
|
||
@subsubsection Package JDEE (Java Development Environment)
|
||
|
||
@cindex JDEE
|
||
JDEE has a lot of ``dialogs'' where the user can select among several
|
||
choices. An example is importing classes via the command
|
||
@code{jde-import-find-and-import}. These dialogs are strongly designed
|
||
to work in an environment where a new temporary window is created, the
|
||
contents of the dialog are displayed in the new window, the user
|
||
select his choice and hits [OK]. After that the new window is deleted
|
||
and the selection is performed (for example the chosen import
|
||
statement are inserted in the source-buffer.
|
||
|
||
@strong{Caution}: ECB can work very well with this dialogs but only if
|
||
the buffer-name of these dialog-buffers (normally ``Dialog'') is not
|
||
contained in the option @code{ecb-compilation-buffer-names}. So do not
|
||
add the string ``Dialog'' to this option!
|
||
|
||
@strong{Please Note}: Regardless if a persistent compile-window is used
|
||
(i.e. @code{ecb-compile-window-height} is not nil) or not, these
|
||
JDEE-dialogs will always being displayed by splitting the edit-window
|
||
of ECB and not within the compile-window.
|
||
|
||
@subsubsection Package scroll-all.el (scroll-all-mode)
|
||
|
||
@cindex scroll-all-mode
|
||
@cindex scroll-all
|
||
ECB advices @code{scroll-all-mode} so it is working correct during
|
||
running ECB. This means if point stays in an edit-window and the
|
||
edit-window is splitted then all edit-windows are scrolled by
|
||
@code{scroll-all-mode} and no other window! If point stays in any
|
||
other window just this selected window is scrolled. This is the only
|
||
senseful behavior of @code{scroll-all-mode} with ECB.
|
||
|
||
@subsubsection Package VC (Version Control)
|
||
|
||
@cindex VC package
|
||
@cindex Version control
|
||
The variable @code{vc-delete-logbuf-window} must be set to nil during
|
||
active ECB. This can be done with the hooks mentioned in @ref{Elisp
|
||
programming}.
|
||
|
||
@subsubsection Package VM (Emacs Mail-Client)
|
||
|
||
@cindex VM package
|
||
As of ECB 2.21 there should be no conflicts between VM and ECB, so
|
||
VM can be used even when the ECB-windows are visible.
|
||
|
||
But if you encounter problems then it is recommened to use one of the
|
||
window-managers escreen.el or winring.el (@pxref{Window-managers and
|
||
ECB}). With such a window-manager ECB and VM should work together very
|
||
well under all circumstances!
|
||
|
||
|
||
@subsubsection Package winner.el (winner-mode)
|
||
|
||
@cindex winner-mode
|
||
@cindex winner
|
||
@code{winner-mode} is autom. disabled as long as ECB is running. ECB
|
||
has its own window-management which is completely incompatible with
|
||
@code{winner-mode}! But @code{winner-mode} makes also not really sense
|
||
with ECB.
|
||
|
||
@subsubsection Package wb-line-number.el
|
||
@cindex wb-line-number
|
||
|
||
Do not use the package wb-line-number.el in combination with ECB - it
|
||
will not work and it will not work under any circumstances and there
|
||
is no way to make it work together and there will be no way in the
|
||
future!
|
||
|
||
The reason behind that is: wb-line-number.el uses additional dedicated
|
||
windows to display the line-numbers. And ECB can not work if there
|
||
there are additional dedicated windows - additional to that ones
|
||
created by ECB.
|
||
|
||
@subsubsection Application xrefactory
|
||
|
||
@cindex xrefactory
|
||
Xrefactory (also known as Xref, X-ref and Xref-Speller), the
|
||
refactoring browser for (X)Emacs@footnote{Xrefactory is available at
|
||
@ifhtml
|
||
@uref{http://www.xref-tech.com}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://www.xref-tech.com}
|
||
@end ifnothtml
|
||
}, can be used during running ECB regardless if the ECB-windows are
|
||
visible or not. There should be no conflicts as of ECB versions >=
|
||
2.21.
|
||
|
||
If there are conflicts with the Xref-browser then the most recommended
|
||
way is to use one of the window-manager escreen.el or winring.el (and
|
||
then use different escreens or window-configurations for ECB and
|
||
Xrefactory-browsing - @ref{Window-managers and ECB}).
|
||
|
||
@subsection What to do for unknown conflicts with other packages
|
||
|
||
As of version 2.20 the layout-engine of ECB is so flexible that
|
||
normally there should be no conflicts with other packages unless these
|
||
packages have their own complete window-layout-management (e.g. Gnus,
|
||
BBDB, Xrefactory). But these packages can and should be handled very
|
||
well with the window-manager-support of ECB (@pxref{Window-managers
|
||
and ECB}).
|
||
|
||
So if you detect an unknown (i.e. not listed in the conflicts-list in
|
||
the next subsection) conflict with a small package and some of its
|
||
commands and you have installed an ECB-version < 2.20 the first task
|
||
you have to do is to upgrade to a version >= 2.20!
|
||
|
||
If this doesn't solve the problem a very probable reason for the
|
||
conflict is that the command fails if called from another window than
|
||
an edit-window of the ecb-frame. So please check if the problem
|
||
disappears if you call the failing command from an edit-window of ECB.
|
||
If this is true then you you can add the following code to your
|
||
.emacs (and of course replace the XXX with the failing command):
|
||
|
||
@example
|
||
@group
|
||
(defecb-advice XXX before ecb-compatibility-advices
|
||
"Ensures `XXX' works well when called from another window
|
||
as an edit-window. Does nothing if called in another frame
|
||
as the `ecb-frame'."
|
||
(when (equal (selected-frame) ecb-frame)
|
||
(unless (ecb-point-in-edit-window)
|
||
(ecb-select-edit-window))))
|
||
@end group
|
||
@end example
|
||
|
||
This before-advice runs before the command XXX and ensures that the
|
||
XXX is called from within an edit-window if the current selected
|
||
window is not an edit-window. It does nothing if called for another
|
||
frame as the ecb-frame.
|
||
|
||
@strong{Please note}: You have to define such compatibility advices exactly as
|
||
demonstrated in the example above, i.e. you must use the macro
|
||
@code{defecb-advice} and you have to use the advice-set
|
||
@code{ecb-compatibility-advices} (see the documentation of this macro)! The
|
||
advice-class is not necessary @code{before}, it can be @code{after} or
|
||
@code{around} too. Never use @code{defadvice} for ECB-advices!
|
||
|
||
If such an advice solves the problem then please send a note with the
|
||
solution to the ECB-mailing-list or direct to the ECB-maintainer so
|
||
the solution can be integrated in the next ECB-release
|
||
|
||
If calling from an edit-window fails too then please file a complete
|
||
bug-report to the ECB-mailing-list (@pxref{Submitting problem
|
||
report}). This report should contain a detailed description which
|
||
command of which package fails under which circumstances!
|
||
|
||
|
||
@node Bugs, , Conflicts, Conflicts and bugs
|
||
@section Known bugs
|
||
|
||
This section describes all currently known bugs of ECB. The
|
||
maintainers of ECB try to fix these bugs as soon as possible.
|
||
|
||
@subsection Extra history-entries for JDEE source-buffers
|
||
|
||
ECB on occasions creates an extra edit buffer for entries in the
|
||
history window. For example, let say there are three entries in the
|
||
history window:
|
||
|
||
@example
|
||
@group
|
||
Test1
|
||
Test2
|
||
Test3
|
||
@end group
|
||
@end example
|
||
|
||
In the edit window Test1 file is edited. When clicked on Test2 entry
|
||
in history, on occasion instead of switching to the existing buffer for
|
||
Test2, a new edit buffer is opened for Test2 file. At this point, there
|
||
are four entries in the history as follows:
|
||
|
||
@example
|
||
@group
|
||
Test2
|
||
Test2<2>
|
||
Test1
|
||
Test3
|
||
@end group
|
||
@end example
|
||
|
||
@node FAQ, Command Index, Conflicts and bugs, Top
|
||
@chapter Frequently asked questions
|
||
|
||
This is the Emacs Code Browser FAQ.
|
||
|
||
@c To produce prettier output we make a small empty column between the
|
||
@c question- and the answer-column. Therefore every Q/A-item must look
|
||
@c like:
|
||
@c
|
||
@c @c an empty line between every Q/A-item
|
||
@c @item @tab @tab
|
||
@c
|
||
@c @c The Q/A-item
|
||
@c @item
|
||
@c <The text of the question?>
|
||
@c @tab @tab
|
||
@c <The text of the answer>
|
||
|
||
@multitable @columnfractions 0.40 0.01 0.59
|
||
|
||
@item
|
||
@ifnotinfo
|
||
@strong{Question}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
QUESTION
|
||
@end ifinfo
|
||
@tab @tab
|
||
@ifnotinfo
|
||
@strong{Answer}
|
||
@end ifnotinfo
|
||
@ifinfo
|
||
ANSWER
|
||
@end ifinfo
|
||
|
||
@c an empty line between every Q/A-item
|
||
@item @tab @tab
|
||
|
||
@c The Q/A-item
|
||
@item
|
||
What is the first step i should do if i have problems with ECB?
|
||
@tab @tab
|
||
Read carefully the related sections of the online-help of ECB.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
What should i do, if a have a problem which can not be solved even
|
||
after reading the online-help?
|
||
@tab @tab
|
||
Send a problem-report to the ECB-mailing-list with the command
|
||
@code{ecb-submit-problem-report}.
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
See @ref{Submitting problem report}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
What should i do, if another package seems not to work correct with
|
||
ECB?
|
||
@tab @tab
|
||
Take a look into @ref{Conflicts}. If your package is not listed there
|
||
then submit a problem-report.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can ECB parse and display source-contents not supported by semantic?
|
||
@tab @tab
|
||
Yes, in all version >= 1.94. ECB can now parse and display all
|
||
source-contents supported by semantic, imenu or etags - same as
|
||
speedbar. See @ref{Non-semantic sources}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Why are the lines in the ECB-, temp- and compilation-buffers not
|
||
wrapped but truncated?
|
||
@tab @tab
|
||
Check the variable @code{truncate-partial-width-windows} and set it to
|
||
nil.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Why doesn't ECB work correct with VC?
|
||
@tab @tab
|
||
The variable @code{vc-delete-logbuf-window} must be set to nil during
|
||
active ECB. This can be done with the hooks of ECB.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Does ECB support C++ as well as Java?
|
||
@tab @tab
|
||
In general C++ is supported very well. But it depends on the used
|
||
cedet-version, but cedet-version >= 1.0pre6 support C++ really well.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Does ECB support Perl?
|
||
@tab @tab
|
||
If perl can be parsed either by imenu, etags or semantic then ECB
|
||
supports perl. Of course ECB would support perl best if perl is
|
||
supported by semantic.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Does ECB support language XYZ?
|
||
@tab @tab
|
||
See question ``Does ECB support Perl?'' and replace ``Perl'' with
|
||
``XYZ'' in the answer.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How to add new languages to ECB?
|
||
@tab @tab
|
||
Add the language XYZ to semantic (perform all necessary steps described in
|
||
the semantic-manual) and ECB will automatically support language XYZ!
|
||
There is nothing to do in ECB itself! Same when you write an imenu- or
|
||
etags-support for language XYZ.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Why does ECB not recognize my source-files for C++?
|
||
@tab @tab
|
||
Your C++-files have probably an extension which is not mapped to
|
||
c++-mode in @code{auto-mode-alist} and/or your own Emacs-setup has
|
||
``destroyed'' the correct value of the hook-variable
|
||
@code{c++-mode-hook}.
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
See @ref{Setting up Emacs}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Is it possible to make the history of ECB persistent?
|
||
@tab @tab
|
||
You can use the library ``desktop.el'' which works very well with ECB.
|
||
Then all files of your recent Emacs-session will be opened
|
||
automatically after next Emacs-start and will be added automatically
|
||
to the ECB-history after ECB-start.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Is there an ``Intellisense''-mechanism like with other IDEs?
|
||
@tab @tab
|
||
For Java the JDEE@footnote{
|
||
@ifhtml
|
||
@uref{http://jdee.sunsite.dk/}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://jdee.sunsite.dk/}
|
||
@end ifnothtml
|
||
} has this feature and for all other languages
|
||
semantic offer something similar, see
|
||
@ifhtml
|
||
@uref{http://cedet.sourceforge.net/intellisense.shtml}
|
||
@end ifhtml
|
||
@ifnothtml
|
||
@url{http://cedet.sourceforge.net/intellisense.shtml}
|
||
@end ifnothtml
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i use ECB in combination with Gnus within one frame?
|
||
@tab @tab
|
||
You can, but for ECB-versions < 1.96 it is not recommended because
|
||
each of them has it's own window-management and probably there will be
|
||
conflicts, so use different frames for ECB and Gnus! But beginning
|
||
with ECB 1.96 you can use either escreen.el or winring.el as
|
||
``window-manager'' which allows you in consequence to use ECB and
|
||
applications like Gnus in one frame!
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
@xref{Window-managers and ECB}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i speed up displaying the contents of big-size directories?
|
||
@tab @tab
|
||
Yes, see the option @code{ecb-cache-directory-contents}. Read the
|
||
section
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
@ref{Large directories}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Is it possible to create/use other layouts than the built-in ones?
|
||
@tab @tab
|
||
Yes. @ref{Creating a new ECB-layout} and
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
@ref{The layout-engine} are the relevant sections. The former one
|
||
describes how to create interactively new layouts where the latter
|
||
one is for Elisp-programmers.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i use speedbar as directory-browser within ECB?
|
||
@tab @tab
|
||
Yes, see @ref{Integrating speedbar}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i exclude subdirectories from the recursive grep in the directories buffer?
|
||
@tab @tab
|
||
Yes, see @ref{Grepping directories}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How can i prevent contaminating each directory with a file @file{semantic-cache}?
|
||
@tab @tab
|
||
Set @code{semanticdb-default-save-directory} to a directory.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Why ECB displays large portions of current source-file with dark background?
|
||
@tab @tab
|
||
This comes from semantic;
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
see @ref{Setting up Emacs}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Why ECB underlines some parts of current source-file?
|
||
@tab @tab
|
||
This comes from semantic;
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
see @ref{Setting up Emacs}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i add my own commands to the popup-menus of tree-buffers?
|
||
@tab @tab
|
||
Yes, see @ref{Using the mouse}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can ECB display the compile-window ``on demand''?
|
||
@tab @tab
|
||
Yes, see @ref{Common use-cases}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Which buffers are treated as compilation-buffers by ECB?
|
||
@tab @tab
|
||
See the docstring of the function @code{ecb-compilation-buffer-p}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How can i change the modeline of an ECB-tree-buffer?
|
||
@tab @tab
|
||
You can change it with the options @code{ecb-mode-line-prefixes},
|
||
@code{ecb-mode-line-data} and
|
||
@code{ecb-mode-line-display-window-number}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can the tree-buffers being selected faster than with the
|
||
standard-keybindings of ECB?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-mode-line-display-window-number}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can ECB display the window-number in the modeline of the special windows?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-mode-line-display-window-number}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How can i change the keybindings of ECB?
|
||
@tab @tab
|
||
You can do this with option @code{ecb-key-map} (@pxref{ecb-general}).
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
What can i do if hiding/showing from the methods-buffer does not work?
|
||
@tab @tab
|
||
Either the current @code{major-modes} is not supported by hideshow or
|
||
you have to add an entry to @code{hs-special-modes-alist}
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
(@pxref{Hide-show}).
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i maximize one of the ECB-windows for better overlook?
|
||
@tab @tab
|
||
Yes, see @ref{Maximizing the ECB windows}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i hide the ECB-windows for getting more editing-space?
|
||
@tab @tab
|
||
Yes, see @ref{Hiding the ECB windows}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i define the actions ECB performs after visiting a tag?
|
||
@tab @tab
|
||
Yes, see @ref{Visiting tags}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Buffers are not displayed correctly in the compile-window?
|
||
@tab @tab
|
||
See @ref{Problems with the compile window}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can ECB work together with window-managers like escreen.el?
|
||
@tab @tab
|
||
Yes, see @ref{Window-managers and ECB}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i remove these ``ugly'' vertical lines from a tree-buffer?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-tree-buffer-style}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
ECB does not display images in the tree-buffers - what can i do?
|
||
@tab @tab
|
||
Customize @code{ecb-tree-buffer-style} and restart ECB. But note: GNU
|
||
Emacs <= 21.3.X for Windows does not support image-display so ECB uses
|
||
always ascii-guide-lines even when here the image-style is set in
|
||
@code{ecb-tree-buffer-style}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Do @code{special-display-function} et. al. work with ECB.
|
||
@tab @tab
|
||
Yes, see
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
@ref{Using special-display with ECB}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i activate the popup-menu of a tree-buffer from keyboard?
|
||
@tab @tab
|
||
Yes, see @ref{Using popup-menus}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i display the popup-menu of a tree-buffer with tmm?
|
||
@tab @tab
|
||
Yes, see @ref{Using popup-menus}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Does ECB disable all advices after deactivation?
|
||
@tab @tab
|
||
``Nes''@footnote{Nes is a combination of No and Yes :-)}, see remarks
|
||
in the documentation of the option
|
||
@code{ecb-split-edit-window-after-start}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can ECB preserve the full state of ECB between deactivation and next
|
||
activation?
|
||
@tab @tab
|
||
Yes, see the option @code{ecb-split-edit-window-after-start}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i change the behavior how ECB chooses another window for selecting
|
||
it or scrolling it.
|
||
@tab @tab
|
||
Yes, see @ref{The other window}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i increase the allowed depth of nested submenus.
|
||
@tab @tab
|
||
Yes, see the docstring of the option
|
||
@code{ecb-directories-menu-user-extension}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i apply some filters to the Tree-buffers.
|
||
@tab @tab
|
||
Yes, see @ref{Filtering the tree-buffers}
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
With XEmacs i get sometimes an error ``Wrong number of arguments:
|
||
widen (1)''. What can i do?
|
||
@tab @tab
|
||
Disable the func-menu support in your XEmacs-setup. See
|
||
@ref{Conflicts}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i use desktop.el in combination with ECB?
|
||
@tab @tab
|
||
Yes, see @ref{Conflicts}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Opening directories takes a long time - what can i do?
|
||
@tab @tab
|
||
Read @ref{Large directories}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
ECB seems to be blocked sometimes - what is the reason?
|
||
@tab @tab
|
||
ECB performs some stealthy tasks when idle - this can cause sometimes
|
||
a blocked Emacs but this tasks will be immetiatelly interrupted by any
|
||
user-event so there should be normally no problems. But especially for
|
||
mounted net-drives some of the stealthy tasks can take time up to some
|
||
seconds for each file - and during one file-operation it can not be
|
||
interrupted. See also @code{ecb-stealthy-tasks-delay}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i exclude certain directories from being checked for emptyness?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-prescan-directories-exclude-regexps}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i exclude certain directories from checking the VC-state of the
|
||
contained sources?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-vc-directory-exclude-regexps}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
Can i exclude certain directories from checking the read-only-state of
|
||
the contained sources?
|
||
@tab @tab
|
||
Yes, see option @code{ecb-read-only-check-exclude-regexps}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
ECB ignores the remote-paths i have added to @code{ecb-source-path}.
|
||
@tab @tab
|
||
Maybe you have to check the option @code{ecb-ping-options}. Ensure
|
||
that this option contains a value suitable for your ping-program (see
|
||
@code{ecb-ping-program}).
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
See also @ref{Remote directories}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
ECB seems to be blocked a long time.
|
||
@tab @tab
|
||
Maybe you use cygwin-XEmacs. Then either the empty-dir-check (see
|
||
option @code{ecb-prescan-directories-for-emptyness}) or the VC-support
|
||
(see @code{ecb-vc-enable-support}) can block ECB.
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
For the latter one see @ref{Known VC-problems}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
ECB seems to be blocked during the VC-state update in the
|
||
tree-windows.
|
||
@tab @tab
|
||
Maybe the root repository for the current directory is a
|
||
remote-repository. This can result in a long lasting check-time per
|
||
file.
|
||
@ifinfo
|
||
@*
|
||
@end ifinfo
|
||
See also @ref{Version-control support} for hints what you can do.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
I have encountered some problems with the display of the VC-state in
|
||
the tree-buffers.
|
||
@tab @tab
|
||
See also @ref{Version-control support} for hints what you can do.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
The state of the files under version control seems to be not accurate. What is
|
||
the reason and what can i do?
|
||
@tab @tab
|
||
The option @code{ecb-vc-supported-backends} offers now also a accurate
|
||
recompute-state function. This is by offering @code{ecb-vc-recompute-state} as
|
||
an alias to the function @code{vc-recompute-state} as state-check function for
|
||
this option. See also @ref{Version-control support}
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
With Emacs 23 ECB shows a odd split-behavior when calling help or displaying
|
||
completion-output or compilation- or grep-output. What is the reason.
|
||
@tab @tab
|
||
Check the values of the options @code{split-width-threshold} and
|
||
@code{split-height-threshold}. ECBs split-behavior depends fully on the
|
||
Emacs-logic and that one depends mainly on these two options. So adjust them
|
||
to match (at least nearly) the sizes of the edit-area of ECB.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
When using a layout with the special ecb-window for the semantic analyzer then
|
||
Emacs seems to be blocked when typing pauses. What is the reason and what can
|
||
i do?
|
||
@tab @tab
|
||
This comes from the idle-mechanism ECB/semantic uses to offer some
|
||
intellisense like displaying possible completions and local variables
|
||
depending on current context (ie. location of point). So if point stays on a
|
||
location within your code where hundreds (or even thousands) of completions
|
||
are possible then parsing and displaying them can last annoying time. But in
|
||
general a keypress interupts. If not then you have to possibilities offered by
|
||
the options @code{ecb-analyse-buffer-sync} and
|
||
@code{ecb-analyse-buffer-sync-delay}: You can increase the delay of the latter
|
||
one so parsing current context starts later after Emacs goes idle (ie. after
|
||
you pause typing). Or you can disable the automatic synchronizing the
|
||
analyser-window with the former one - see the docstring. Then you have to
|
||
synchronize (ie. start parsing context) on demand via the command
|
||
@code{ecb-analyse-buffer-sync}@footnote{Yes, both the option and the command
|
||
have the same name}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How can i change the bucketizing method of the history-window?
|
||
@tab @tab
|
||
Either via popup context-menu (right mouse-button) or with the option
|
||
@code{ecb-history-make-buckets}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
How can i disable this grey headerline in the tree-buffers?
|
||
@tab @tab
|
||
See the option @code{ecb-tree-make-parent-node-sticky}.
|
||
|
||
@item @tab @tab
|
||
|
||
@item
|
||
When clicking onto a parent-node in the methods-window then ECB doesn't jump
|
||
to the definition of this parent-type.
|
||
@tab @tab
|
||
ECB uses completely the smartness of the semanticdb and the semantic-analyzer.
|
||
So if you have customized semantic accordingly to the needs of your project
|
||
(ie. mainly setting up all so semantic can find files in your
|
||
directory-structure) then ECB will find the parent-definition and also jump to
|
||
it. See @ref{ECB Methods-window} and the subsection ``Jumping to the
|
||
definition of external tags'' and see the option
|
||
@code{ecb-find-external-tag-functions}.
|
||
|
||
@end multitable
|
||
|
||
@node Command Index, Option Index, FAQ, Top
|
||
@unnumbered Command Index
|
||
|
||
@noindent
|
||
This index contains all user commands of ECB.
|
||
|
||
@strong{Please note}: The commands in this index are listed without
|
||
the prefix ``ecb-'' (e.g. the command @code{ecb-activate} is listed
|
||
with name ``activate'').
|
||
|
||
@printindex fn
|
||
|
||
@node Option Index, Concept Index, Command Index, Top
|
||
@unnumbered Option Index
|
||
|
||
@noindent
|
||
This index contains all customizable options of ECB.
|
||
|
||
@strong{Please note}: All options in this index are listed without the
|
||
prefix ``ecb-'' (e.g. the option @code{ecb-layout-name} is listed with
|
||
name ``layout-name'').
|
||
|
||
@printindex vr
|
||
|
||
@node Concept Index, , Option Index, Top
|
||
@unnumbered Concept Index
|
||
|
||
@printindex cp
|
||
|
||
@contents
|
||
|
||
|
||
@bye
|
||
|
||
@c LocalWords: texinfo Berndl java ECB ecb texi berndl Exp setfilename vr cp
|
||
@c LocalWords: settitle syncodeindex fn ifinfo paragraphindent exampleindent
|
||
@c LocalWords: footnotestyle frobbed ecbver dircategory direntry titlepage sp
|
||
@c LocalWords: titlefont vskip pt Jesper Nordenberg dir ifnottex Elisp imenu
|
||
@c LocalWords: etags perl iftex ref tex url ifhtml uref detailmenu eshell API
|
||
@c LocalWords: keybindings speedbar Grepping JDEE website eieio xref subdirs
|
||
@c LocalWords: loadtime autoloads Bytecompiling bytecompile EMACSINFOPATH hxx
|
||
@c LocalWords: pxref alist multitable columnfractions ifnotinfo hh HH cxx cpp
|
||
@c LocalWords: CC jde setq RET kbd Alt minibuffer cindex dfn grep ascii popup
|
||
@c LocalWords: screenshot splitted sourcecode noindent de itemx rsp CTRL hor
|
||
@c LocalWords: senseful modeline subnode uml const gm Ctrl docstring autom lc
|
||
@c LocalWords: subsubsection fontify defun asis Hist leftright lr nav dired
|
||
@c LocalWords: deffn var CLEARALL cedet sourcepath classpath arg html regexp
|
||
@c LocalWords: backtrace def incl defopt cdr keysequence SPC DEL LFD ESC NUL
|
||
@c LocalWords: alt abc horiz filenumber rexexp bigdir iff cvsignore lib ini
|
||
@c LocalWords: elc obj dll rexexps assoc taglist bovinate toplevel oo CLOS
|
||
@c LocalWords: defclass colorized XYZ XYC structs colorizing struct enum adv
|
||
@c LocalWords: func comint proc min subdir wget gzip cygwin ifnothtml env iso
|
||
@c LocalWords: http defcustom upgradable defconst lw doc ls grepping tempor
|
||
@c LocalWords: igrep CVS gen maxout FF hs hideshow JDEbug defmac ver undefine
|
||
@c LocalWords: Bufferinfo rw bufferinfo readonly filebuffer filebuffers pos
|
||
@c LocalWords: cond buf preactivation usw msw lsw asynch XP Newsreader BBDB
|
||
@c LocalWords: VC vc logbuf BNF Intellisense IDEs semanticdb printindex
|