1 \input texinfo @c -*-texinfo-*-
2 @documentencoding ISO-8859-1
4 @c Copyright (C) 2000 - 2003 Jesper Nordenberg,
7 @c Free Software Foundation, Inc.
9 @c Author: Jesper Nordenberg <mayhem@home.se>
10 @c Klaus Berndl <klaus.berndl@sdm.de>
11 @c Kevin A. Burton <burton@openprivacy.org>
12 @c Maintainer: Klaus Berndl <klaus.berndl@sdm.de>
13 @c Kevin A. Burton <burton@openprivacy.org>
14 @c Keywords: browser, code, programming, tools
17 @c This program is free software; you can redistribute it and/or modify it under
18 @c the terms of the GNU General Public License as published by the Free Software
19 @c Foundation; either version 2, or (at your option) any later version.
21 @c This program is distributed in the hope that it will be useful, but WITHOUT
22 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
23 @c FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
26 @c You should have received a copy of the GNU General Public License along with
27 @c GNU Emacs; see the file COPYING. If not, write to the Free Software
28 @c Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
30 @c $Id: ecb.texi,v 1.20 2004-12-10 16:34:14 berndl Exp $
34 @settitle ECB - the Emacs Code Browser
36 @c If we want only one index for concepts, functions and variables
37 @c @syncodeindex vr cp
38 @c @syncodeindex fn cp
40 @c in info we do not want paragraph indenting
49 @c The version number is auto-frobbed from the Makefile, so you should
50 @c edit the Makefile to change the version number. mechanism stolen
57 @dircategory GNU Emacs Lisp
59 * ECB: (ecb). Emacs Code Browser
64 @center @titlefont{ECB version @ecbver{} - User manual}
65 @vskip 0pt plus 1 fill
66 Copyright @copyright{} 2000, 2001, 2002 Jesper Nordenberg, Klaus Berndl
69 @node Top, Install and first steps, (dir), (dir)
70 @comment node-name, next, previous, up
73 This is the user manual for ECB version @ecbver{}.
76 ECB stands for "Emacs Code Browser". While (X)Emacs already has good
77 @strong{editing} support for many modes, its @strong{browsing} support
78 is somewhat lacking. That's where ECB comes in: it displays a number
79 of informational windows that allow for easy source code navigation
82 The informational windows can contain:
85 @item A directory tree,
86 @item a list of source files in the current directory,
87 @item a list of functions/classes/methods/... in the current file,
88 (ECB uses the Semantic Bovinator, or Imenu, or etags, for getting this
89 list so all languages supported by any of these tools are
90 automatically supported by ECB too)
91 @item a history of recently visited files,
92 @item the Speedbar and
93 @item output from compilation (the "*compilation*" window) and other
94 modes like help, grep etc. or whatever a user defines to be displayed
98 As an added bonus, ECB makes sure to keep these informational windows
99 visible, even when you use @kbd{C-x 1} and similar commands.
101 It goes without saying that you can configure the layout, ie which
102 informational windows should be displayed where. ECB comes with a
103 number of ready-made window layouts to choose from.
109 @strong{Please note}: Experienced ECB users find a complete
110 alphabetical list of all commands and user-options in @ref{Interactive
111 ECB commands} and @ref{Customizable options}.
113 @c In the following two paragraphs we distinct between HTML-, info-,
114 @c and tex-format concerning the display of the URLs.
116 The latest version of ECB can always be found at the URL
117 @url{http://ecb.sourceforge.net}.
119 To send bug reports, or participate in discussions about ECB, use the
120 mailing list @email{ecb-list@@lists.sourceforge.net} via the URL
121 @url{http://lists.sourceforge.net/lists/listinfo/ecb-list}.
128 The latest version of ECB can always be found at the URL @*
129 @url{http://ecb.sourceforge.net}.
133 To send bug reports, or participate in discussions about ECB, use the
134 mailing list @*@email{ecb-list@@lists.sourceforge.net} via the URL @*
135 @url{http://lists.sourceforge.net/lists/listinfo/ecb-list}.
139 The latest version of ECB can always be found at
140 @uref{http://ecb.sourceforge.net}
142 To send bug reports, or participate in discussions about ECB, use the
143 mailing list @email{ecb-list@@lists.sourceforge.net} via
144 @uref{http://lists.sourceforge.net/lists/listinfo/ecb-list}
147 @strong{IMPORTANT}: Cause of extra appearance of SPAM in the
148 mailing-lists, SourceForge has changed its policy: Now it is only
149 possible to post to the mailing-list for users who have subscribed
150 this mailing-list. So please be aware you will not be able to send
151 comments, bug reports and improvement suggestions before you have
152 subscribed the ECB-mailing-list. See the section "Mailing-list" at the
155 @uref{http://ecb.sourceforge.net}
158 @url{http://ecb.sourceforge.net}
163 * Install and first steps:: Installing ECB and first steps
164 * Overview:: Introduce basic concepts
165 * Activation and Deactivation:: How to start and end ECB
166 * Usage of ECB:: How to use ECB
167 * Customizing:: How to customize ECB
168 * Submitting problem report:: What to do when problems occur
169 * Upgrading:: Upgrading and downloading packages
170 * Tips and tricks:: Useful hints and tips
171 * Elisp programming:: Entry points for Elisp programmers
172 * Conflicts and bugs:: Known Conflicts with other packages and bugs
173 * FAQ:: Frequently asked questions
174 * Command Index:: Index for interactive commands
175 * Option Index:: Index for user options
176 * Concept Index:: Index for concepts and terms
180 --- The Detailed Node Listing ---
182 Installation and first steps of ECB
184 * Installation:: Installation of ECB
185 * Setting up Emacs:: How to set up Emacs for file parsing with ECB
186 * First steps:: First steps after activating ECB first time
190 * XEmacs Installation:: Installation of ECB for XEmacs users
191 * GNU Emacs Installation:: Installation of ECB for GNU Emacs users
193 How to set up Emacs for file parsing with ECB
195 * General hints:: General hints for a correct setup
196 * Setting up semantic:: How to setup semantic correctly
197 * Non-semantic files:: Setup for file types not supported by semantic
201 * ECB Directories-buffer:: Contents of the ECB Directories-buffer
202 * ECB Sources-buffer:: Contents of the ECB Sources/history-buffer
203 * ECB Methods-buffer:: Contents of the ECB Methods-buffer
205 Activation and Deactivation
207 * Standard activation:: How to manually (de)activate ECB
208 * Automatic activation:: Automatically (de)activating ECB
212 * Using the mouse:: Working with the mouse
213 * Using the keyboard:: Working with the keyboard
214 * The edit-area:: How to use the edit-area
215 * Temp- and compile-buffers:: Displaying temp- and compilation-buffers
216 * The other window:: How the ``other window'' is determined
217 * The Methods buffer:: Using and customizing the Methods-buffer
218 * Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers
219 * The ECB-layout:: Changing, customizing, redrawing, creating
220 * Hiding the ECB windows:: Hiding/Showing the ECB-windows
221 * Maximizing the ECB windows:: Maximizing the ECB-windows
222 * Back/forward navigation:: Back- and forward navigation like a browser
223 * ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows
224 * Stealthy background tasks:: Stealthy background-tasks of ECB
225 * Interactive ECB commands:: All interactive user-commands of ECB
227 Working with the keyboard in the ECB-windows
229 * Navigation/Selection:: Keyboard navigation/selection in a tree-buffer
230 * Incremental search:: Find nodes as fast as possible
231 * Personal keybindings:: Adding personal keybindings to a tree-buffer
232 * Using popup-menus:: Using the popup-menus from keyboard.
234 Using and customizing the ECB-Methods buffer
236 * Visiting tags:: Possible actions after visiting a tag
237 * Expanding:: Explicit and automatic expanding
238 * Customizing the display:: How to customize the Methods-buffer display
239 * Rebuilding the Methods:: When to rebuild the Methods-buffer
241 Applying filters to the special ECB-tree-buffers
243 * Filtering Directories:: Applying filters to the Directories-buffer
244 * Filtering Sources:: Applying filters to the Sources--buffer
245 * Filtering History:: Applying filters to the History-buffer
246 * Filtering Methods:: Applying filters to the Methods-buffer
248 Changing, customizing, redrawing and creating layouts
250 * Changing the ECB-layout:: How to change and customize the layout
251 * Redrawing the ECB-layout:: How and when redrawing the layout
252 * Changing window sizes:: Changing sizes of the ECB-windows
253 * Fixing window sizes:: Fixing sizes of the ECB-windows
254 * Creating a new ECB-layout:: Interactively creating new layouts
258 * General aspects:: General aspects for customizing ECB
259 * Most important options:: Which option you must know
260 * Customizable options:: All customizable options of ECB
262 General aspects for customizing ECB
264 * setq or customize:: Should i use setq or customize?
265 * Site-wide customizing:: Site-wide customizing of ECB
267 All customizable options of ECB
269 * ecb-general:: General customizing ECB
270 * ecb-tree-buffer:: Customizing the general tree layout
271 * ecb-directories:: Customizing the ECB-directories-tree
272 * ecb-sources:: Customizing the ECB-sources-tree
273 * ecb-methods:: Customizing the ECB-methods-tree
274 * ecb-history:: Customizing the ECB-history-tree
275 * ecb-layout:: Customizing the ECB-layout
276 * ecb-compilation:: Customizing the compile-window
277 * ecb-create-layout:: Customizing options for creating layouts
278 * ecb-face-options:: Customizing options for faces
279 * ecb-faces:: Customizing the faces
280 * ecb-download:: Customizing how to download ECB
281 * ecb-help:: Customizing the online help of ECB
282 * ecb-eshell:: Customizing the eshell-integration
283 * ecb-speedbar:: Customizing the speedbar-integration
284 * ecb-non-semantic:: Customizing parsing non-semantic sources
285 * ecb-winman:: Customizing window-manager support
286 * ecb-mode-line:: Customizing the tree-buffer-modelines
287 * ecb-version-control:: Customizing the version-control-support
289 Upgrading and downloading packages
291 * Downloading new versions:: How to download newer versions of packages
292 * Auto. option-upgrading:: ECB can auto. upgrade your options
294 Automatic upgrading of options
296 * User interface:: Options and commands you should know
297 * Background information:: Maybe some interesting informations
301 * Changing faces:: Changing faces in the ECB tree-buffers
302 * Small screens:: Working with small screens
303 * Big screens:: Working with big screens
304 * Simulating speedbar:: Simulating speedbar without an extra frame
305 * Integrating speedbar:: Integrating speedbar in the ECB-frame
306 * Optimize scrolling:: Optimize scrolling in the edit-window
307 * Large directories:: Working with large directories
308 * Remote directories:: Working with remote directories
309 * Version-control support:: Supporting Version control systems
310 * Using eshell:: Optimal using of eshell in ECB
311 * Grepping directories:: Grepping directories with ECB
312 * Working with JDEE:: Working best with ECB and JDEE
313 * Compile-window on demand:: Displaying the compile-window on demand
314 * Non-semantic sources:: Parsing and displaying non-semantic sources
315 * Hide-show:: Using hide-show from the methods-buffer-menu
316 * Window-managers and ECB:: Support of several Emacs-window-managers
317 * Tree-buffer styles:: Displaying the trees with different styles
318 * Using semanticdb:: Using semanticdb for going to external nodes
320 Supporting Version control systems
322 * Identifying backends:: How ECB identifies the VC-backend of a dir
323 * Checking the state:: How ECB checks the VC-state of a file
324 * Remote repositories:: What you should now about this
325 * Refreshing the VC-state:: How to refresh when state changed outside
326 * Adding new backends:: Necessary steps for adding new backends
327 * Known VC-problems:: Currently known problems of the VC-support
329 Displaying the trees of the ECB-windows with different styles
331 * Style basics:: Basic knowledge about the styles
332 * Ascii-based styles:: How to customize the ascii-styles
333 * Tree-buffers with images:: Which images are used for the tree
334 * Images for Methods-buffer:: Images for the tags in the Methods-buffer
336 Entry points for Elisp programmers
338 * List of variables:: Which variables an Elisp-program can use
339 * List of hooks:: All available hooks
340 * tree-buffer:: Some words to the tree-buffer-library
341 * Adviced functions:: How to deal with the adviced functions
342 * The layout-engine:: Programming new layouts and special windows
344 How to program new layouts and new special windows
346 * Programming a new layout:: How to program a new layout
347 * Programming special windows:: Aspects of programming special windows
348 * Possible layout-outlines:: The wide range of possible layouts
349 * The layout-engine API:: The complete layout-engine API
351 Conflicts and bugs of ECB
353 * Conflicts:: Conflicts with other packages
359 @node Install and first steps, Overview, Top, Top
360 @chapter Installation and first steps of ECB
362 This chapter describes how to install ECB and setup (X)Emacs correctly
363 and what are the first steps after activation of ECB.
366 * Installation:: Installation of ECB
367 * Setting up Emacs:: How to set up Emacs for file parsing with ECB
368 * First steps:: First steps after activating ECB first time
371 @node Installation, Setting up Emacs, Install and first steps, Install and first steps
372 @section Installation of ECB
374 This section describes how to install ECB.
377 * XEmacs Installation:: Installation of ECB for XEmacs users
378 * GNU Emacs Installation:: Installation of ECB for GNU Emacs users
381 @node XEmacs Installation, GNU Emacs Installation, Installation, Installation
382 @subsection Installation of ECB for XEmacs users
384 For XEmacs-users it is strongly recommended to use the
385 package-management-system of XEmacs for first-time
386 downloading/installing ECB or for upgrading to a newer version of ECB.
387 Here is a short guide (for details about the package-manager of XEmacs
388 see the related info-manual):
390 @strong{Caution}: If ECB is already installed and you just want
391 upgrading to a newer version then it is recommended to deactivate ECB
392 before proceeding with the steps below!
395 @item Choose a download-site
397 This can be done via the menu ``Tools --> Packages --> Add Download
398 Site'': Choose one of the listed sites. Or you can customize the
399 option @code{package-get-remote} by hand and save it for future
402 @item Activate the packages list
404 This can be done either by the menu ``Tools --> Packages --> List and
405 Install'' or via the command @code{pui-list-packages}. After that a
406 special packages-buffer is displayed where you can interactively
407 install or upgrade packages. At the end of this buffer there is a
408 short description how to use this buffer.
410 @item Install ECB and all required packages
412 Mark the package named ``ecb'' for install. Do this also for the
413 required packages ``semantic'', ``eieio'' and ``speedbar''. The
414 package ``mail-lib'' is needed for easy submitting of problem-reports
415 to the ECB-maintainers and the package ``c-support'' is needed for
416 easy using hideshow within the Methods-buffer of ECB@footnote{All
417 required packages can simply autom. marked by hitting @kbd{r} in the
418 packages buffer. But this installs a lot of packages more (e.g. the
419 Newsreader Gnus) which are really not essential for ECB. Therefore it
420 is recommended to mark the required packages by hand.}.
422 After marking all needed packages for installation hit @kbd{x} to
425 If you have already installed ECB and you want just upgrading to the
426 latest available version then proceed as described above - same if you
427 want to upgrade one of the required packages.
431 Now you can immediately start ECB via the command @code{ecb-activate};
432 there is no need to restart XEmacs! As an alternative you can first
433 read the online-help via @code{ecb-show-help}.
437 If you do not like the package-manager of XEmacs but you want
438 installing ECB ``by hand'' direct from the ECB-website then you have
439 to follow the instructions for GNU Emacs, see @ref{GNU Emacs Installation}.
441 @node GNU Emacs Installation, , XEmacs Installation, Installation
442 @subsection Installation of ECB for GNU Emacs users
444 @strong{IMPORTANT}: If you are a XEmacs-user please read @ref{XEmacs
445 Installation} before proceeding with the following instructions!
447 @c TODO: Klaus Berndl <klaus.berndl@sdm.de>: Remove this when we
448 @c support upgrading also with cedet.
450 @strong{Using the new cedet 1.0 suite}: From beginning with version
451 2.01 ECB supports the next generation of the cedet-tools. But before
452 the cedet 1.0 suite becomes stable this means that ECB runs correctly
453 with loaded cedet 1.0 but the ECB-upgrading feature
454 (@pxref{Downloading new versions}) does not support autom. upgrading
455 to latest available cedet versions. This will be first available after
456 first stable release of the new cedet-library 1.0.
458 So, if the cedet 1.0 suite is loaded then the min- and max-version of
459 semantic, eieio and speedbar (mentioned in the Requirements-section of
460 the file @file{README}) have no relevance! If the new cedet 1.0 suite
461 should be used then just install and load cedet 1.0 like described in
462 the cedet-installation-instructions and go one with step 3.
467 Download and unpack the ECB archive (probably you have already done
471 Read the file @file{README} in the ECB-directory and install the
472 required semantic-, eieio- and speedbar-version@footnote{The
473 speedbar-version shipped with GNU Emacs <= 21.3 does not satisfy the
474 requirements for this feature - download a newer one!}.
476 @strong{Please note}: ECB maybe requires a newer version of these
477 libraries than shipped with (X)Emacs. You have to install exactly a
478 version ECB requires and also to make sure that the correct version is
479 loaded into (X)Emacs!
481 But ECB performs two autom checks:
485 It checks if the packages semantic, eieio and speedbar are at least
486 installed so ECB can be loaded. If not it offers to download and
490 It checks if the correct versions of semantic, eieio and speedbar are
491 installed and gives you proper feedback. @xref{Download required
495 So if you are not sure if you have installed the required packages at
496 all or if you have installed the correct versions of these packages
497 then do not worry about this, just go on with the following
498 installation steps: If ECB is missing something it will give you
499 proper feedback and support not later than at load-time or start-time!
502 Add the new ECB-directory to your @code{load-path} variable.
504 You @strong{MUST} add the ECB-install-directory to the
505 @code{load-path} either by changing the @code{load-path} variable
506 directly in your @file{.emacs} or @file{site-lisp/site-start.el} or by
507 working with a file @file{subdirs.el}@footnote{This works at least for
508 Emacs 20.X and Emacs 21.X but XEmacs may have slightly different
509 mechanisms; see the XEmacs documentation}.
511 So for example the needed entry for your @file{.emacs}-file could be:
514 (add-to-list 'load-path
515 "/path/to/your/ecb/installation/directory")
519 ECB is NOT properly installed if it's directory is not added to
520 @code{load-path} and for example just loaded by
523 (load-file "/path/to/ecb/ecb.el")
529 Load ECB by adding code to your @file{.emacs}:
531 If you want to load the complete ECB at (X)Emacs-loadtime (Advantage:
532 All ECB-options available after loading ECB. Disadvantage: Increasing
533 loadtime@footnote{Cause of full loading of ECB itself and also the
534 packages semantic, eieio and speedbar regardless if ECB is started.}):
540 If you want to load the ECB first after starting it by
541 @code{ecb-activate} (Advantage: Fast loading@footnote{ECB, semantic,
542 eieio and speedbar are first loaded after starting ECB or with other
543 words: ECB and semantic are not loaded if you do not use/need them}.
544 Disadvantage: ECB- and semantic-options first available after starting
548 (require 'ecb-autoloads)
551 This loads all available autoloads of ECB, e.g. @code{ecb-activate},
552 @code{ecb-minor-mode}, @code{ecb-byte-compile} and
553 @code{ecb-show-help}.
555 Regardless which method you prefer: In both cases the used statement
556 must be placed @strong{after} the statement of step 3!
559 @item Restart (X)Emacs.
562 ECB is now ready for use and can be activated by calling @code{M-x
563 ecb-activate} or @code{ecb-minor-mode}. Now you can either starting
564 using ECB or you can do these optional installation steps:
568 @item Reading the online help with @code{ecb-show-help}
570 Maybe you are interested to read the online-help of ECB before first
573 @item Bytecompiling ECB with @code{ecb-byte-compile}
575 This byte compiles ECB. You can safely ignore all messages if there
576 are any. (You can also bytecompile ECB from the command-line either by
577 using the @file{Makefile} or by using the batch-file @file{make.bat};
578 just read the comments in that file you choose.)
580 @item Installing the Info-help of ECB
582 The ECB distribution contains a subdirectory @file{info-help} which
583 contains the online-help of ECB in Info-format. You can install this
584 online help so it's available in the Top-directory of Info. There are
588 @item Use ``install-info'' (recommended):
592 Copy the files of the subdirectory @file{info-help} into the
593 info-directory of Emacs
596 Install the file @file{info-help/ecb.info} with the command
597 ``install-info'' (if available on your system) in the @file{dir}-file.
600 The supplied @file{Makefile} offers a target @code{install-help} which
601 does both of these steps. You have just to call @code{make
602 install-help} with the correct EMACSINFOPATH set (see the comment in
603 @file{Makefile}). Here is an example:
606 make EMACSINFOPATH=/path/to/emacs/info install-help
609 @item Manual Installation:
611 Copy the files of the subdirectory @file{info-help} into the
612 info-directory of Emacs and modify the file @file{dir} manually.
615 But it doesn't matter if you do not execute this step (8.) because the
616 online help of ECB is always available though, see
617 @code{ecb-show-help} (@pxref{Interactive ECB commands}).
621 @node Setting up Emacs, First steps, Installation, Install and first steps
622 @section How to set up Emacs for file parsing with ECB
624 @strong{Please note}: Normally it should not necessary for you to
625 bother with the following stuff unless you have problems getting ECB
626 working correctly for you.
629 * General hints:: General hints for a correct setup
630 * Setting up semantic:: How to setup semantic correctly
631 * Non-semantic files:: Setup for file types not supported by semantic
634 @node General hints, Setting up semantic, Setting up Emacs, Setting up Emacs
635 @subsection General hints for a correct setup
637 ECB is for browsing files and therefore you have to setup your
638 Emacs-configuration properly so the file-parsing engines like
639 semantic, imenu or etags can be activated automatically for parsing
640 your Emacs-Lisp, C, C++ or Java buffers@footnote{semantic supports
641 some more ``languages'' like Makefiles etc. but these are the most
642 important ones.}. For this Emacs must activate the correct
643 @code{major-mode} for the source-files and Emacs can only do this if
644 the option @code{auto-mode-alist} is setup correctly. The correct
645 major-modes and possible file-extensions@footnote{Especially for C++
646 and C you can use any extension you want but these are the most common
649 @multitable @columnfractions 0.20 0.50 0.30
667 @strong{Extension(s)}
673 @item Emacs Lisp @tab @code{emacs-lisp-mode} @tab .el
675 @item C @tab @code{c-mode} @tab .h, .c
677 @item C++ @tab @code{c++-mode} @tab .h, .hxx, .hh, .HH, .cxx, .cpp,
680 @item Java @tab @code{java-mode} or @code{jde-mode} (if you use JDEE)
684 Example: If you want files with extension ``.cpp'' being c++-parsed by
685 semantic and ECB, your @code{auto-mode-alist} must contain an entry
689 ("\\.cpp\\'" . c++-mode)
692 After this ECB will correctly parse your ``.cpp''-sources and display
693 all the parsing information in the ECB-methods buffer.
695 @node Setting up semantic, Non-semantic files, General hints, Setting up Emacs
696 @subsection Setting up semantic
698 To ensure ECB and semantic are working correctly for all by semantic
699 supported languages you have to pay attention to the following aspects
700 concerning your Emacs-setup:
703 @item Setting up semantic itself
705 For all semantic-supported file-types parsing files is done completely
706 by semantic. ECB just displays the parsing results. For all needs of
707 ECB semantic is completely setup by ECB itself, i.e. ECB sets up
708 semantic for you! You have only to add the installation directory of
709 semantic to your @code{load-path} (in an appropriate way)!
711 @strong{Please note}: If you setup semantic for yourself following the
712 recommendations in the installation instructions of semantic then you
713 have probably added code to your startup-file like:
716 (setq semantic-load-turn-everything-on t)
717 (require 'semantic-load)
720 Be aware that this also enables the minor-modes
721 @code{semantic-show-dirty-mode} and
722 @code{semantic-show-unmatched-syntax-mode} where the former one
723 highlights all code which has to be reparsed with dark background
724 (which results in large portions of dark background ;-) and the latter
725 one underlines all syntax which can not be parsed. Especially the
726 former one can be really annoying.
728 To switch off these modes you can add to your startup-file:
731 (global-semantic-show-dirty-mode -1)
732 (global-semantic-show-unmatched-syntax-mode -1)
735 @anchor{Checking your hooks}
736 @item Checking your hooks
738 If you have already checked point (1.) and if you have still problems
739 getting ECB/semantic working properly for your sources you should
740 check the related major-mode hook. Every major-mode X has a hook with
741 name ``X-hook'' which is evaluated after activating the major-mode
742 (see above, 2.), e.g. the hook for the major-mode @code{c++-mode} is
743 @code{c++-mode-hook}.
745 Semantic adds automatically during load-time a special
746 ``semantic-setup'' to these major-mode hooks@footnote{Of course only
747 for major-modes supported by semantic!} in form of a
748 ``setup-function''. Example: For c and c++ modes semantic adds
749 @code{semantic-default-c-setup} to @code{c-mode-hook} and
750 @code{c++-mode-hook}.
752 If your own Emacs-setup (e.g. in @file{.emacs} or
753 @file{site-lisp/site-start.el}) overwrites such a major-mode-hook then
754 semantic can not be activated for this major-mode and in consequence
755 ECB can not work properly too!
757 Check if your Emacs-setup uses somewhere @code{setq} for adding code
758 to a major-mode-hook. @strong{IMPORTANT}: Use @code{add-hook} instead of
759 @code{setq}@footnote{@code{setq} replaces/overwrites the current
760 value of a hook with the new value whereas @code{add-hook}
761 @strong{adds} the new value to the old-value of the hook!}!
765 If your source-files are ``running'' with correct @code{major-mode}
766 and correct major-mode hooks ECB and semantic will do what you expect
769 @node Non-semantic files, , Setting up semantic, Setting up Emacs
770 @subsection Setup for file types not supported by semantic
772 From version 1.94 on ECB supports also parsing and displaying
773 file-contents for file-types not supported by semantic (i.e. there is
774 no semantic-grammar available for such file-types).
776 Such non-semantic file-types can often be parsed by imenu and/or
777 etags. Both of these parsing methods are now supported: ECB can
778 display the results of imenu and/or etags in its Method-buffer. ECB
779 uses for this speedbar-logic. Therefore the following speedbar options
780 takes effect for this feature:
783 @item @code{speedbar-dynamic-tags-function-list}
784 @item @code{speedbar-tag-split-minimum-length}
785 @item @code{speedbar-tag-regroup-maximum-length}
786 @item @code{speedbar-tag-hierarchy-method}
789 Normally there should no need for you to bother with these options,
790 because the default values are suitable for most situations! But if
791 you are not satisfied with the parsing/display results then you can
792 change some of these options.
794 @node First steps, , Setting up Emacs, Install and first steps
795 @section First steps after activating ECB first time
797 This section of the ECB online-help is displayed automatically by ECB
798 after activating ECB first time and describes what are the first basic
803 @item Configure where ECB can find your sources:
805 Call @code{M-x customize-option RET ecb-source-path RET}@footnote{This
806 means first hitting the keys @kbd{M} (Meta- or Alt-key) and @kbd{x}
807 simultaneously, inserting ``customize-option'' in the minibuffer,
808 hitting RETURN, inserting ``ecb-source-path'' in the minibuffer and
809 finally hitting RETURN again}. This lets you customize the option
810 @code{ecb-source-path} with the customize-feature of Emacs. This opens
811 a customize-buffer where you can insert all the directories where ECB
812 can find your source-files. Save your changes with the button ``Save
813 for future sessions'' and then throw away this customize-buffer either
814 by killing it with @code{M-x kill-buffer} or clicking at the button
817 @item Take a look at the most important options of ECB
818 Call @code{M-x ecb-customize-most-important RET} and see a list of
819 options which you should at least know that these options exist.
821 @item Read the online-help of ECB:
823 The online-help of ECB is available via
826 @item calling @code{M-x ecb-show-help},
827 @item pressing @kbd{C-c . o} or
828 @item using the menu ``ECB''.
831 (The section you are currently reading is part of the online-help of
834 Here is also the chapter ``Tips and tricks'' very interesting!
836 @item Start working with ECB.
839 @node Overview, Activation and Deactivation , Install and first steps, Top
844 ECB is a global minor-mode which offers a couple of @dfn{ECB-windows}
845 for browsing your sources comfortable with the mouse and the keyboard.
846 These ``special'' windows are also called @dfn{tree-buffer} in this
847 manual. Every @dfn{item} in such a tree-buffer, i.e. every line, is
848 also called a @dfn{node} of this tree-buffer. See @ref{Tree-buffer
849 styles} to get an impression about the look&feel of these
850 tree-buffers. There are currently three different types of
851 ECB-windows/tree-buffers:
854 @item ECB-Directories
859 In addition to these ``special'' ECB-windows you have always an
860 @dfn{edit-area} where you can edit sour source-files. The edit-area
861 can be divided into several @dfn{edit-windows} - as many as you need
862 (@pxref{The edit-area}). And at the bottom of the ECB-frame a
863 durable @dfn{compilation-window} (also called @dfn{compile-window})
864 can be displayed (optional), where all the output of Emacs-compilation
865 (compile, grep etc.) is shown (@pxref{Temp- and compile-buffers}).
867 The following ``screenshot'' illustrates the typical layout of
868 the ECB-frame@footnote{This is only one example of the layouts ECB
869 offers, see @ref{Changing the ECB-layout}}:
873 ------------------------------------------------------------------
881 |--------------| Edit-area |
882 | | (can be splitted in several edit-windows) |
889 ------------------------------------------------------------------
891 | Compilation-window (optional) |
893 ------------------------------------------------------------------
897 In the following subsections the ``special'' ECB-windows will be
901 * ECB Directories-buffer:: Contents of the ECB Directories-buffer
902 * ECB Sources-buffer:: Contents of the ECB Sources/history-buffer
903 * ECB Methods-buffer:: Contents of the ECB Methods-buffer
906 @node ECB Directories-buffer, ECB Sources-buffer, Overview, Overview
907 @section ECB Directories-buffer
912 Select directories (and - if enabled - source files) in the
913 @dfn{ECB-Directories} buffer by clicking a mouse button on the directory
914 name or by hitting RETURN when the cursor is placed on the item line,
915 see @ref{Usage of ECB}.
917 IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key
918 while clicking with the primary mouse button (@pxref{Using the mouse})
919 or RETURN (@pxref{Using the keyboard})) on a directory node in the
920 this buffer then the directory-contents-cache for this directory will
921 be refreshed and actualized.
924 Directory names with a ``[+]'' symbol after (or before) them can be
925 expanded/collapsed by clicking on the symbol, pressing the TAB key
926 (@pxref{Using the keyboard}) when the cursor is placed on the package
927 line or clicking a mouse button on the item, see @ref{Using the mouse}.
930 Right clicking on an item will open a popup menu where different
931 operations on the item under the mouse cursor can be performed.
934 Pressing F2 will open the ECB customization group
935 (@pxref{Customizing}) in the edit window. F3 shows the online help in
936 the edit-window. Pressing F4 in the ECB-directories buffer will offer
937 adding a new source-path.
940 @node ECB Sources-buffer, ECB Methods-buffer, ECB Directories-buffer, Overview
941 @section ECB Sources-buffer
947 Source files can be selected by clicking with the primary mouse button
948 (@pxref{Using the mouse}) or hitting RETURN (@pxref{Using the
949 keyboard}) on the source row in the @dfn{ECB-Sources} or
950 @dfn{ECB-History} windows. The buffer of the selected source-file will
951 be displayed in an edit-window - which one depends on the setting in
952 @code{ecb-mouse-click-destination}.
954 IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key
955 while clicking with the primary mouse button (@pxref{Using the mouse})
956 or RETURN (@pxref{Using the keyboard})) on a source row in the
957 ECB-Sources or ECB-History windows then the source will not be
958 displayed in an edit-window but it will be scanned in the background
959 and all its contents (e.g. methods and variables) are listed in the
960 @dfn{ECB Methods} window (@pxref{ECB Methods-buffer}. So you can get an
961 overlook over the source without changing the buffer in the
965 Clicking on the source file with the secondary mouse button or
966 C-RETURN (@pxref{Usage of ECB}) will open the source file in
967 another edit window - which one depends on the setting in
968 @code{ecb-mouse-click-destination}.
971 Right clicking on a source file (mouse-button 3) will open a popup
972 menu where different operation on the item under the mouse cursor can
976 @node ECB Methods-buffer, , ECB Sources-buffer, Overview
977 @section ECB Methods-buffer
980 The @dfn{ECB-Methods} buffer contains all parsed and recognized tags
981 of the current source-buffer. It is called ``Method-buffer'' because
982 ECB is mostly designed for browsing sourcecode files and for
983 programming-languages these tags are often methods (and variables
984 etc.) To simplify explanations we talk in the following only about
985 methods and variables - but in general the method-buffer can contain
986 any kind of tags (e.g. sections and subsections for texinfo
991 When a method/variable is selected with the primary mouse button
992 (@pxref{Using the mouse}) or RETURN (@pxref{Using the keyboard}) the
993 buffer in the edit-window (which one depends on the setting in
994 @code{ecb-mouse-click-destination}) will jump to the method/variable.
996 IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key
997 while clicking with the primary mouse button (@pxref{Using the mouse})
998 or RETURN (@pxref{Using the keyboard})) on a node in this buffer then
999 the edit-buffer will be narrowed to the selected tag (see also
1000 option @code{ecb-tag-visit-post-actions}). But this works only for
1001 sources parsed by semantic, not by imenu or etags!
1004 Clicking on a method/variable with the secondary mouse button or C-RETURN
1005 (@pxref{Usage of ECB}) will jump to the method in another edit window
1006 - which one depends on the setting in
1007 @code{ecb-mouse-click-destination}.
1010 Right clicking on a method/variable will open a popup menu where
1011 different operation on the item under the mouse cursor can be
1015 @node Activation and Deactivation, Usage of ECB, Overview, Top
1016 @chapter Activation and Deactivation
1019 This chapter describes all aspects of activating and deactivating ECB.
1022 * Standard activation:: How to manually (de)activate ECB
1023 * Automatic activation:: Automatically (de)activating ECB
1026 @strong{IMPORTANT}: Regardless of the activation-type (standard or
1027 automatic) the activation-process of ECB is always completely
1028 failure-save. This means any error during any step of the
1029 activation-process forces a complete cleanup (e.g. removing hooks,
1030 disabling advices etc.) of all settings ECB did (e.g. adding hooks,
1031 activating advices etc.) until the failure. Therefore if
1032 ECB-activation stops cause of a failure then you can be sure that your
1033 Emacs has the same state as before the ECB-activation-start!
1035 @node Standard activation, Automatic activation, Activation and Deactivation, Activation and Deactivation
1036 @section Standard activation and deactivation
1038 Call @kbd{M-x ecb-activate} and @kbd{M-x ecb-deactivate} to activate
1039 or deactivate ECB@footnote{Activation is also possible via the menu
1040 ``Tools --> Start Code Browser (ECB)''.}. If you want ECB started in a
1041 new frame see the option @code{ecb-new-ecb-frame} (default is nil).
1042 @code{ecb-activate} always raises and selects the ECB-frame even if
1043 ECB is already started.
1046 Because ECB is a global minor-mode it can also be
1047 (de)activated/toggled by @kbd{M-x ecb-minor-mode}.
1049 @cindex Activation hook-sequence
1050 @anchor{Activation hook-sequence}
1051 The following sequence of hooks is evaluated during activation of ECB:
1053 @item @code{ecb-before-activate-hook}
1054 @item <All actions for activation but no layout drawing>
1055 @item @code{ecb-activate-before-layout-draw-hook}
1056 @item @code{ecb-redraw-layout-before-hook}
1057 @item <Drawing the layout>
1058 @item @code{ecb-redraw-layout-after-hook}
1059 @item @code{ecb-activate-hook}
1062 @anchor{Deactivation hook-sequence}
1063 @cindex Deactivation hook-sequence
1064 The following sequence of hooks is evaluated during deactivation of
1067 @item @code{ecb-before-deactivate-hook}
1068 @item <All actions for deactivation of ECB>
1069 @item @code{ecb-deactivate-hook}
1072 @node Automatic activation, , Standard activation, Activation and Deactivation
1073 @section Automatic activation and deactivation
1075 @cindex Automatic activation
1076 @cindex Automatic deactivation
1077 There are two ways for auto. (de)activation ECB after Emacs-start and
1078 for different window-configurations.
1081 @item ecb-auto-activate
1082 This option is for auto. activating ECB after Emacs-startup. Set this
1083 to not nil and ECB will automatically be started after Emacs comes up.
1085 @item window-manager support
1086 The window-manager support of ECB deactivates ECB when going to
1087 another window-configuration and reactivates ECB when coming back to
1088 the ECB-window-configuration. For all details about this see
1089 @ref{Window-managers and ECB}.
1092 @node Usage of ECB, Customizing, Activation and Deactivation, Top
1093 @chapter Usage of ECB
1095 This chapter describes in a detailed manner all aspects of using the
1099 * Using the mouse:: Working with the mouse
1100 * Using the keyboard:: Working with the keyboard
1101 * The edit-area:: How to use the edit-area
1102 * Temp- and compile-buffers:: Displaying temp- and compilation-buffers
1103 * The other window:: How the ``other window'' is determined
1104 * The Methods buffer:: Using and customizing the Methods-buffer
1105 * Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers
1106 * The ECB-layout:: Changing, customizing, redrawing, creating
1107 * Hiding the ECB windows:: Hiding/Showing the ECB-windows
1108 * Maximizing the ECB windows:: Maximizing the ECB-windows
1109 * Back/forward navigation:: Back- and forward navigation like a browser
1110 * ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows
1111 * Stealthy background tasks:: Stealthy background-tasks of ECB
1112 * Interactive ECB commands:: All interactive user-commands of ECB
1115 @node Using the mouse, Using the keyboard, Usage of ECB, Usage of ECB
1116 @section Working with the mouse in the ECB-windows
1118 @cindex primary button
1119 @cindex secondary button
1120 @cindex mouse button
1121 Normally you get best usage if you use ECB with a mouse. ECB
1122 distinguishes between a @dfn{primary} and a @dfn{secondary}
1125 With the option @code{ecb-primary-secondary-mouse-buttons} the following
1126 combinations of primary and secondary mouse-buttons are possible:
1130 primary: mouse-2, secondary: C-mouse-2@footnote{means mouse-2 while CTRL-key
1131 is pressed.}. This is the default.
1134 primary: mouse-1, secondary: C-mouse-1
1137 primary: mouse-1, secondary: mouse-2
1140 If you change this during ECB is activated you must deactivate and activate
1141 ECB again to take effect.
1143 @subsection The primary mouse-button
1145 A click with the primary button causes the main effect in each ECB-buffer:
1148 @item ECB Directories:
1149 Expanding/collapsing nodes and displaying files in the ECB-Sources
1152 @item ECB sources/history:
1153 Opening the file in that edit-window specified by the option
1154 @code{ecb-mouse-click-destination}.
1157 Jumping to the method in that edit-window specified by the option
1158 @code{ecb-mouse-click-destination}.
1161 @subsection The POWER- or SHIFT-click
1165 A click with the primary mouse-button while the SHIFT-key is pressed
1166 is called the POWER-click and does the following (depending on the
1167 ECB-buffer where the POWER-click occurs):
1170 @item ECB Directory:
1171 Refreshing the directory-contents-cache (see
1172 @code{ecb-cache-directory-contents}).
1174 @item ECB sources/history:
1175 Only displaying the source-contents in the method-buffer but not
1176 displaying the source-file in an edit-window. This means it opens the
1177 clicked source only in the background and shows all its
1178 methods/variables in ECB-Methods; the buffer of the edit-window is not
1179 changed! This is very useful to get only an overlook for a certain
1183 Narrowing to the clicked method/variable/ect... (see
1184 @code{ecb-tag-visit-post-actions}). But this works only for sources
1185 parsed by semantic, not by imenu or etags!
1188 Per default the complete node-name of an item in a tree-buffer is
1189 displayed in the echo-area if the mouse moves over it, regardless if
1190 the related window is the active one or not. You get the same effect
1191 always after a POWER-click. In general: Via
1192 @code{ecb-show-node-info-in-minibuffer} you can specify in a detailed
1193 manner for every ECB tree-buffer when and which node-info should be
1194 displayed in the minibuffer.
1196 @subsection The secondary mouse-button
1198 The secondary mouse-button is for opening (jumping to) the file in
1199 another edit-window (see the documentation of the option
1200 @code{ecb-mouse-click-destination}).
1202 @subsection The right mouse-button
1204 In each ECB-buffer mouse-3 (= right button) opens a special context
1205 popup-menu for the clicked item where you can choose several senseful
1208 With the options @code{ecb-directories-menu-user-extension},
1209 @code{ecb-sources-menu-user-extension},
1210 @code{ecb-methods-menu-user-extension} and
1211 @code{ecb-history-menu-user-extension} you can add statically new
1212 commands to the popup-menus. See the docstring of
1213 @code{ecb-directories-menu-user-extension} for more details.
1215 With the options @code{ecb-directories-menu-user-extension-function},
1216 @code{ecb-sources-menu-user-extension-function},
1217 @code{ecb-methods-menu-user-extension-function} and
1218 @code{ecb-history-menu-user-extension-function} you can add new
1219 commands to the popup-menus in a dynamic manner. See the docstring of
1220 @code{ecb-directories-menu-user-extension-function} for more details.
1222 With the options @code{ecb-directories-menu-sorter},
1223 @code{ecb-sources-menu-sorter}, @code{ecb-methods-menu-sorter} and
1224 @code{ecb-history-menu-sorter} you can even re-arrange all the entries
1227 @subsection Horizontal scrolling with the mouse
1229 In each tree-buffer of ECB you can easily scroll left and right with
1230 the mouse if the option @code{ecb-tree-easy-hor-scroll} is not
1233 The reason for this is: XEmacs has horizontal scroll-bars so invisible
1234 parts beyond the right window-border of a tree-buffer can always made
1237 GNU Emacs does not have hor. scroll-bars so especially with the mouse
1238 it is quite impossible to scroll smoothly right and left. The
1239 functions @code{scroll-left} and @code{scroll-right} can be annoying
1240 and are also not bound to mouse-buttons.
1242 ECB offers three ways for smoothly hor. scrolling with GNU Emacs if
1243 @code{ecb-tree-easy-hor-scroll} is a positive integer-value S:
1247 In all ECB-tree-buffers the keys @kbd{M-mouse-1} and @kbd{M-mouse-3}
1248 are bound to scrolling left rsp. right with scroll-step S.
1251 Clicking with mouse-1 or mouse-2 onto the edge of the modeline has the
1252 same effect, i.e. if you click with mouse-1 onto the left \(resp
1253 right) edge of the modeline you will scroll left \(resp. right) with
1257 Additionally @kbd{C-M-mouse-1} and @code{C-M-mouse-3} are bound to
1258 scrolling left rsp. right with scroll-step @code{window-width} - 2.
1261 This is NOT done for XEmacs cause of its horizontal scrollbars. If you
1262 want scrolling left and right with the mouse in XEmacs then activate
1263 the horizontal scrollbars.
1266 @node Using the keyboard, The edit-area, Using the mouse, Usage of ECB
1267 @section Working with the keyboard in the ECB-windows
1269 ECB offers the @code{ecb-mode-map} which binds the most important
1270 functions of ECB to keys so you can easily use ECB in every
1271 window@footnote{Regardless if a tree-window or an edit-window} without
1274 IMPORTANT: Do not modify @code{ecb-mode-map} directly! The option
1275 @code{ecb-key-map} defines all ECB keybindings, including a common
1276 prefix-key (This is by default @kbd{C-c .}). If there are conflicts
1277 with other minor-modes or packages you can define very easy another
1278 prefix. Please read carefully the description of @code{ecb-key-map}
1279 (@pxref{ecb-general}).!
1281 The following sections describe special topics about using the
1282 keyboard in the ECB-tree-buffers:
1285 * Navigation/Selection:: Keyboard navigation/selection in a tree-buffer
1286 * Incremental search:: Find nodes as fast as possible
1287 * Personal keybindings:: Adding personal keybindings to a tree-buffer
1288 * Using popup-menus:: Using the popup-menus from keyboard.
1291 @node Navigation/Selection, Incremental search, Using the keyboard, Using the keyboard
1292 @subsection Navigation and Selection in a tree-buffer
1298 In the ECB-buffers RETURN and TAB are the most important keys:
1302 RETURN does the same as the primary button and C-RETURN does the same
1303 as the secondary button. S-RETURN is the same as the SHIFT-click or
1304 POWER-click. The terms ``primary'', ``secondary'', ``SHIFT-'' and
1305 ``POWER-click'' are explained in @ref{Using the mouse}. See also the
1306 option @code{ecb-tree-RET-selects-edit-window} and the function
1307 @code{ecb-toggle-RET-selects-edit-window} which is bound to @kbd{C-t}
1308 in each tree-buffer of ECB!
1311 TAB always expands or collapses expandable nodes.
1314 The RETURN and TAB keys can not be (re)defined with @code{ecb-key-map}!
1316 If you set @code{ecb-tree-navigation-by-arrow} to not nil then the left- and
1317 right-arrow keys work in the ECB tree-window in the following smart way:
1321 Left-arrow: If node is expanded then it will be collapsed otherwise
1322 (i.e. current node is either not expandable or not expanded) point
1323 jumps to the next ``higher'' node in the hierarchical tree (higher
1324 means the next higher level or - if no higher level available
1325 - the next higher node on the same level).
1328 Right-arrow: If node is expandable but not expanded then it will be
1329 expanded. Otherwise (i.e. current node is either not expandable or
1330 already expanded) point jumps to the next following node (which is the
1331 first subnode in case of an already expanded node or simply the next
1332 node in the following line).
1336 @node Incremental search, Personal keybindings, Navigation/Selection, Using the keyboard
1337 @subsection Incremental search for a node in current tree-buffer
1339 @cindex Incremental search
1340 Each display-able key (e.g. all keys normally bound to @code{self-insert-command})
1341 is appended to the current search-pattern. The tree-buffer tries to jump to the
1342 first node which matching the current search-pattern either as substring or as
1343 prefix (see below). If no match is found then nothing is done. There are some
1347 @item @kbd{backspace} and @kbd{delete}:
1348 Delete the last character from the search-pattern.
1351 Delete the complete search-pattern
1354 Expand either to a complete node if current search-pattern is already
1355 unique or expands to the greatest common substring or prefix of the
1356 nodes. If there are at least two nodes with the same greatest
1357 common-prefix than every hit of @kbd{end} jumps to the next node with this
1361 For better overlooking the current search-pattern is shown in the echo area.
1362 After selecting a node with RET the search-pattern is cleared out. With
1363 @code{ecb-tree-incremental-search} you can specify if the current search-pattern
1364 must be a real prefix of the node (default) or if any substring is matched.
1366 For faster and easier finding the right node in a ecb-window the incremental
1367 search ignores the following non interesting stuff:
1370 @item any leading spaces
1371 @item expand/collapse-buttons: [+] rsp. [-]
1372 @item protection-signs (+, -, #) in the method-window if uml-notation is used
1373 @item variables types or return-types in front of variable- or method-names.
1374 @item const specifier for variables
1377 This means: Just type in the prefix (rsp. a substring) of a class-,
1378 variable-, method-, directory- or filename and ECB will bring you as
1379 fast as possible to the node you want. Incremental node-search uses
1380 the value of @code{case-fold-search}.
1382 Tip: The @code{ecb-minor-mode} offers you in the @code{ecb-mode-map}
1383 (customizable via @code{ecb-key-map}) some keys for selecting every window
1384 of the ecb-frame. This makes window-selection a child´s play. For
1385 example you can jump into the method-window by hitting @kbd{C-c . gm}.
1387 @node Personal keybindings, Using popup-menus, Incremental search, Using the keyboard
1388 @subsection Adding personal keybindings
1390 There are five hooks which can be used for adding personal keybindings
1391 to the ECB tree-buffers:
1394 @item @code{ecb-common-tree-buffer-after-create-hook}
1395 @item @code{ecb-directories-buffer-after-create-hook}
1396 @item @code{ecb-sources-buffer-after-create-hook}
1397 @item @code{ecb-methods-buffer-after-create-hook}
1398 @item @code{ecb-history-buffer-after-create-hook}
1401 These hooks are called directly after tree-buffer creation so they can
1402 be used to add personal local keybindings@footnote{To be more general:
1403 They can be used to run any arbitrary lisp code after a tree-buffer
1404 creation!} either to all tree-buffers
1405 (@code{ecb-common-tree-buffer-after-create-hook}) or just to a certain
1406 tree-buffer. Here is a list which keys MUST NOT be rebound:
1409 @item @kbd{RET} and all combinations with @kbd{Shift} and @kbd{Ctrl}:
1410 Used for selecting nodes in all tree-buffers.
1412 Used for expanding/collapsing nodes in all tree-buffers.
1414 Used for toggling ``jump after selection'' in all tree-buffers, see
1415 command @code{ecb-toggle-RET-selects-edit-window}.
1416 @item All self-inserting characters:
1417 Used for easy and fast navigation in all tree-buffers,
1418 @xref{Incremental search}.
1419 @item @kbd{F2}, @kbd{F3}, @kbd{F4}:
1420 Used for customizing ECB, adding source-path in the directories buffer.
1423 The following example binds @kbd{C-a} to some useful code in ALL
1424 tree-buffers and @kbd{C-d} to even more useful code ONLY in the
1429 (add-hook 'ecb-common-tree-buffer-after-create-hook
1431 (local-set-key (kbd "C-a")
1434 (message "ECB is great!")))))
1436 (add-hook 'ecb-directories-buffer-after-create-hook
1438 (local-set-key (kbd "C-d")
1441 (message "ECB is wonderful!")))))
1445 @node Using popup-menus, ,Personal keybindings, Using the keyboard
1446 @subsection Using the popup-menu of a tree-buffer from keyboard.
1449 A popup-menu of a tree-buffer can be activated from keyboard with the
1450 command @code{tree-buffer-show-menu-keyboard} which is bound to
1451 @kbd{M-m} in every tree-buffer. How the popup-menu is displayed
1452 depends if this command is called with a prefix-argument or not:
1454 If called without a prefix-arg then the popup-menu is displayed
1455 graphically as if it would be activated via mouse (for GNU Emacs this
1456 works perfectly but for XEmacs there is a bug which results in a wrong
1457 menu-position - but the menu itself works also with XEmacs).
1459 If called with a prefix-arg (@kbd{C-u M-m}) then the popup-menu is
1460 displayed with the tmm-mechanism (like the Emacs-[menu-bar] is
1461 displayed when `tmm-menubar' is called). This tmm-display is only
1462 available for GNU Emacs.
1465 @node The edit-area, Temp- and compile-buffers, Using the keyboard, Usage of ECB
1466 @section Working with the edit-window(s) of the edit-area
1469 ECB offers you all what you need to work with the edit-area as if the
1470 edit-windows of the edit-area would be the only windows of the
1473 @cindex Adviced functions
1474 ECB offers you to advice the following functions so they work best with ECB:
1477 @item @code{other-window}
1478 @item @code{delete-window}
1479 @item @code{delete-other-windows}
1480 @item @code{delete-windows-on}
1481 @item @code{split-window-horizontally}
1482 @item @code{split-window-vertically}
1483 @item @code{split-window}
1484 @item @code{display-buffer}
1485 @item @code{switch-to-buffer}
1486 @item @code{switch-to-buffer-other-window}
1487 @item @code{other-window-for-scrolling}
1488 @item @code{balance-windows}
1492 The behavior of the adviced functions is (slightly simplified):
1496 All these adviced functions behaves exactly like their corresponding
1497 original functions but they always act as if the edit-window(s) of ECB
1498 would be the only window(s) of the ECB-frame. So the edit-window(s) of
1499 ECB seems to be a normal Emacs-frame to the user. This means that you
1500 can split and delete edit-windows without any restriction - ECB
1501 ensures that neither the special ECB-windows nor the compile-window
1505 If there is a durable compile-window (@pxref{Temp- and
1506 compile-buffers}) then all compilation-buffers in the sense of
1507 @code{ecb-compilation-buffer-p} will be displayed in the
1511 If called in another frame than the ECB-frame these functions behave
1512 exactly like the not adviced original versions!
1515 ATTENTION: If you want to work within the edit-area with splitting and
1516 unsplitting (i.e. deleting) the edit-window(s) it is highly
1517 recommended to use the adviced-functions of ECB instead of the
1518 original Emacs-functions (see above). Per default ECB advices all of
1519 the functions mentioned above but with the option
1520 @code{ecb-advice-window-functions} you can customizes which functions
1521 should be adviced by ECB. Please read carefully the documentation of
1524 Another interesting option in the context of the edit-window and these
1525 adviced functions is @code{ecb-layout-always-operate-in-edit-window}!
1527 @subsection Documentation of the adviced window functions
1529 This section describes for every adviced window function (s.a.) how it
1530 differs from the original version. Only the differences are mentioned,
1531 so if you want the full documentation of such a function call
1532 @code{describe-function} or @kbd{C-h f}.
1534 @deffn Command other-window ARG &optional ALL-FRAMES
1535 Around-advice @code{ecb}: The ECB-version of @code{other-window}.
1536 Works exactly like the original function with the following
1537 ECB-adjustment: The behavior depends on
1538 @code{ecb-other-window-behavior}.
1541 @deffn Command delete-window &optional WINDOW
1542 Around-advice @code{ecb}: The ECB-version of @code{delete-window}.
1543 Works exactly like the original function with the following
1546 If optional argument WINDOW is nil (i.e. probably called
1547 interactively): If called in a splitted edit-window then it works like
1548 as if all the edit-windows would be the only windows in the frame.
1549 This means the current edit-window which contains the point will be
1550 destroyed and its place will be occupied from another one. If called
1551 in an unsplitted edit-window then nothing is done. If called in the
1552 compile-window of ECB then the compile-window will be hidden (like
1553 with @code{ecb-toggle-compile-window}). If called in an ecb-window
1554 of the current ECB-layout there are two alternatives:
1557 @item If the function is contained in
1558 @code{ecb-layout-always-operate-in-edit-window} the right edit-window
1559 is selected (depends on the value of the option
1560 @code{ecb-mouse-click-destination}) and does then it´s job.
1562 @item Otherwise the behavior depends on the value of the option
1563 @code{ecb-advice-window-functions-signal-error}.
1566 If optional argument WINDOW is a living window (i.e. called from
1567 program): If WINDOW is an edit-window then this window is deleted, if
1568 WINDOW is the compile-window then it will be hidden and otherwise the
1569 behavior depends on @code{ecb-advice-window-functions-signal-error}.
1572 @deffn Command delete-other-windows &optional WINDOW
1573 Around-advice @code{ecb}: The ECB-version of
1574 @code{delete-other-windows}. Works exactly like the original function
1575 with the following ECB-adjustment:
1577 If optional argument WINDOW is nil (i.e. probably called
1578 interactively): If called in a splitted edit-window then it works like
1579 as if all the edit-windows would be the only windows in the frame.
1580 This means all other edit-windows besides the current edit-window
1581 which contains the point will be destroyed and the current edit-window
1582 fills the whole edit-area. Neither the special ecb-windows nor the
1583 compile-window will be destroyed!
1588 If called in an unsplitted edit-window then either the compile-window
1589 will be hidden (if there is one) otherwise nothing is done.
1592 If called in one of the ecb-windows then the current one is maximized,
1593 i.e. the other ecb-windows (not the edit-windows!) are deleted.
1596 If called in the compile window there are two alternatives:
1600 If the function is contained in
1601 @code{ecb-layout-always-operate-in-edit-window} the right edit-window
1602 is selected (depends on the value of the option
1603 @code{ecb-mouse-click-destination}) and then it does it´s job.
1606 Otherwise the behavior depends on the value of the option
1607 @code{ecb-advice-window-functions-signal-error}.
1611 If optional argument WINDOW is a living window (i.e. called from
1612 program): If WINDOW is an edit-window then this window is maximized
1613 (i.e. the other edit-window is deleted) if there are more at least 2
1614 edit-windows otherwise the compile-window is deleted (if there is
1615 one). If WINDOW is an ecb-window then only the other ecb-windows are
1616 deleted and in all other cases the behavior depends on
1617 @code{ecb-advice-window-functions-signal-error}.
1621 @deffn Command delete-windows-on BUFFER &optional FRAME
1622 Around-advice @code{ecb}: The ECB-version of @code{delete-windows-on}.
1623 Works exactly like the original function with the following
1626 An error is reported if @var{BUFFER} is an ECB-tree-buffer. These
1627 windows are not allowed to be deleted.
1630 @deffn Command split-window &optional WINDOW SIZE HORFLAG
1631 Around-advice @code{ecb}: The ECB-version of @code{split-window}.
1632 Works exactly like the original function with the following
1635 If called for a not-edit-window in the @code{ecb-frame} it stops with
1636 an error if @code{split-window} is not contained in the option
1637 @code{ecb-layout-always-operate-in-edit-window}! Besides this (e.g.
1638 called for a window in another frame than the @code{ecb-frame}) it
1639 behaves like the original version.
1643 @deffn Command split-window-horizontally
1644 Around-advice @code{ecb}: The ECB-version of
1645 @code{split-window-horizontally}. Works exactly like the original
1646 function with the following ECB-adjustment:
1648 If called in any other window of the current ECB-layout it stops with
1649 an error if this @code{split-window-horizontally} is not contained in
1650 the option @code{ecb-layout-always-operate-in-edit-window}!
1653 @deffn Command split-window-vertically
1654 Around-advice @code{ecb}: The ECB-version of
1655 @code{split-window-vertically}. Works exactly like the original
1656 function with the following ECB-adjustment:
1658 If called in any other window of the current ECB-layout it stops with
1659 an error if this @code{split-window-vertically} is not contained in
1660 the option @code{ecb-layout-always-operate-in-edit-window}!
1664 @deffn Command display-buffer BUFFER &optional NOT-THIS-WINDOW FRAME
1665 Around-advice @code{ecb}: Makes this function compatible with ECB if
1666 called in or for the ecb-frame. It displays all buffers which are
1667 ``compilation-buffers'' in the sense of
1668 @code{ecb-compilation-buffer-p} in the compile-window of ECB. If the
1669 compile-window is temporally hidden then it will be displayed first.
1671 If there is no compile-window (@code{ecb-compile-window-height} is
1672 nil) then it splits the edit-window if unsplitted and displays BUFFER
1673 in another edit-window but only if @code{pop-up-windows} is not nil
1674 (otherwise the edit-window will not be splitted).
1676 All buffers which are not ``compilation-buffers'' in the sense of
1677 @code{ecb-compilation-buffer-p} will be displayed in one of the
1678 edit-area and @code{display-buffer} behaves as if the edit-windows
1679 would be the only windows in the frame.
1681 If BUFFER is contained in @code{special-display-buffer-names} or
1682 matches @code{special-display-regexps} then
1683 @code{special-display-function} will be called (if not nil). But this
1684 behavior depends on the value of the option
1685 @code{ecb-ignore-special-display}. The values of
1686 @code{same-window-buffer-names} and @code{same-window-regexps} are
1689 See the option @code{ecb-ignore-display-buffer-function}!
1691 If called for other frames it works like the original version.
1694 @deffn Command switch-to-buffer BUFFER &optional NORECORD
1695 Around-advice @code{ecb}: The ECB-version of @code{switch-to-buffer}.
1696 Works exactly like the original but with the following enhancements
1699 ``compilation-buffers'' in the sense of
1700 @code{ecb-compilation-buffer-p} will be displayed always in the
1701 compile-window of ECB (if @code{ecb-compile-window-height} is not nil)
1702 - if the compile-window is temporally hidden then it will be displayed
1703 first. If you do not want this you have to modify the options
1704 @code{ecb-compilation-buffer-names},
1705 @code{ecb-compilation-major-modes} or
1706 @code{ecb-compilation-predicates}.
1708 If called for non ``compilation-buffers'' (s.a.) from outside the
1709 edit-area of ECB it behaves as if called from an edit-window if
1710 @code{switch-to-buffer} is contained in the option
1711 @code{ecb-layout-always-operate-in-edit-window}. Otherwise an error is
1715 @deffn Command switch-to-buffer-other-window BUFFER &optional FRAME
1716 Around-advice @code{ecb}: The ECB-version of
1717 @code{switch-to-buffer-other-window}. Works exactly like the original
1718 but with some adaptions for ECB so this function works in a
1721 If called in any special ecb-window of the current ECB-layout then it
1722 goes always to an edit-window (which one depends on the setting in
1723 @code{ecb-mouse-click-destination}) and then goes on as if called from
1726 If a compile-window is used (i.e. @code{ecb-compile-window-height} is
1727 not nil) then ``compilation-buffers'' in the sense of
1728 @code{ecb-compilation-buffer-p} are always displayed in the
1729 compile-window. If the compile-window is temporally hidden then it
1730 will be displayed first. If no compile-window is used it behaves like
1733 If called from within the compile-window then ``compilation-buffers''
1734 will be displayed still there and all other buffers are displayed in
1735 one of the edit-windows - if the destination-buffer is already
1736 displayed in one of the edit-windows then this one is used otherwise
1737 it behaves like the original.
1739 If called within an edit-window it behaves like the original function
1740 except for compilation-buffers (if a compile-window is used, see
1745 @deffn Function other-window-for-scrolling
1746 Around-advice @code{ecb}: This function determines the window which is
1747 scrolled if any of the ``other-window-scrolling-functions'' is called
1748 (e.g. @code{scroll-other-window}):
1750 If the option @code{ecb-scroll-other-window-scrolls-compile-window} is
1751 not nil (maybe set by
1752 @code{ecb-toggle-scroll-other-window-scrolls-compile}) and a
1753 compile-window is visible then always the current buffer in the
1754 compile-window is scrolled!
1756 Otherwise it depends completely on the setting in
1757 @code{ecb-other-window-behavior}.
1760 @deffn Command balance-windows
1761 Around-advice @code{ecb}: When called in the @code{ecb-frame} then
1762 only the edit-windows are balanced.
1765 @node Temp- and compile-buffers, The other window, The edit-area, Usage of ECB
1766 @section Temp- and compile-buffers display in ECB
1768 @cindex temporary buffers
1769 @cindex help buffers
1770 @cindex compilation buffers
1771 @cindex grep buffers
1772 If you call any help in Emacs, e.g. by calling @code{describe-function}, or
1773 if you do a completion in the minibuffer, then Emacs displays the
1774 result-buffer in another window. This behavior you have also in ECB.
1776 @subsection Standard Emacs behavior
1778 If the edit-area is already splitted into at least two edit-windows
1779 then the temp-buffer is displayed in another edit-window otherwise the
1780 edit-are will be splitted first into two edit-windows, one above the
1781 other. The variables @code{temp-buffer-max-height} and
1782 @code{temp-buffer-resize-mode} (for GNU Emacs) and
1783 @code{temp-buffer-shrink-to-fit} (for XEmacs) work also correctly with
1786 Same for all compilation output-buffers (e.g. after a @code{compile} or
1787 @code{grep}) and the variable @code{compilation-window-height}.
1789 This is default behavior of ECB. But there is also another way to
1790 display such buffers: Using a durable extra window at the bottom of
1793 @subsection Using a durable compile window
1795 With the option @code{ecb-compile-window-height} you can define if the
1796 ECB layout should contain per default a compile-window at the
1797 bottom (just specify the number of lines which should be used for the
1798 compile-window at the bottom of the frame). If ``yes'' ECB displays
1799 all buffers for which the function @code{ecb-compilation-buffer-p}
1800 returns not nil (e.g. all output of compilation-mode (compile, grep
1801 etc.) or all temp-buffers like *Help*-buffers) in this special
1804 In general: With the options @code{ecb-compilation-buffer-names},
1805 @code{ecb-compilation-major-modes} and
1806 @code{ecb-compilation-predicates} you can define which buffers should
1807 be displayed in the compile-window of ECB (for example if you call
1808 @code{switch-to-buffer} or @code{display-buffer} or if you run
1809 @code{compile} or if you display *Help*-buffers). Per default these
1810 are all temp-buffers like *Help*-buffers, all compile- and grep
1811 buffers, *Occur*-buffers etc. See the default values of these options.
1813 With the command @code{ecb-toggle-compile-window} (bound to @kbd{C-c .
1814 \}) you can toggle the visibility of the compile-window
1815 (@pxref{Interactive ECB commands}).
1817 There are some more useful options and commands related to the
1818 compile-window of ECB (to see all options for the compile-window see
1819 the customization group @ref{ecb-compilation}):
1823 With the option @code{ecb-compile-window-temporally-enlarge} you can
1824 allow Emacs to enlarge temporally the ECB-compile-window in some
1825 situations. Please read the comment of this option. See also the
1826 description of the command
1827 @code{ecb-toggle-compile-window-height}.
1830 With the option @code{ecb-enlarged-compilation-window-max-height} you
1831 specify how @code{ecb-toggle-compile-window-height} should
1832 enlarge the compile-window.
1835 With the command @code{ecb-cycle-through-compilation-buffers}
1836 (@pxref{Interactive ECB commands}) you can cycle through all current
1837 open compilation-buffers (in the sense of
1838 @code{ecb-compilation-buffer-p}) very fast.
1841 ECB offers the same compile-window functionality regardless if the
1842 ECB-window are hidden or not. The state of the compile-window will be
1843 preserved when toggling the ecb-windows or when maximizing one
1844 ecb-windows! So you have the advantage of one special window for all
1845 help-, grep or compile-output (see above) also when the ecb-windows
1846 are hidden - a window which will not be deleted if you call
1847 @code{delete-other-windows} (bound to @kbd{C-x 1}) for one of the
1848 edit-windows. In general: All features of the compile-window work with
1849 hidden ecb-windows exactly as when the ecb-windows are visible.
1852 @anchor{Problems with the compile window}
1853 @subsection What to do if there are problems with the compile-window
1855 Normally displaying temp- and compilation-buffers (or more general:
1856 displaying buffer for which @code{ecb-compilation-buffer-p} is not
1857 nil) should work reliable. But if there are problems which you can not
1858 handle with the options @code{ecb-compilation-buffer-names},
1859 @code{ecb-compilation-major-modes} or
1860 @code{ecb-compilation-predicates} then please go on like follows:
1864 Set the option @code{ecb-layout-debug-mode} to not nil.
1867 Reproduce the wrong behavior exactly by repeating all the operations
1868 which lead to the problem. If possible then restart Emacs before
1869 reproducing the problem so you can begin from the beginning!
1872 Now send immediately a bug report with
1873 @code{ecb-submit-problem-report}.
1876 Set @code{ecb-layout-debug-mode} back to nil if you do not want
1877 further debugging output in the *Messages* buffer"
1880 @anchor{Using special-display with ECB}
1881 @cindex special-display
1882 @subsection Handling special-display-buffers
1884 Emacs offers three options for a special-display-handling of certain
1885 buffers: @code{special-display-function},
1886 @code{special-display-buffer-names} and
1887 @code{special-display-regexps} (see the Emacs manual for a description
1888 of these options). ECB offers an option
1889 @code{ecb-ignore-special-display} for specification in which
1890 situations ECB should take account for the values of these
1891 special-display-options.
1893 Default-behavior of ECB is to ignore these special-display-options
1894 when a durable compile-window is active (i.e.
1895 @code{ecb-compile-window-height} is not nil). But with
1896 @code{ecb-ignore-special-display} you can tell ECB, that either always
1897 the special-display-options should be ignored as long as ECB is active
1898 or that they should be never igored regardless if a durable
1899 compile-window is set or not. In the latter case using
1900 @code{display-buffer} or @code{pop-to-buffer} takes always account for
1901 the values of these options - like the original behavior of Emacs.
1903 @node The other window, The Methods buffer, Temp- and compile-buffers, Usage of ECB
1904 @section How the ``other window'' is determined by ECB
1906 @cindex other window
1907 Normally all windows in an Emacs-frame are arranged in a cyclic order
1908 and window-selecting-commands like @code{other-window} or
1909 window-scrolling-commands like @code{scroll-other-window} choose
1910 simply the next@footnote{@code{other-window} allows to select ARG'th
1911 different window, i.e. the window ARG steps away from current window
1912 in the cyclic order of the windows} window after the current window as
1915 @subsection ``Other window''-basics in ECB
1917 With a typical window-layout of ECB such a cyclic order of
1918 @strong{all} windows in the ECB-frame does not make sense because it
1919 would be not very intuitive and against that what the user wants to
1920 ``say'' when calling @code{other-window} or
1921 @code{scroll-other-window}.
1923 Therefore ECB divides the whole set of windows of the ECB-frame in
1927 @item The edit-windows of the edit-area
1928 @item The special tree-windows for browsing-tasks
1929 @item The compile-window at the bottom (if there is one)
1930 @item The minibuffer-window of the ECB-frame (if active)
1933 Each of these subsets will be treated as a cyclic ordered subset, i.e.
1934 all windows in each of these subsets are ordered as the function
1935 @code{walk-windows} would visit the windows when the windows of a
1936 subset would be the only windows of a
1937 frame@footnote{@code{other-window} uses the same window-ordering as
1938 @code{walk-windows}}.
1940 @subsection Builtin ``other window'' behaviors of ECB
1942 ECB now offers to specify the behavior of commands like
1943 @code{other-window} or @code{scroll-other-window} within the
1944 ECB-frame. This can be done with the option
1945 @code{ecb-other-window-behavior}. This option offers several builtin
1949 @item All windows of the ECB-frame are considered
1951 ECB will cycle through all windows of the ECB-frame or scroll simply
1952 the next window in the ECB-frame, means it behaves like the original
1953 @code{other-window} rsp. the original
1954 @code{other-window-for-scrolling}.
1956 @item Only the windows of the edit-area are considered
1958 ECB will only cycle through the edit-windows of ECB or only scroll
1959 another edit-window. If the selected window is not an edit-window then
1960 all windows are taken into account.
1962 @item The edit-windos and the compile-window are considered
1964 Like above but the compile-window will be added to the subset of the
1967 @item Behave as smart and intuitive as possible
1969 This is the default behavior of ECB. ECB tries to choose the
1970 @code{other-window}-destination or the ``other window'' to scroll in a
1971 smart and intuitive way: If point is in one of the edit-windows and if
1972 the edit-area is splitted then always the ``next'' edit-window is
1973 choosen (whereas the next edit-window of the last edit-window is the
1974 first edit-window)- if the edit-area is unsplitted then the
1975 compile-window is used if there is one. In the context of an
1976 @code{other-window}-call the @var{ARG} of @code{other-window} will be
1979 If one of the special ecb-windows is selected then always the ``next''
1980 ecb-window is choosen (whereas the next ecb-window of the last
1981 ecb-window is the first ecb-window). In the context of an
1982 @code{other-window}-call the @var{ARG} of @code{other-window} will be
1983 taken into account. If there is only one ecb-window then ECB considers
1984 also the edit-windows.
1986 If the compile-window is selected then always the last edit-window
1987 which had the point will be used unless @code{other-window} has been
1988 called with a prefix-argument unequal 1.
1991 Regardless of the different behaviors above ECB handles the situation
1992 of an active minibuffer during a call to @code{other-window} or
1993 @code{scroll-other-window} like follows:
1995 If the minibuffer-window is selected then ECB always chooses the
1996 window @code{minibuffer-scroll-window} points to (when this variable
1997 is set, otherwise the compile-window or the last selected edit-window
1998 is choosen) when the called command is called to choose the 1. next
1999 window (always true for scrolling another window or true when
2000 @code{other-window} called without prefix-arg or with prefix-arg equal
2001 1). Otherwise the window ARG steps away is choosen (in case of
2002 @code{other-window}).
2004 If there is an active minibuffer but the minibuffer-window is not
2005 selected then @code{other-window} and @code{scroll-other-window}
2006 behave like the original version.
2008 @subsection User-defined ``other window'' behavior
2010 In addition to the builtin ``other window'' behaviors ECB offers a
2011 user to completely define for himself how ECB should choose another
2012 window for scrolling it or selecting it. This can be done with the
2013 option @code{ecb-other-window-behavior} too because this option can
2014 also have a function-symbol as value:
2016 Such a function gets seven arguments:
2019 A canonical list of all currently visible windows of the
2022 A canonical list of all currently visible edit-windows
2024 A canonical list of all currently visible ecb-windows
2026 The window-object of the compile-window if there is any.
2028 The minibuffer-window of the ECB-frame if there is an active
2031 The result of the function @code{ecb-where-is-point} - see the
2032 documentation of this function for details.
2034 An integer which indicates how many steps away from the current
2035 selected window the ``other-window'' is. Is nil when this function is
2036 called in another context than for @code{other-window}.
2039 The function has to return a window-object which is then used as
2040 ``other window'' for the command @code{other-window} or for scrolling
2041 another window (e.g. with @code{scroll-other-window}). Such a function
2042 has to handle properly all situation for itself.
2044 Here is an example for such a function:
2048 (defun ecb-get-other-window-smart (win-list
2055 "Implements the smart-setting of `ecb-other-window-behavior'."
2057 ;; if we have an active mini-buffer we delegate this to
2058 ;; `ecb-get-other-window-minibuf-active'
2059 (ecb-get-other-window-minibuf-active win-list
2066 ;; here we have no active minibuffer!
2067 (let ((nth-win (or nth-window 1)))
2068 (cond ((equal point-loc 'ecb)
2069 (ecb-next-listelem ecb-win-list (selected-window) nth-win))
2070 ((equal point-loc 'compile)
2072 (or (and ecb-last-edit-window-with-point
2073 (window-live-p ecb-last-edit-window-with-point)
2074 ecb-last-edit-window-with-point)
2075 (car edit-win-list))
2076 (ecb-next-listelem (append edit-win-list
2077 (list (selected-window)))
2080 (t ;; must be an edit-window
2081 (ecb-next-listelem (append edit-win-list
2083 (= (length edit-win-list)
2091 This example implements the builtin smart behavior described above.
2093 @node The Methods buffer, Filtering the tree-buffers, The other window, Usage of ECB
2094 @section Using and customizing the ECB-Methods buffer
2096 ECB is mostly designed to display parsing information for files
2097 supported by semantic. But beginning with version 1.94 it also
2098 supports other parsing engines like imenu and etags, so also files not
2099 supported by semantic but by imenu/etags can be displayed in the
2100 Method-buffer of ECB. Therefore we have to introduce some terminology:
2102 @cindex semantic-sources
2103 @anchor{Definition of semantic- and non-semantic-sources}
2105 @item @dfn{semantic-sources}:
2106 These are file-types for which a semantic grammar is available, so the
2107 files are parse-able by semantic. These sources are supported best by
2108 ECB and most of the following options and descriptions are related to
2109 these file-types. Examples are programming-sources like C++, C, Java,
2110 Emacs-Lisp and Texinfo-file and some more.
2112 @cindex non-semantic-sources
2113 @item @dfn{non-semantic-sources}:
2114 For these files there is no semantic-grammar available so they can not
2115 be parsed by semantic. Examples are Perl-, LaTeX- and TeX-files. But
2116 for many of these files imenu and/or etags parsers exist. ECB supports
2117 now parsing and displaying these file-types too and it uses for this
2118 some speedbar-logic.
2121 This chapter describes how to use and customize the Methods-buffer of
2125 * Visiting tags:: Possible actions after visiting a tag
2126 * Expanding:: Explicit and automatic expanding
2127 * Customizing the display:: How to customize the Methods-buffer display
2128 * Rebuilding the Methods:: When to rebuild the Methods-buffer
2131 @node Visiting tags, Expanding, The Methods buffer, The Methods buffer
2132 @subsection Possible actions after visiting a tag
2134 You visit a tag by clicking with either the primary oder secondary
2135 mouse-button (or by hitting @kbd{RET} or @kbd{C-RET} if using the
2136 keyboard) onto a node in the Methods-tree-buffer of ECB. This simply
2137 selects the ``right'' edit-window (depends if clicked with the primary
2138 or secondary button, in how many windows the edit-area is splitted and
2139 the value of @code{ecb-mouse-click-destination}) and puts the point
2140 onto the first line of the clicked tag.
2142 But you can define if after this ``basic'' tag-visit-action more
2143 additional actions should be performed by ECB. You can either use some
2144 of the predefined actions (e.g. highlighting the header-line of the
2145 tag) or define own actions. You can set different actions for
2146 different major-modes. All this is done via the option
2147 @code{ecb-tag-visit-post-actions}.
2149 The following actions are currently predefined:
2151 @item @code{ecb-tag-visit-highlight-tag-header}
2152 @item @code{ecb-tag-visit-smart-tag-start}
2153 @item @code{ecb-tag-visit-recenter}
2154 @item @code{ecb-tag-visit-recenter-top}
2155 @item @code{ecb-tag-visit-goto-doc-start}
2156 @item @code{ecb-tag-visit-narrow-tag}
2159 See the documentation of these function for details what they do.
2161 Per default ECB performs the actions
2162 @code{ecb-tag-visit-smart-tag-start} and
2163 @code{ecb-tag-visit-highlight-tag-header} for all major-modes.
2166 @node Expanding, Customizing the display, Visiting tags, The Methods buffer
2167 @subsection Explicit and automatic expanding of the ECB-methods-buffer
2169 @subsubsection Explicit expanding all nodes to a certain expansion level
2171 With the command @code{ecb-expand-methods-nodes} (bound to @kbd{C-c .
2172 x}) you can get a fast overlook of the contents of the source-buffer,
2173 because this command allows precisely expanding all tags with a
2174 certain indentation-level. So you can either expand no tags (or with
2175 other words collapse all tags) or expand all tags so see the contents
2176 of a buffer at one glance. Or you can expand exactly that tags of a
2177 certain indentation level.
2179 Which node-types are expanded (rsp. collapsed) by this command
2180 depends for semantic-sources on the options
2181 @code{ecb-methods-nodes-expand-spec} and
2182 @code{ecb-methods-nodes-collapse-spec}! For non-semantic-sources always
2183 all node-types are expanded/collapsed, i.e. the two options above
2184 takes no effect for these files.
2186 @subsubsection Explicit expanding of the current node to a certain level
2188 With the popup-menu of the methods-buffer an even more precise
2189 expansion is possible because it allows not only expanding all tags
2190 (see above) but offers in addition expanding only the current-node
2191 (for which the menu was activated) to an exact level of expansion:
2193 All menu-entries are label with an expansion-``level'' whereas level
2194 specifies precisely which level of nodes should be expanded. level
2195 means the indentation-level of the NODE itself and its (recursive)
2196 subnodes relative to the NODE itself.
2198 So a level value X means that all (sub)nodes with an indentation-level
2199 <= X relative to NODE are expanded and all other are collapsed.
2204 @item Expand this node to level 0:
2205 Expand only the NODE itself because it is the only node which has
2206 indentation 0 to itself. All deeper indented nodes will be collapsed.
2207 This is also the important difference between using this menu compared
2208 to clicking onto the expand-symbol of the node: The latter one expands
2209 the NODE to that expansion-state it has before the last collapsing (so
2210 when deeper nodes has been expanded they will be expanded now to). The
2211 former one expands exactly(!) to level 0, means expand only the node
2212 itself and collapse all(!) its subnodes recursively(!).
2214 @item Expand this node to level 1:
2215 Expand the NODE itself and all of its direct subnodes - because only
2216 the direct subnodes of NODE have indentation-level 1 relativ to NODE.
2217 All deeper nodes will be collapsed.
2219 @item Collapse this node completely:
2220 Collapses the current node recursively, means collapse not only the
2221 node itself but also its subnodes, the subnodes of the subnodes and so
2222 on! This is very differnt from clicking onto the collapse symbol
2223 because this action only collapses the node itself but preserves the
2224 expansion-state of all its subnodes!
2228 Expanding the current node with the popup-menu ignores the settings in
2229 the options @code{ecb-methods-nodes-expand-spec} and
2230 @code{ecb-methods-nodes-collapse-spec}!
2232 @subsubsection Automatic expansion ot tags after buffer-parsing
2234 With the option @code{ecb-show-tags} you tell ECB how to display tags
2235 of a certain tag-class (@pxref{Customizing the display}). Among other
2236 things you can tell ECB that a certain tag-class should be combined
2237 under an expanded or collapsed bucket-node. But such a setting defines
2238 the expansion-state of such a bucket-node only direct afterwards the
2239 buffer has been (re)parsed, which can occur after opening a file,
2240 after autom. reparsing the buffer via semantic or after manually
2241 rebuilding the methods-buffer of ECB.
2243 The tag-class @code{type} (classes, interfaces, enumerations etc.) is
2244 divided into several subtypes by semantic. The subtypes are stings
2245 which names exactly if the tag with tag-class @code{type} is a class,
2246 an interface, an enumeration, a typedef etc. With the option
2247 @code{ecb-type-tag-expansion} you can tell ECB if these type-tags
2248 should be autom. expanded after (reparsing) a buffer (see above) or if
2249 they should be displayed collapsed - so all its members (methods,
2250 variables etc.) are hidden.
2252 @subsubsection Automatic expanding the ECB-methods-buffer for current tag
2254 If the option @code{ecb-highlight-tag-with-point} is switched on, then
2255 always that node in the method-buffer is highlighted which belongs to
2256 the current semantic-tag under point in the current active
2257 edit-window. But if this node is invisible (probably because its
2258 parent node is collapsed) then no node is highlighted if the auto.
2259 expanding feature is switched off.
2261 You can either switch on this feature with the option
2262 @code{ecb-auto-expand-tag-tree} or even easier with the command
2263 @code{ecb-toggle-auto-expand-tag-tree}.
2265 There is another option
2266 @code{ecb-expand-methods-switch-off-auto-expand} which makes both
2267 explicit and auto. expanding best working together. See the
2268 documentation of this option to get the details.
2270 The autom. expanding feature is only available for semantic-sources!
2272 Previous versions of ECB have always fully expanded the whole tree in
2273 the Methods-buffer if the current tag in the source-buffer was not
2274 visible in the current tree - e.g. because the variables-bucket was
2275 collapsed or the containing type of a tag (e.g. the class of a method)
2276 was collapsed. So in most cases much more was expanded as needed to
2277 make the current tag visible.
2279 The mechanism of ECB 2.22 and higher only expands the needed parts of
2280 the tree-buffer to make the related node visible: First we try to
2281 highlight the current tag with current expansion-state of the
2282 Methods-buffer. If the node is not visible so the tag can not be
2283 highlighted then we go upstairs the ladder of type-tags the current
2284 tag belongs to (e.g. we expand successive the nodes of the whole
2285 class-hierachy of the current method-tag until the related node
2286 becomes visible). If there is no containing type for the current tag
2287 then the node of the tag is probably contained in a toplevel-bucket
2288 which is currently collapsed; in this case we expand only this
2289 bucket-node and try highlighting again. Only if this has still no
2290 success then we expand the full tree-buffer and try to highlight the
2293 There is another option
2294 @code{ecb-auto-expand-tag-tree-collapse-other}: If this option is set
2295 then auto. expanding the tag-tree collapses all not related nodes.
2296 This means that all nodes which have no relevance for the currently
2297 highlighted node will be collapsed, because they are not necessary to
2298 make the highlighted node visible. This feature is switched off by
2299 default because if always collapses the complete Methods-tree before
2300 the following highlighting of the node for the current tag expands the
2301 needed parts of the tree-buffer.
2304 @node Customizing the display, Rebuilding the Methods, Expanding, The Methods buffer
2305 @subsection Customizing the display of the Methods-buffer
2307 @cindex semantic tag
2309 The ECB-Methods buffer is probably the most important browsing window
2310 offered by ECB. It displays all parsing informations of the current
2311 source-buffer (the buffer displayed in the current active
2314 Normally ECB gets all informations displayed in this Methods-buffer
2315 from the semantic-library - at least for semantic-sources. This
2316 library parses auto. the current source-buffer in the edit-window of
2317 ECB and returns all information in form of @dfn{tags} to ECB which
2318 displays them in a browse-able form in its Method-buffer. See @ref{ECB
2319 Methods-buffer} for information how to use the Methods-buffer.
2321 There are several options to customize which tags ECB should display
2322 in general, if the tags should be collapsed or expanded, how to
2323 fontify them (i.e. syntax-highlighting) and something more.
2327 With the option @code{ecb-show-tags} you specify how ECB should
2328 display the tags returned by the semantic parser. Semantic divides its
2329 tags in several so called @dfn{tag classes}. A tag-class is always a
2330 symbol and can be for example @code{type} (tags which represent a
2331 class@footnote{Do not confuse the term ``class'' in the context of a
2332 tag, which means the class of the tag and which is a semantic-term and
2333 a ``class'' in the context of an object oriented language like Java or
2334 C++! Normally the surrounding context sould be sufficient to
2335 understand which type of ``class'' is meant whenever the term
2336 ``class'' is used in this manual.}, a interface, an enumeration etc.),
2337 @code{function} (tags which represent function or methods),
2338 @code{variable} (variables and attributes), @code{include}
2339 (import-statements) etc. There is no predefined superset of allowed
2340 tag-class-symbols because each language-parser can define its own
2341 tag-classes. But to get an overview of the most common tag-classes see
2342 the default value of the option @code{ecb-show-tags}.
2344 With the option @code{ecb-show-tags} you can now specify how ECB
2345 should display tags of a certain tag-class in a certain major-mode.
2346 You can tell ECB that all tags of a tag-class @code{X} should be
2347 displayed in an expanded bucket and all tags of a tag-class @code{Y}
2348 should be displayed in a collapsed bucket and all tags of a tag-class
2349 @code{Z} should be displayed flattened (means not contained in a
2350 expandable/collapsable bucket-node). These settings can be made
2351 separately for each major-mode but you can also define a
2352 default-display which takes effect when for a major-mode no special
2353 setting can be found in @code{ecb-show-tags}.
2355 For every tag-class you can tell ECB how the tags should be sorted.
2357 @item ecb-font-lock-tags
2358 @itemx ecb-type-tag-display
2359 How to fontify the tags in the Method-buffer
2361 @item ecb-tag-display-function
2362 ECB and semantic offer several predefined functions for displaying the
2363 tags. Here you can customize, what informations tags should
2364 contain (only the method-name or the whole signature or something
2365 else) and what notation should be used, e.g. UML or not.
2369 These are the most important options for this topic but it is
2370 recommended to have a look into the customize-group @code{ecb-methods}
2371 (@pxref{ecb-methods}) and check all the options offered there!
2373 All these options are only relevant for semantic-sources and take no
2374 effect for non-semantic-sources!
2376 @node Rebuilding the Methods, , Customizing the display, The Methods buffer
2377 @subsection Rebuilding the Methods-buffer
2379 In almost all cases there is @strong{NO} need to manually rebuild the
2380 method-buffer, because it is always done automatically if necessary;
2381 the mechanism depends on the sources:
2384 @item semantic-sources:
2385 The command @code{global-semantic-auto-parse-mode} switches on autom.
2386 reparsing of semantic-sources.
2388 @item non-semantic-sources (imenu supported):
2389 You can switch on autom. rescanning/reparsing with the option
2390 @code{imenu-auto-rescan}. But nevertheless you have to manually
2391 rebuild the Method-buffer (with the autom. updated imenu-tags) via the
2392 command @code{ecb-rebuild-methods-buffer} (bound to @kbd{C-c . r}).
2394 @item non-semantic-sources (etags supported):
2395 For these sources there is no built-in auto-rescan mechanism, because
2396 etags is an external tool it can only operate on the saved
2397 file-contents. So rescanning the buffer contents would need to save
2398 the buffer before. Therefore there is no built-in auto-rescan mechanism
2399 because this would always result in saving the buffer and running an
2400 external tool. But of course you can program such a an
2401 etags-auto-rescan mechanism for yourself!
2404 Besides for etags-supported non-semantic-sources there exist a few rare
2405 scenarios also for the other sources where a complete manual rebuild
2406 can be necessary. Here is one example:
2408 Depending on the semantic-version: If an Elisp-file is parsed which
2409 contains a defun X in the middle where the closing ) is missing, then
2410 semantic parses only until this defun X is reached and you will get an
2411 incomplete ECB-method buffer. In such a case you must complete the
2412 defun X and then completely reparse the Elisp-file and rebuild the ECB
2415 A complete manually rebuild is done by
2416 @code{ecb-rebuild-methods-buffer}. For etags-parsed
2417 non-semantic-sources this causes an automatic saving of the
2418 source-buffer because otherwise etags would not operate with the
2421 @node Filtering the tree-buffers, The ECB-layout, The Methods buffer, Usage of ECB
2422 @section Applying filters to the special ECB-tree-buffers
2425 To get a fast and good overlook of the contents of a tree-buffer ECB
2426 offers a filter-mechanism for the Directories-, Sources-, the History-
2427 and the Methods-buffer.
2430 * Filtering Directories:: Applying filters to the Directories-buffer
2431 * Filtering Sources:: Applying filters to the Sources--buffer
2432 * Filtering History:: Applying filters to the History-buffer
2433 * Filtering Methods:: Applying filters to the Methods-buffer
2436 @node Filtering Directories, Filtering Sources, Filtering the tree-buffers, Filtering the tree-buffers
2437 @subsection Applying filters to the Directories-buffer
2439 With the option @code{ecb-excluded-directories-regexps} certain
2440 directories can be excluded from being displayed in the
2441 directories-browser of ECB. This can be done by defining regular
2442 expressions. If the name of a directory matches at least one of the
2443 regexps of this option the directory is not displayed in the
2444 directories-tree-buffer.
2446 The option @code{ecb-sources-exclude-cvsignore} allows to exclude
2447 source-files from the sources-tree-buffer if their name is listed in a
2448 so called @file{.cvsignore}-file. This option is a list of regular
2449 expressions and if a directory-name matches at least one of these
2450 regexps then all files listed in the @file{.cvsignore}-file of this
2451 directory are not displayed in the sources-tree-buffer.
2453 @node Filtering Sources, Filtering History, Filtering Directories, Filtering the tree-buffers
2454 @subsection Applying filters to the Sources-buffer
2456 @subsubsection Interactive Sources-filters
2458 The command @code{ecb-sources-filter} allows to filter these
2459 tree-buffer either by a regular expression or by an extension (e.g.
2460 java, cc, el for java-, c++- rsp elisp-sources). This functionality is
2461 also available via the popup-menu of the Sources-tree-buffer.
2463 The currently applied filter is indicated in the modeline of the
2464 related tree-buffer. Applying a new filter replaces an eventually
2465 already applied filter.
2467 @subsubsection Default Sources-filters
2469 The option @code{ecb-source-file-regexps} allow to specify which
2470 source-files should be displayed and which not. This is done on a
2471 directory-basis, ie. for each directory-regexp the files to display
2472 can be specified. See the documentation of this option for all
2475 In addition to this option you should also know the option
2476 @code{ecb-sources-exclude-cvsignore} (@pxref{Filtering Directories}).
2478 @node Filtering History, Filtering Methods, Filtering Sources, Filtering the tree-buffers
2479 @subsection Applying filters to the History-buffer
2481 @subsubsection Interactive History-filters
2483 The command @code{ecb-history-filter} allows to filter these
2484 tree-buffer either by a regular expression or by an extension (e.g.
2485 java, cc, el for java-, c++- rsp elisp-sources). This functionality is
2486 also available via the popup-menu of the History-tree-buffer.
2488 The currently applied filter is indicated in the modeline of the
2489 related tree-buffer. Applying a new filter replaces an eventually
2490 already applied filter.
2492 @subsubsection Default History-filters
2494 The option @code{ecb-history-exclude-file-regexps} allows to exclude
2495 source-files from being historized (ie. displayed in the
2496 History-buffer). Despite the fact that the History-buffer already
2497 excludes all non-file-buffers there can be still buffers which name
2498 you do not wat to be displayed in the history. These are file-buffer
2499 like @file{TAGS} or @file{semantic.cache} which store
2500 meta-informations used by Emacs and its tools (etags, semantic etc.).
2501 These files can be excluded via
2502 @code{ecb-history-exclude-file-regexps}.
2504 @node Filtering Methods, , Filtering History, Filtering the tree-buffers
2505 @subsection Applying filters to the Methods-buffer
2507 The commands @code{ecb-methods-filter},
2508 @code{ecb-methods-filter-regexp},
2509 @code{ecb-methods-filter-protection},
2510 @code{ecb-methods-filter-tagclass},
2511 @code{ecb-methods-filter-function},
2512 @code{ecb-methods-filter-delete-last},
2513 @code{ecb-methods-filter-nofilter} allows to filter the tags/nodes of
2514 the Methods-buffer by several criterias. As for the Sources- and the
2515 History-buffer the same functionality is also available via the
2516 popup-menu of the Methods-buffer.
2518 @subsubsection Possible filter-criterias
2521 @item Filter by protection:
2522 Just insert the protection you want the Methods-buffer being filtered:
2523 private, protected or public! For sources not supported by semantic
2524 the protection filter will not be offered because these informations
2525 are not available for such sources.
2527 @item Filter by regexp:
2528 Insert the filter as regular expression.
2530 @item Filter by tag-class:
2531 You can filter by tag-classes. The popup-menu contains mode-dependend
2532 tag-filter entries and the command @code{ecb-methods-filter} offers
2533 only the tag-classes of the current mode. This means for sources not
2534 supported by semantic the tag-class filter will not be offered. And
2535 for semantic-supported sources exactly these tag-classes are offered
2536 the semantic-parser for the current major-mode offers. For example
2537 texi-sources can only be filtered by the tag-classes ``Definitions''
2538 and ``Sections'' and java-sources can be filtered by ``Methods'',
2539 ``Variables'', ``Classes'' etc. In general the semantic-variable
2540 @code{semantic-symbol->name-assoc-list} is used to get the right
2543 @item Filter by a filter-function:
2544 Such a function gets two arguments: a tag and the source-buffer of
2545 this tag. If the tag should be displayed (i.e. not being filtered out)
2546 then the function has to return not nil otherwise nil.
2548 @item No special filter:
2549 This means to display all tags specified with the option
2550 @code{ecb-show-tokens}. If currently some of the above filters are
2551 applied they will be all removed.
2553 @item Delete the last added:
2554 This removes only the topmost filter-layer, means that filter added
2558 Be aware that the tag-list specified by the option
2559 @code{ecb-show-tags} is the basis of all filters, i.e. tags which are
2560 excluded by that option will never be shown regardless of the filter
2563 All tags which match the applied filter(s) will be displayed in the
2564 Methods-buffer. Such a filter is only applied to the current
2565 source-buffer, i.e. each source-buffer can have its own tag-filters.
2567 These tag-filters can also applied to sources which are not supported
2568 by the semantic-parser but ``only'' by imenu or etags. But because for
2569 these sources not all information are avaiable the protection- and
2570 tag-class filter are not offered with such ``non-semantic''-sources.
2571 See @ref{Non-semantic sources} for further details about working with
2572 source-files not supported by the semantic-parser.
2575 @subsubsection Inverse Filters
2577 But if @code{ecb-methods-filter} is called with a prefix-argument then
2578 an inverse filter is applied to the Methods-buffer, i.e. all tags
2579 which do @strong{NOT} match the choosen filter will be displayed in
2582 @subsubsection Layered filters
2584 Per default the choosen filter will be applied on top of already
2585 existing filters. This means that filters applied before are combined
2586 with the new filter. This behavior can changed via the option
2587 @code{ecb-methods-filter-replace-existing}.
2589 @subsubsection Display of currently applied filters
2591 The current active filter will be displayed in the modeline of the
2592 Methods-buffer [regexp, prot (= protection), tag-class, function (=
2593 filter-function)]. If an inverse filter has been applied then this is
2594 signalized by a preceding caret ^. If currently more than 1 filter is
2595 applied then always the top-most filter is displayed in the modeline
2596 but the fact of more than 1 filter is visualized by the number of the
2597 filters - included in parens. You can see all currently applied
2598 filters by moving the mouse over the filter-string in modeline of the
2599 Methods-buffer: They will displayed as help-echo.
2601 @subsubsection Default filters for certain files.
2603 The new option @code{ecb-default-tag-filter} allow to define default
2604 tag-filters for certain files which are applied automatically after
2605 loading such a file into a buffer. The possible filters are the same
2606 as offered by the command @code{ecb-methods-filter} and they are
2607 applied in the same manner - the only difference is they are applied
2608 automatically. The files can be specified on a combined major-mode-
2609 and filename-regexp-basis.
2611 Usage-example: This can be used to display in outline-mode files (e.g.
2612 @file{NEWS}) only the level-1-headings by defining a filter regexp
2615 @node The ECB-layout, Hiding the ECB windows, Filtering the tree-buffers, Usage of ECB
2616 @section Changing, customizing, redrawing and creating layouts
2620 The term @dfn{ECB-layout} means in which windows the ECB-frame is
2621 divided. This chapter describes all aspects concerning this layout,
2622 especially changing, customizing, redrawing and also creating new
2626 * Changing the ECB-layout:: How to change and customize the layout
2627 * Redrawing the ECB-layout:: How and when redrawing the layout
2628 * Changing window sizes:: Changing sizes of the ECB-windows
2629 * Fixing window sizes:: Fixing sizes of the ECB-windows
2630 * Creating a new ECB-layout:: Interactively creating new layouts
2633 @node Changing the ECB-layout, Redrawing the ECB-layout, The ECB-layout, The ECB-layout
2634 @subsection Changing and customizing the ECB-layout
2636 ECB offers several predefined layouts with different sets and also
2637 different locations of ECB-windows. See below the ``ascii-screenshot''
2638 of all currently built-in layouts@footnote{The command
2639 @code{ecb-show-layout-help'} shows the outline-picture for all built-in
2642 In addition to these predefined layouts you can either interactively
2643 create new layouts ``by example'' (@pxref{Creating a new ECB-layout})
2644 or program new layouts with the macro @code{ecb-layout-define}
2645 (@pxref{The layout-engine}). The former method is the recommended
2648 There are two ways to interactively change the layout:
2650 @item Changing permanently:
2651 Customize the option @code{ecb-layout-name} and store it for future
2654 @item Switching between several layouts at runtime:
2655 If you want to switch fast between a certain sequence of layouts see
2656 the option @code{ecb-toggle-layout-sequence} and the command
2657 @code{ecb-toggle-layout} (@pxref{Simulating speedbar}). For just
2658 selecting another layout during current Emacs-session use the command
2659 @code{ecb-change-layout}.
2662 With the option @code{ecb-show-sources-in-directories-buffer} you can
2663 define if sources are displayed in the directory-window of a layout
2664 (@pxref{ECB Directories-buffer}).
2666 In addition to the general layout you can specify if the layout should
2667 contain a durable compilation-window at the bottom of the frame, see
2668 @code{ecb-compile-window-height} (@pxref{Temp- and compile-buffers}).
2670 Maybe you want also change the look&feel of the tree-buffers. Then you
2671 can change the general style of the tree-buffers with the option
2672 @code{ecb-tree-buffer-style} and the location of the collapse- and
2673 expand-symbols and the indentation of sub-nodes in a tree. See
2674 @code{ecb-tree-indent} and @code{ecb-tree-expand-symbol-before}. More
2675 details about the different tree-buffer-styles are described in
2676 @ref{Tree-buffer styles}.
2678 Here are all currently available layouts (for creating own new layouts
2679 see @ref{Creating a new ECB-layout}); just customize the option
2680 @code{ecb-layout-name} to the related name:
2683 @item Layout ``left1''
2686 -------------------------------------------------------
2694 | Sour | Hist | Edit |
2702 -------------------------------------------------------
2706 -------------------------------------------------------
2710 @item Layout ``left2''
2713 -------------------------------------------------------
2721 |--------------| Edit |
2729 -------------------------------------------------------
2733 -------------------------------------------------------
2737 @item Layout ``left3''
2740 -------------------------------------------------------
2756 -------------------------------------------------------
2760 -------------------------------------------------------
2764 @item Layout ``left4''
2767 -------------------------------------------------------
2775 |--------------| Edit |
2783 -------------------------------------------------------
2787 -------------------------------------------------------
2791 @item Layout ``left5''
2794 -------------------------------------------------------
2810 -------------------------------------------------------
2814 -------------------------------------------------------
2818 @item Layout ``right1''
2821 -------------------------------------------------------
2837 -------------------------------------------------------
2841 -------------------------------------------------------
2845 @item Layout ``left6''
2848 -------------------------------------------------------
2860 -------------------------------------------------------
2864 -------------------------------------------------------
2868 @item Layout ``top1''
2871 -------------------------------------------------------
2874 | Directories | Sources | Methods |
2877 |-----------------------------------------------------|
2887 -------------------------------------------------------
2891 -------------------------------------------------------
2895 @item Layout ``left7''
2898 -------------------------------------------------------
2906 |--------------| Edit |
2914 -------------------------------------------------------
2918 -------------------------------------------------------
2922 @item Layout ``left8''
2925 -------------------------------------------------------
2933 |--------------| Edit |
2941 -------------------------------------------------------
2945 -------------------------------------------------------
2949 @item Layout ``top2''
2952 -------------------------------------------------------
2958 |-----------------------------------------------------|
2968 -------------------------------------------------------
2972 -------------------------------------------------------
2976 @item Layout ``left9''
2979 -------------------------------------------------------
2995 -------------------------------------------------------
2999 -------------------------------------------------------
3003 @item Layout ``left10''
3006 -------------------------------------------------------
3020 -------------------------------------------------------
3024 -------------------------------------------------------
3028 @item Layout ``left11''
3031 -------------------------------------------------------
3045 -------------------------------------------------------
3049 -------------------------------------------------------
3053 @item Layout ``left12''
3056 -------------------------------------------------------
3072 -------------------------------------------------------
3076 -------------------------------------------------------
3080 @item Layout ``left13''
3083 -------------------------------------------------------
3091 | Directories | Edit |
3099 -------------------------------------------------------
3103 -------------------------------------------------------
3107 @item Layout ``left14''
3110 -------------------------------------------------------
3114 | Directories | Edit |
3124 -------------------------------------------------------
3128 -------------------------------------------------------
3132 @item Layout ``left15''
3135 -------------------------------------------------------
3143 |--------------| Edit |
3151 -------------------------------------------------------
3155 -------------------------------------------------------
3159 @item Layout ``leftright1''
3162 -------------------------------------------------------
3164 | Directories | | Methods |
3170 |-------------| Edit | |
3178 -------------------------------------------------------
3182 -------------------------------------------------------
3186 @item Layout ``leftright2''
3189 -------------------------------------------------------
3191 | Directories | | Methods |
3198 |-------------| |-------------|
3200 | Sources | | History |
3205 -------------------------------------------------------
3209 -------------------------------------------------------
3213 @item Layout ``leftright3''
3216 -------------------------------------------------------
3218 | Directories | | Methods |
3232 -------------------------------------------------------
3236 -------------------------------------------------------
3240 @item Layout ``left-dir-plus-speedbar''
3243 -------------------------------------------------------
3259 -------------------------------------------------------
3263 -------------------------------------------------------
3269 @node Redrawing the ECB-layout, Changing window sizes, Changing the ECB-layout, The ECB-layout
3270 @subsection Redrawing the ECB-layout
3273 If you have unintentionally destroyed the ECB-layout, you can always
3274 restore the layout with calling @code{ecb-redraw-layout}. This is even
3275 true, if you get messages like ``wrong-type-argument window-live-p
3278 If the variable @code{ecb-redraw-layout-quickly} is not nil then the redraw
3279 is done by the @code{ecb-redraw-layout-quickly} function, otherwise by
3280 @code{ecb-redraw-layout-full}. But it's strongly recommended to use the
3281 quick redraw only if you have really slow machines where a full redraw
3282 takes several seconds because the quick redraw is not really safe and
3283 may have some drawbacks! On normal machines the full redraw should be
3286 Please read the documentation of the command @code{ecb-redraw-layout}!
3288 See also the hooks @code{ecb-redraw-layout-after-hook} and
3289 @code{ecb-redraw-layout-before-hook}!
3291 @node Changing window sizes, Fixing window sizes, Redrawing the ECB-layout, The ECB-layout
3292 @subsection Changing the sizes of the special ECB-windows
3294 The standard width and height of the special ECB-windows is defined
3295 with the options @code{ecb-windows-width} and
3296 @code{ecb-windows-height}. But changing these options always
3297 influences all layouts which is not always desired.
3299 ECB offers to re-adjust the width and height of the ECB-windows (e.g. by
3300 dragging the windows-borders via the mouse) and then saving exactly
3301 these current window-sizes for the current layout so after activating
3302 this layout all windows have autom. the stored sizes.
3304 This is done via the option @code{ecb-layout-window-sizes} and the
3305 commands @code{ecb-store-window-sizes},
3306 @code{ecb-restore-window-sizes} and
3307 @code{ecb-restore-default-window-sizes}.
3309 Here is an example how to resize and store the sizes of the
3310 ECB-windows of layout ``left1'':
3314 Switch to layout ``left1'' via @code{ecb-change-layout} (@kbd{C-c . lc})
3316 Resize the ECB-windows by dragging the window-borders with the mouse
3318 Call @code{ecb-store-window-sizes}
3321 After this layout ``left1'' will be always drawn with the new sizes
3322 until you call @code{ecb-restore-default-window-sizes} during layout
3323 ``left1'' is active.
3325 @strong{Please note}: @code{ecb-store-window-sizes} stores the width
3326 and height of the windows per default as fractions of the width (rsp.
3327 height) of the ECB-frame, so the stored sizes are always correct
3328 regardless of the current frame-size! But if called with a prefix
3329 argument then fixed sizes are stored.
3331 @node Fixing window sizes, Creating a new ECB-layout, Changing window sizes, The ECB-layout
3332 @subsection Fixing the sizes of the special ECB-windows
3334 GNU Emacs 21 introduced a new feature which can fix the sizes of a
3335 window displaying a certain buffer even after resizing the frame. This
3336 new feature is driven by the new buffer-local variable
3337 @code{window-size-fixed}.
3339 ECB offers an option @code{ecb-fix-window-size} for fixing the sizes
3340 of the special ECB-windows/buffers even after frame-resizing. The fix
3341 type (valid values are @code{nil}, @code{t}, @code{width} and
3342 @code{height}) can either be set on a layout-basis (means a different
3343 value for each layout) or one value can be set for all layouts. In the
3344 latter case there is an additional value @code{auto} which choose
3345 autom. the senseful fix-type depending on the current layout-type: For
3346 top-layouts the fix-type @code{height} and for all other layout-types
3347 the fix-type @code{width}.
3349 Probably the most senseful value is @code{auto} for all layouts
3350 because it makes less sense to fix the height of the ecb-windows in a
3351 left-, right- or leftright-layout. Same for fixing the width in a
3354 Note: With current Emacs 21.2.X there seems to be no distinction
3355 between @code{width}, @code{height} and @code{t}. Therefore this
3356 option takes no effect (means all ecb-windows have always unfixed
3357 sizes) if @code{ecb-compile-window-height} is not @code{nil}.
3359 @node Creating a new ECB-layout, , Fixing window sizes, The ECB-layout
3360 @subsection Interactively creating new layouts
3363 @cindex Creating new layouts
3365 If you want to create your own ECB-layout then you can do this very
3366 easy ``by example'' with the command @code{ecb-create-new-layout}.
3367 This command creates a new empty frame and offers a small set of keys
3368 to create the new layout by splitting windows.
3369 @code{ecb-create-new-layout} and this couple of keys are your guide
3370 during the layout-creation-process@footnote{During the creation
3371 process you will be asked in the minibuffer for several options; here
3372 you can use TAB-completion and an ``empty'' RET chooses always the
3375 After calling @code{ecb-create-new-layout} you will be asked which
3376 type of layout you want to create: ``left'', ``right'', ``top'' or
3377 ``left-right''. Here you specify where the ECB-tree-windows/buffers
3378 should be located in the ECB-frame:
3381 @item left: All ECB-tree-windows are located on the left side
3382 @item right: All ECB-tree-windows are located on the right side
3383 @item top: All ECB-tree-windows are located on the top side
3384 @item left-right: All ECB-tree-windows are located on the left and
3388 Depending on the type you choose the window is splitted by the values
3389 of the options @code{ecb-windows-width} (types ``left'', ``right'' and
3390 ``left-right'') or @code{ecb-windows-height} (type ``top'').
3392 Afterwards you will see a frame like follows (here the layout-type is
3397 -----------------------------------------------------------------
3399 | | ECB-layout creation mode | |
3400 | | ======================== | |
3402 | | <This is a durable help-screen> | |
3413 -----------------------------------------------------------------
3416 `---| Splitted by the value of @code{ecb-windows-width}.
3421 The big window (here the middle window) will be the edit-area of the
3422 new layout and can not be selected, deleted or splitted during the
3423 creation process. It displays the help-screen for the layout-creation
3424 mode. Here all the available commands are displayed.
3426 The small window(s) (here the left and right windows) can be splitted
3427 by you wherever you want (@kbd{C-s}). The left one contains the point.
3428 You must give every ECB-tree-window you create a type (@kbd{C-t})
3432 @item One of the built-in types
3434 This can be either ``directories'', ``sources'', ``methods'',
3435 ``history'' or ``speedbar''.
3437 @item Any user-defined type:
3439 In this case you insert ``other'' after hitting @kbd{C-t} and you will
3440 then be asked for the name of the user-defined type. You can insert
3441 any arbitrary type name X. But to get this layout working you have to
3442 define a function with name @code{ecb-set-X-buffer} whereas X is the
3443 name of the user-defined type you have specified during
3446 This function @code{ecb-set-X-buffer} has first to switch to the
3447 buffer you want to display in this window and then making this window
3448 dedicated. You have to use the macro @code{ecb-with-dedicated-window}
3451 Here is an example: Suppose you have inserted as type name ``example''
3452 then you have to define and load a function
3453 @code{ecb-set-example-buffer} which could be defined like follows:
3456 (defun ecb-set-example-buffer ()
3457 (ecb-with-dedicated-window
3458 " *ECB example-buffer*"
3459 'ecb-set-example-buffer
3460 (switch-to-buffer (get-buffer-create " *ECB example-buffer*"))))
3463 If you forget to define such a function for the user-defined type then
3464 nevertheless ECB will draw this layout but it will use the
3465 default-function @code{ecb-set-default-ecb-buffer} instead.
3468 If you are satisfied with your new layout just hit @kbd{C-q}. You will
3469 be asked for a new layout-name (TAB-completion is offered to get a
3470 list of all names already in use) and after inserting a new(!) name
3471 the new layout is saved in the file defined by the option
3472 @code{ecb-create-layout-file}. The new layout is now available via the
3473 option @code{ecb-layout-name}.
3475 There is no need for you to load the file
3476 @code{ecb-create-layout-file} manually into your Emacs because it's
3477 automatically loaded by ECB!
3479 @strong{Please note}: During the layout-creation process only the
3480 commands displayed in the help-screen are available. ALL other
3481 commands are temporally disabled (even the mouse-commands).
3483 For programming new layouts with emacs-lisp see @ref{The layout-engine}.
3485 With the command @code{ecb-delete-new-layout} you can delete
3486 previously created layouts (TAB-completion is offered for all names of
3487 user created layouts).
3489 @node Hiding the ECB windows, Maximizing the ECB windows, The ECB-layout, Usage of ECB
3490 @section Hiding/Showing the ECB windows
3492 @cindex Hide windows
3493 @cindex Show windows
3494 With @code{ecb-toggle-ecb-windows}, @code{ecb-hide-ecb-windows} and
3495 @code{ecb-show-ecb-windows} you can hide/show all the ECB windows
3496 without changing the activation state of ECB and also without
3497 deactivating the advices for @code{delete-other-windows} and/or
3498 @code{delete-window}. This is most useful if you use a layout like
3499 ``top2'' (@pxref{Tips and tricks}) or if you want to have maximum space
3500 for editing and you don't need the browsing windows all the time.
3502 The following sequence of hooks is evaluated during showing again the
3505 @item @code{ecb-show-ecb-windows-before-hook}
3506 @item @code{ecb-redraw-layout-before-hook}
3507 @item <Redrawing the layout to show the hidden ECB-windows>
3508 @item @code{ecb-redraw-layout-after-hook}
3509 @item @code{ecb-show-ecb-windows-after-hook}
3512 The following sequence of hooks is evaluated during hiding the
3515 @item @code{ecb-hide-ecb-windows-before-hook}
3516 @item @code{ecb-redraw-layout-before-hook}
3517 @item <Hiding the ECB-windows>
3518 @item @code{ecb-redraw-layout-after-hook}
3519 @item @code{ecb-hide-ecb-windows-after-hook}
3522 If the special ECB-windows are hidden (e.g. by
3523 `ecb-toggle-ecb-windows') all adviced functions behave as their
3524 originals. So the frame can be used as if ECB would not be active but
3525 ECB IS still active in the ``background'' and all ECB-commands and all
3526 ECB-keybindings can be used. Of course some of them doesn't make much
3527 sense but nevertheless they can be called. Toggling the visibility of
3528 the ECB-windows preserves the splitting-state of the edit-area: If you
3529 hide the ECB-windows then the frame will be divided in the same
3530 window-layout the edit-area had before the hiding and if you show the
3531 ECB-windows again the edit-area will be divided into all the
3532 edit-windows the ECB-frame had before the showing.
3534 Therefore it should be enough to hide the ECB-windows to run other
3535 Emacs-applications which have their own window-layout-managing. There
3536 should be no conflicts. But nevertheless the most recommended method
3537 for running ECB and other applications (e.g. xrefactory, Gnus etc.) in
3538 the same frame is to use a window-manager like winring.el or
3539 escreen.el (@pxref{Window-managers and ECB}).
3542 @node Maximizing the ECB windows, Back/forward navigation, Hiding the ECB windows, Usage of ECB
3543 @section Maximizing the ECB windows
3545 To get a better overlook about the contents of a certain ECB-window
3546 every ECB-window can be ``maximized'', means all other ECB-windows are
3547 deleted so only the edit-window(s) and this maximized ECB-window are
3548 visible (and maybe a compile-window if active). There are several ways
3553 Via the popup-menus of the ECB-windows
3556 Via the main ``ECB''-menu and here ``Display window maximized''
3559 Via calling the adviced version of
3560 @code{delete-other-windows}@footnote{This command is adviced per
3561 default, see @ref{The edit-area}.} (bound to @kbd{C-x 1}) in one of
3565 Via one of the commands @code{ecb-maximize-window-directories},
3566 @code{ecb-maximize-window-sources}, @code{ecb-maximize-window-methods},
3567 @code{ecb-maximize-window-history} or
3568 @code{ecb-maximize-window-speedbar} or the bound short-cuts for those
3572 Via the new command @code{ecb-cycle-maximized-ecb-buffers} which
3573 cycles through all ecb-buffers of current layout by maximizing exactly
3574 one of the ecb-windows after every cycle-step.
3577 Via the option @code{ecb-maximize-ecb-window-after-selection} and then
3578 just by selecting an ECB-window. ``Deselecting'' an ECB-window brings
3579 back all ECB-windows of current layout.
3582 Via the default modeline-mechanisms for deleting other windows. GNU
3583 Emacs binds @kbd{mouse-2} in its modeline to
3584 @code{delete-other-window}. ECB now supports this mechanism by binding
3585 a toggle-command to @kbd{mouse-2} in the modeline of each tree-buffer:
3586 If all ECB-windows are visible then this command maximizes the current
3587 tree-window and if current tree-window is maximized all ECB-windows
3588 are displayed again. XEmacs binds a popup-menu with some window
3589 commands to @kbd{button-3} in its modeline. ECB supports this
3590 mechanism by replacing this menu by a menu which offers exactly 2
3591 commands: Maximizing current tree-window and displaying all
3595 Minimizing such a maximized ECB-window, i.e. bringing back to its
3596 original size, can simply be done by redrawing the layout via the
3597 command @code{ecb-redraw-layout} (bound to @kbd{C-c . lr}).
3599 @node Back/forward navigation, ECB-window synchronizing, Maximizing the ECB windows, Usage of ECB
3600 @section Back- and forward navigation like a browser
3602 With ECB you can ``browse'' in your source-files like with a
3603 web-browser. This means ECB stores the current buffer- and
3604 window-position relative to the current tag@footnote{e.g. a method,
3605 a variable or any other semantic tag} in the edit-window after
3608 @item selecting a tag in the ECB-methods buffer or
3609 @item selecting a source-file in the ECB-sources/history-buffer.
3612 ECB offers two commands @code{ecb-nav-goto-next} (@kbd{C-c . n}) and
3613 @code{ecb-nav-goto-previous} (@kbd{C-c . p}) to go forward and
3614 backward within this navigation history-list. These commands are also
3615 available via the menu ``ECB --> Navigate''.
3617 Aside normal ``location-browsing'' this is useful for example in a
3618 scenario where the buffer is narrowed to a tag (see
3619 @code{ecb-tag-visit-post-actions}):
3622 @item You edit a function
3623 @item Goto another function above the current in the same file
3624 @item Add a few lines
3625 @item Call ecb-nav-goto-previous
3627 Now you will edit at the same place in the function.
3630 @node ECB-window synchronizing, Stealthy background tasks, Back/forward navigation, Usage of ECB
3631 @section Synchronization of the ECB-windows
3633 Per default ECB synchronizes automatically the contents of the
3634 ECB-windows/tree-buffers with the current active edit-window (rsp. the
3635 current buffer of the edit window):
3639 @item ECB-directories:
3641 This windows is synchronized to display the directory where the
3642 source-file which is displayed in the current active edit-window is
3643 located. If the source-path (i.e. an element of the option
3644 @code{ecb-source-path}) containing this directory is not expanded it
3645 will be auto. expanded according to the value of the option
3646 @code{ecb-auto-expand-directory-tree} (@pxref{ecb-directories}).
3650 The ECB-sources-buffer contains after synchronizing all the sources of
3651 the directory of the ``current'' source-file displayed in the
3652 edit-window. The entry of the ``current'' source-file is highlighted.
3656 Contains after synchronizing all the tags of the buffer in the current
3657 selected edit-window, i.e. all methods, variables etc... depending of
3662 Highlights the entry of the buffer displayed in the current active
3663 edit-window if this buffer is a source-file.
3667 This feature can be customized with the option @code{ecb-window-sync}:
3669 If active then the synchronization takes place always a buffer changes
3670 in an edit window or if another edit-window with another buffer will
3671 be selected, if deactivated then never. But you can also set this
3672 option to a list of major-modes and then the sync. will only be done
3673 if the major-mode of the current buffer belongs NOT to this list.
3675 But in every case the synchronization takes only place if the
3676 major-mode of the current-buffer in the current selected edit-window
3677 has a relation to files or directories. Examples for the former one
3678 are all programming-language-modes like @code{c++-mode} or
3679 @code{java-mode}, @code{Info-mode} too, an example for the latter one
3680 is @code{dired-mode}. For all major-modes related to
3681 non-file/directory-buffers like @code{help-mode},
3682 @code{customize-mode} and others never a synchronization will be done!
3684 It's recommended to exclude at least @code{Info-mode} because it makes
3685 no sense to synchronize the ECB-windows after calling the Info help.
3686 Per default also @code{dired-mode} is excluded but it can also making
3687 sense to synchronize the ECB-directories/sources windows with the
3688 current directory of the dired-buffer in the edit-window.
3690 If you often need to toggle between autom. synchronization on and off
3691 then customizing the option @code{ecb-window-sync} is inefficient and
3692 therefore ECB offers the command @code{ecb-toggle-window-sync}.
3694 @strong{Please note}: With the command @code{ecb-window-sync} you can
3695 do a manually synchronization if the automatic one is switched off or
3696 if you just want to do this!
3698 @node Stealthy background tasks, Interactive ECB commands, ECB-window synchronizing, Usage of ECB
3699 @section Stealthy background-tasks of ECB
3701 ECB performs some tasks stealthy in the background and also
3702 interruptable by the user because these tasks can be time-consuming
3703 and could otherwise block ECB. Currently the following tasks are
3704 performed stealthy and in the background by ECB:
3707 @item Prescann directories for emptyness
3708 Prescann directories and display them as empty or not-empty in the
3709 directories-buffer. See the documentation of the option
3710 @code{ecb-prescan-directories-for-emptyness} for a description.
3712 @item File is read only
3713 Check if sourcefile-items of the directories- or sources-buffer are
3714 read-only or not. See documentation of the option
3715 @code{ecb-sources-perform-read-only-check}.
3717 @item Version-control-state
3718 Checks the version-control-state of files in directories which are
3719 managed by a VC-backend. See the option @code{ecb-vc-enable-support}.
3723 All of these tasks (e.g. checking if a directory is empty or not)
3724 perform a certain action for all directories or sources displayed in
3725 the current visible tree-buffers of ECB. Normally there should be no
3726 annoying delay for the user because each of these tasks will be only
3727 performed when Emacs is idle and will be interrupted immediatelly when
3728 a user hits a key or clicks the mouse but especially for
3729 remote-directories one single action (e.g. checking if a certain
3730 directory is empty or checking the VC-state of a sourcefile in such a
3731 remote directory) can be very time-consuming and such a single action
3732 is not interruptable (an interrupt can only occur between the
3733 single-actions for two directories or sources) For a further
3734 discussion how to deal best with remote directories see @ref{Remote
3737 ECB offers for all stealthy tasks three steps of activation:
3740 Switch on this feature.
3742 @item @code{unless-remote}:
3743 Switch on this feature but not for remote directories. The term
3744 ``remote'' means here directories which are used via tramp, ange-ftp
3745 or efs. So mounted directories are counted not as remote directories
3746 here even if such a directory is maybe hosted on a remote machine. But
3747 normally only directories in a LAN are mounted so there should be no
3748 performance-problems with such mounted directories.
3751 Switch off this feature completely.
3754 In combination with the option @code{ecb-stealthy-tasks-delay} these
3755 three choices allows already adapting the stealthy tasks to most
3756 needs. But to offer finest granularity for which directories a certain
3757 stealthy task should be switched on and for which not ECB offers for
3758 every stealthy task an additional option which allows a finer
3762 @item Prescanning directories for emptyness:
3763 @code{ecb-prescan-directories-exclude-regexps}.
3765 @item Checking the read-only-state of a sourcefile:
3766 @code{ecb-read-only-check-exclude-regexps}
3768 @item Checking the VC-state of sourcefiles:
3769 @code{ecb-vc-directory-exclude-regexps}
3772 These options take only effect when the related task is not completely
3773 switched off but then they allow excluding certain directories (or the
3774 sources of directories) from being processed by a certain stealthy
3777 @node Interactive ECB commands, ,Stealthy background tasks, Usage of ECB
3778 @section Interactive ECB commands
3781 ECB offers a lot of interactive commands. Some of these commands
3782 prompt the user in the minibuffer if called with a prefix argument.
3784 Example: If @code{ecb-clear-history} is called with a prefix argument
3785 then you will be prompted in the minibuffer with:
3788 Clear from history: [all, not-existing-buffers, existing-buffers]
3791 You can choose one of the options enclosed in brackets with
3792 TAB-completion; hitting RET direct after the prompt chooses auto. the
3793 first offered option (in the example above ``all'').
3795 @strong{Please note}: The following interactive commands of ECB are
3796 listed without the prefix ``ecb-'' (e.g. the command
3797 @code{ecb-activate} is listed with name ``activate''). This has been
3798 done for a better readable command index. @xref{Command Index}.
3800 @deffn Command activate
3801 Activates ECB and creates the special buffers for the choosen layout.
3802 For the layout see @code{ecb-layout-name}. This function raises always
3803 the ECB-frame if called from another frame. This is the same as
3804 calling @code{ecb-minor-mode} with a positive argument.
3807 @deffn Command add-all-buffers-to-history
3808 Add all current file-buffers to the history-buffer of ECB. Dependend
3809 on the value of @code{ecb-history-sort-method} afterwards the history
3810 is sorted either by name or by extension. If
3811 @code{ecb-history-sort-method} is nil the most recently used buffers
3812 are on the top of the history and the seldom used buffers at the
3818 @deffn Command change-layout &optional preselect-type
3819 Select a layout-name from all current available layouts
3820 (TAB-completion is offered) and change the layout to the selected
3821 layout-name. If optional argument PRESELECT-TYPE is not nil then you
3822 can preselect a layout-type \(TAB-completion is offered too) and then
3823 you will be asked only for layouts of that preselected type. Note:
3824 This function works by changing the option @code{ecb-layout-name} but
3825 only for current Emacs-session.
3828 @deffn Command clear-history
3829 Clears the history-buffer.
3832 @deffn Command customize
3833 Open a customize-buffer for all customize-groups of ECB.
3836 @deffn Command customize-most-important
3837 Open a customize-buffer for the most important options of ECB.
3840 @deffn Command create-new-layout
3841 Start process for interactively creating a new ECB-layout
3842 (@pxref{Creating a new ECB-layout}).
3845 @deffn Command cycle-maximized-ecb-buffers
3846 Cycles through all ecb-buffers of current layout by maximizing exactly
3847 one of the ecb-windows after every cycle-step.
3850 @deffn Command cycle-through-compilation-buffers &optional choose-buffer
3851 Cycle through all compilation buffers currently open and display them
3852 within the compilation window @code{ecb-compile-window}. If the
3853 currently opened buffer within the compilation window is not a
3854 compilation buffer, we jump to the first compilation buffer. If not we
3855 try to loop through all compilation buffers. If we hit the end we go
3856 back to the beginning.
3858 If @var{CHOOSE-BUFFER} is not @code{nil} then the user will be
3859 prompted for the compilation-buffer to switch to.
3862 @deffn Command deactivate
3863 Deactivates the ECB and kills all ECB buffers and windows.
3866 @deffn Command delete-new-layout
3867 Select a layout-name for a layout created by
3868 @code{ecb-create-new-layout} and delete this layout. This means the
3869 layout-definition is removed from the file
3870 @code{ecb-create-layout-file} and the layout-function and associated
3871 aliases are unbound.
3874 @deffn Command display-news-for-upgrade &optional FULL-NEWS
3875 Display the most important NEWS after an ECB-upgrade. If you call this
3876 function but no ECB-upgrade has been performed before starting ECB
3877 then nothing is display unless @var{FULL-NEWS} is not nil.
3879 If @var{FULL-NEWS} is not nil then the NEWS-file is displayed in
3883 @deffn Command display-upgraded-options
3884 Display a information-buffer which options have been upgraded or
3885 reset. Offers two buttons where the user can decide if the upgraded
3886 options should also being saved by ECB for future settings or if the
3887 buffer should be killed.
3889 If saving is possible this command display where the options would be
3890 saved. It is that file Emacs uses to save customize-settings. This
3891 file is ``computed'' from the settings in @code{custom-file} and
3892 @code{user-init-file} (see the documentation of these variables).
3894 ECB automatically makes a backup-file of that file which will be
3895 modified by storing the upgraded rsp. renamed ECB-options. This backup
3896 file gets a unique name by adding a suffix ``.before_ecb_<version>''
3897 to the name of the modified file. If such a file already exists ECB
3898 adds a unique number to the end of the filename to make the filename
3899 unique. This is a safety mechanism if something fails during storing
3900 the upgraded options, so you never lose the contents of your
3905 @deffn Command download-ecb
3906 Download ECB from the ECB-website and install it. For this the option
3907 @code{ecb-download-url} must be set correct, whereas the default value of
3908 this option should always be correct.
3910 If @code{ecb-download-package-version-type} is set to -1 (means asking
3911 for a version) then you will be ask in the minibuffer for the version
3912 to download. Otherwise ECB downloads autom. the latest version
3913 available for the type specified in
3914 @code{ecb-download-package-version-type}. If no newer version than the
3915 current one is available no download will be done.
3917 For details about downloading and what requirements must be satisfied
3918 see function @code{ecb-package-download} and option
3919 @code{ecb-download-package-version-type}!
3921 After successful downloading the new ECB will be installed in a
3922 subdirectory of @code{ecb-download-install-parent-dir}. After adding
3923 this subdirectory to @code{load-path} and restarting Emacs the new ECB
3924 version can be activated by @code{ecb-activate}.
3926 If current running ECB is installed as regular XEmacs-package and not
3927 with the archive available at the ECB website then this function asks
3931 @deffn Command download-semantic
3932 Download semantic from the semantic-website and install it. For this
3933 the variable @code{ecb-cedet-url} must be set correct,
3934 whereas the default value of this variable should always be correct.
3936 If @code{ecb-download-package-version-type} is set to -1 (means asking
3937 for a version) then you will be ask in the minibuffer for the version
3938 to download. Otherwise ECB downloads autom. the latest version
3939 available for the type specified in
3940 @code{ecb-download-package-version-type}. If no newer version than the
3941 current one is available no download will be done.
3943 For details about downloading and what requirements must be satisfied
3944 see function @code{ecb-package-download} and option
3945 @code{ecb-download-package-version-type}!
3947 After successful downloading the new semantic will be installed in a
3948 subdirectory of @code{ecb-download-install-parent-dir}. After adding
3949 this new subdirectory to @code{load-path} and restarting Emacs the new
3950 semantic version is loaded and is used after next start of ECB.
3952 If current running semantic is installed as regular XEmacs-package and
3953 not with the archive available at the semantic website then this
3954 function asks for proceeding!
3957 @deffn Command expand-methods-nodes &optional force-all
3958 Set the expand level of the nodes in the ECB-methods-buffer.
3960 This command asks in the minibuffer for an indentation level LEVEL. With this
3961 LEVEL you can precisely specify which level of nodes should be expanded. LEVEL
3962 means the indentation-level of the nodes.
3964 A LEVEL value X means that all nodes with an indentation-level <= X are
3965 expanded and all other are collapsed. A negative LEVEL value means all visible
3966 nodes are collapsed.
3968 Nodes which are not indented have indentation-level 0!
3970 Which node-types are expanded (rsp. collapsed) by this command
3971 depends on the options @code{ecb-methods-nodes-expand-spec} and
3972 @code{ecb-methods-nodes-collapse-spec}! With optional argument
3973 @var{FORCE-ALL} all tags will be expanded/collapsed regardless of
3974 the values of these options.
3979 expands only nodes which have no indentation itself.
3981 expands nodes which are either not indented or indented indented once
3984 should normally expand all nodes expect there are nodes which are
3985 indented deeper than 10.
3988 Note 1: This command switches off auto. expanding of the method-buffer
3989 if @code{ecb-expand-methods-switch-off-auto-expand} is not nil. But it
3990 can be switched on again quickly with
3991 @code{ecb-toggle-auto-expand-tag-tree} or @kbd{[C-c . a]}.
3993 Note 2: All this is only valid for file-types parsed by semantic. For
3994 other file types which are parsed by imenu or etags (see
3995 @code{ecb-process-non-semantic-files}) @var{FORCE-ALL} is always true!
3998 @deffn Command dump-semantic-toplevel
3999 Dump the current semantic-tags in special buffer and display them.
4003 @deffn Command eshell-current-buffer-sync
4004 Synchronize the eshell with the directory of current source-buffer.
4005 This is only done if the eshell is currently visible in the
4006 compile-window of ECB and if either this function is called
4007 interactively or @code{ecb-eshell-synchronize} is not nil.
4010 @deffn Command eshell-recenter
4011 Recenter the eshell window so that the prompt is at the buffer-end.
4014 @deffn Command expand-directory-nodes
4015 Set the expand level of the nodes in the ECB-directories-buffer. For
4016 argument LEVEL see @code{ecb-expand-methods-nodes}.
4018 Be aware that for deep structured paths and a lot of source-paths this
4019 command can last a long time - depending of machine- and
4023 @deffn Command goto-window-compilation
4024 Goto the ecb compilation window @code{ecb-compile-window}.
4027 @deffn Command goto-window-directories
4028 Make the ECB-directories window the current window. If
4029 @code{ecb-use-speedbar-instead-native-tree-buffer} is @code{dir} then
4030 goto to the speedbar-window.
4033 @deffn Command goto-window-edit1
4034 Make the (first) edit-window window the current window.
4037 @deffn Command goto-window-edit2
4038 Make the second edit-window (if available) window the current window.
4041 @deffn Command goto-window-edit-last
4042 Make the last selected edit-window window the current window. This is
4043 the same as if @code{ecb-mouse-click-destination} is set to
4048 @deffn Command goto-window-history
4049 Make the ECB-history window the current window.
4052 @deffn Command goto-window-methods
4053 Make the ECB-methods window the current window. If
4054 @code{ecb-use-speedbar-instead-native-tree-buffer} is @code{method}
4055 then goto to the speedbar-window.
4058 @deffn Command goto-window-sources
4059 Make the ECB-sources window the current window. If
4060 @code{ecb-use-speedbar-instead-native-tree-buffer} is @code{source}
4061 then goto to the speedbar-window.
4064 @deffn Command history-filter
4065 Apply a filter to the history-buffer to reduce the number of entries.
4066 So you get a better overlooking. There are three choices:
4069 @item Filter by extension:
4070 Just insert the extension you want the History-buffer being filtered.
4071 Insert the extension without leading dot!
4073 @item Filter by regexp:
4074 Insert the filter as regular expression.
4077 This means to display an entry for all currently living file-buffers.
4083 @deffn Command jde-display-class-at-point
4084 Display in the ECB-methods-buffer the contents (methods, attributes
4085 etc...) of the class which contains the definition of the ``thing''
4086 under point (this can be a variable-name, class-name, method-name,
4087 attribute-name). This function needs the same requirements to work as
4088 the method-completion feature of JDEE (see
4089 @code{jde-complete})!. The source-file is searched first in
4090 @code{jde-sourcepath}, then in @code{jde-global-classpath}, then in
4091 @var{$CLASSPATH}, then in current-directory.
4093 Works only for classes where the source-code (i.e. the *.java-file) is
4097 @deffn Command maximize-window-directories
4098 Maximize the ECB-directories-window, i.e. delete all other
4099 ECB-windows, so only one ECB-window and the edit-window(s) are visible
4100 (and maybe a compile-window). Works also if the ECB-directories-window
4101 is not visible in current layout.
4104 @deffn Command maximize-window-sources
4105 Maximize the ECB-sources-window, i.e. delete all other ECB-windows, so
4106 only one ECB-window and the edit-window(s) are visible (and maybe a
4107 compile-window). Works also if the ECB-sources-window is not visible
4111 @deffn Command maximize-window-methods
4112 Maximize the ECB-methods-window, i.e. delete all other ECB-windows, so
4113 only one ECB-window and the edit-window(s) are visible (and maybe a
4114 compile-window). Works also if the ECB-methods-window is not visible
4118 @deffn Command maximize-window-history
4119 Maximize the ECB-history-window, i.e. delete all other ECB-windows, so
4120 only one ECB-window and the edit-window(s) are visible (and maybe a
4121 compile-window). Works also if the ECB-history-window is not visible
4125 @deffn Command maximize-window-speedbar
4126 Maximize the ECB-speedbar-window, i.e. delete all other ECB-windows,
4127 so only one ECB-window and the edit-window(s) are visible (and maybe a
4128 compile-window). Does nothing if the speedbar-window is not visible
4129 within the ECB-frame.
4132 @deffn Command methods-filter
4133 Apply a filter to the Methods-buffer to reduce the number of entries.
4134 So you get a better overlooking. There are six choices:
4137 @item Filter by protection:
4138 Just insert the protection you want the Methods-buffer being filtered:
4139 private, protected or public!
4141 @item Filter by regexp:
4142 Insert the filter as regular expression.
4144 @item Filter by tag-class:
4145 You can filter by the tag-classes of current major-mode. The available
4146 tag-classes come from the variable
4147 @code{semantic--symbol->name-assoc-list}. The are normally methods,
4150 @item Filter by current type:
4151 In languages which have types like Java or C++ this filter displays
4152 only the current type and all its members (e.g. attributes and
4153 methods). If ECB can not identify the current type in the
4154 source-buffer or in the methods-window then nothing will be done.
4156 @item Filter by a filter-function:
4157 Such a function gets two arguments: a tag and the source-buffer of
4158 this tag. If the tag should be displayed (i.e. not being filtered out)
4159 then the function has to return not nil otherwise nil.
4161 @item No special filter:
4162 This means to display all tags specified with the option
4163 @code{ecb-show-tokens}. If currently some of the above filters are
4164 applied they will be all removed.
4166 @item Delete the last added:
4167 This removes only the topmost filter-layer, means that filter added
4171 The protection-, current-type- and the tag-class-filter are only
4172 available for semantic-supported sources.
4174 Be aware that the tag-list specified by the option
4175 @code{ecb-show-tags} is the basis of all filters, i.e. tags which are
4176 excluded by that option will never be shown regardless of the filter
4179 All tags which match the applied filter(s) will be displayed in the
4182 If called with a prefix-argument or when optional arg INVERSE is not
4183 nil then an inverse filter is applied to the Methods-buffer, i.e. all
4184 tags which do NOT match the choosen filter will be displayed in the
4187 Per default the choosen filter will be applied on top of already
4188 existing filters. This means that filters applied before are combined
4189 with the new filter. This behavior can changed via the option
4190 @code{ecb-methods-filter-replace-existing}. But regardless of the
4191 setting in @code{ecb-methods-filter-replace-existing} applying one of
4192 the not-inverse filters protection, tag-class or current-type always
4193 replaces exactly already existing filters of that type. On the other
4194 hand applying more than one inverse tag-class- or protection-filter
4197 Such a filter is only applied to the current source-buffer, i.e. each
4198 source-buffer can have its own tag-filters.
4200 The current active filter will be displayed in the modeline of the
4201 Methods-buffer [regexp, prot (= protection), tag-class, function (=
4202 filter-function)]. If an inverse filter has been applied then this is
4203 signalized by a preceding caret ^. If currently more than 1 filter is
4204 applied then always the top-most filter is displayed in the modeline
4205 but the fact of more than 1 filter is visualized by the number of the
4206 filters - included in parens. You can see all currently applied
4207 filters by moving the mouse over the filter-string in modeline of the
4208 Methods-buffer: They will displayed as help-echo.
4210 See the option @code{ecb-default-tag-filter} if you search for
4211 automatically applied default-tag-filters.
4214 @deffn Command methods-filter-current-type
4215 Display in the Methods-buffer only the current type and its members.
4216 For further details see @code{ecb-methods-filter}.
4220 @deffn Command methods-filter-delete-last
4221 Remove the most recent filter from the Methods-buffer. For further details see
4222 @code{ecb-methods-filter}.
4225 @deffn Command methods-filter-function &optional inverse
4226 Filter the methods-buffer by a function. If INVERSE is not nil (called
4227 with a prefix arg) then an inverse filter is applied. For further details see
4228 @code{ecb-methods-filter}.
4231 @deffn Command methods-filter-nofilter
4232 Remove any filter from the Methods-buffer. For further details see
4233 @code{ecb-methods-filter}.
4236 @deffn Command methods-filter-protection &optional inverse
4237 Filter the methods-buffer by protection. If INVERSE is not nil (called
4238 with a prefix arg) then an inverse filter is applied. For further details see
4239 @code{ecb-methods-filter}.
4242 @deffn Command methods-filter-regexp &optional inverse
4243 Filter the methods-buffer by a regexp. If INVERSE is not nil (called
4244 with a prefix arg) then an inverse filter is applied. For further details see
4245 @code{ecb-methods-filter}.
4248 @deffn Command methods-filter-tagclass &optional inverse
4249 Filter the methods-buffer by tag-class. If INVERSE is not nil (called
4250 with a prefix arg) then an inverse filter is applied. For further details see
4251 @code{ecb-methods-filter}.
4254 @deffn Command minor-mode &optional arg
4255 Toggle ECB minor mode. With prefix argument @var{ARG}, turn on if
4256 positive, otherwise off. Return non-@code{nil} if the minor mode is
4260 @deffn Command nav-goto-previous
4261 Go backward in the navigation history-list, see @ref{Back/forward
4265 @deffn Command nav-goto-next
4266 Go forward in the navigation history-list, see @ref{Back/forward
4270 @deffn Command rebuild-methods-buffer
4271 Updates the methods buffer with the current buffer after deleting the
4272 complete previous parser-information, means no semantic-cache is used!
4273 Point must stay in an edit-window otherwise nothing is done. This
4274 method is merely needed for semantic parsed buffers if semantic parses
4275 not the whole buffer because it reaches a not parse-able code or for
4276 buffers not supported by semantic but by imenu or etags.
4278 Examples when a call to this function can be necessary:
4282 If an Elisp-file is parsed which contains in the middle a defun X
4283 where the closing ) is missing then semantic parses only until this
4284 defun X is reached and you will get an incomplete ECB-method buffer.
4285 In such a case you must complete the defun X and then call this
4286 function to completely reparse the Elisp-file and rebuild the ECB
4290 For not semantic supported buffers which can be parsed by imenu or
4291 etags (see @code{ecb-process-non-semantic-files}) because for these
4292 buffers there is no built-in auto-rebuild mechanism. For these buffers
4293 this command calls @code{ecb-rebuild-methods-buffer-for-non-semantic}.
4296 For non-semantic-sources supported by etags the option
4297 @code{ecb-auto-save-before-etags-methods-rebuild} is checked before
4298 rescanning the source-buffer and rebuilding the methods-buffer.
4300 If point is in one of the ecb-windows or in the compile-window then
4301 this command rebuids the methods-buffer with the contents of the
4302 source-buffer the last selected edit-window.
4305 @deffn Command redraw-layout &optional ARG
4306 Redraw the ECB screen.
4308 Do not call this command from elisp-program but only interactively!
4310 Called without a prefix-argument the state of the ECB-frame-layout
4311 will preserved. This means:
4315 The state of compile-window (hidden or visible) will be preserved but
4316 if visible then the height will be as specified in
4317 @code{ecb-compile-window-height}.
4320 The state of the ECB-windows will be preserved (hidden or visible) but
4321 if visible then the sizes will be as specified in the layout (and with
4322 the options @code{ecb-windows-width} and @code{ecb-windows-height}) or
4323 as stored with @code{ecb-store-window-sizes}.
4326 If called with ONE prefix-argument (@kbd{[C-u]}) then the layout will
4327 be drawn with all ECB-windows and also with a visible compile-window
4328 (when @code{ecb-compile-window-height} is not nil). The
4329 splitting-state of the edit-area will be preserved.
4331 If called with TWO prefix-arguments (i.e. hitting @kbd{[C-u]} twice:
4332 (@kbd{[C-u]} @kbd{[C-u]}) then an emergency-redraw will be performed.
4333 This means the same as if called with one prefix-argument (s.a.) but
4334 the splitting-state of the edit-area will NOT be preserved but all
4335 edit-windows besides the current one will be deleted. Use this only if
4336 there are some anomalies after standard redraws!
4338 If the variable @code{ecb-redraw-layout-quickly} is not nil then the
4339 redraw is done by the @code{ecb-redraw-layout-quickly} function,
4340 otherwise by @code{ecb-redraw-layout-full}.
4342 Please not: It's strongly recommended to use the quick redraw only if
4343 you have really slow machines where a full redraw takes several
4344 seconds because the quick redraw is not really safe and has some
4345 annoying drawbacks! On normal machines the full redraw should be done
4346 in << 1s so there should be no need for the quick version!
4350 @deffn Command restore-default-window-sizes
4351 Resets the sizes of the ECB windows to their default values.
4354 @deffn Command restore-window-sizes
4355 Sets the sizes of the ECB windows to their stored values. See option
4356 @code{ecb-layout-window-sizes} and command
4357 @code{ecb-store-window-sizes}.
4360 @deffn Command select-ecb-frame
4361 Selects the @code{ecb-frame} if ECB is activated - otherwise reports
4365 @deffn Command show-help &optional format
4366 Shows the online help of ECB either in Info or in HTML format
4367 depending of the value of @code{ecb-show-help-format}. If called with
4368 prefix argument, i.e. if @var{FORMAT} is not nil then the user is
4369 prompted to choose the format of the help (Info or HTML). If an error
4370 about not finding the needed help-file occurs please take a look at
4371 the options @code{ecb-help-info-start-file} and
4372 @code{ecb-help-html-start-file}!
4374 Note: If you got ECB as a standard XEmacs-package maybe the
4375 HTML-online-documentation is not included.
4378 @deffn Command show-layout-help
4379 Select a name of a layout and shows the documentation of the
4380 associated layout-function. At least for the built-in layouts the
4381 documentation contains a picture of the outline of the chosen layout.
4384 @deffn Command show-tip-of-the-day
4385 Show tip of the day if @code{ecb-tip-of-the-day} is not nil or if
4386 called interactively.
4389 @deffn Command sources-filter
4390 Apply a filter to the sources-buffer to reduce the number of entries.
4391 So you get a better overlooking. There are three choices:
4394 @item Filter by extension:
4395 Just insert the extension you want the Sources-buffer being filtered.
4396 Insert the extension without leading dot!
4398 @item Filter by regexp:
4399 Insert the filter as regular expression.
4402 This means to display an entry for every file in the current selected
4403 directory (all except these filter already filtered out by
4404 @code{ecb-source-file-regexps} and
4405 @code{ecb-sources-exclude-cvsignore}).
4408 Such a filter is only applied to the current selected directory, i.e. each
4409 directory has its own filtered sources-buffer.
4412 @deffn Command store-window-sizes &optional FIX
4413 Stores the sizes of the ECB windows for the current layout. The size
4414 of the ECB windows will be set to their stored values when
4415 @code{ecb-redraw-layout} or @code{ecb-restore-window-sizes} is called.
4416 To reset the window sizes to their default values call
4417 @code{ecb-restore-default-window-sizes}. Please read also the
4418 documentation of @code{ecb-layout-window-sizes}!
4420 The windows sizes are stored per default as fractions of current
4421 frame-width and -height of the ecb-frame, so the stored values will
4422 ``work'' for other frame sizes too. If a permanent compile-window is
4423 visible then ECB will tell you that window-sizes should be stored with
4424 hidden compile-window and ask you if you want proceed; if you proceed
4425 then the window-heights will be stored as fractions of current
4426 (frame-height minus current visible compile-window-height) so you
4427 should ensure that the current compile-window has its standard-height
4428 as specified in @code{ecb-compile-window-height}!. If @var{FIX} is not
4429 nil (means called with a prefix argument) then always the fixed values
4430 of current width and height are stored!
4433 @deffn Command submit-problem-report
4434 Submit a problem report for the ECB to the ECB mailing-list. This
4435 command generates in the edit-window a problem-report which contains
4436 already the current values of all ECB options, the current
4437 backtrace-buffer if there is any and the current message-buffer. You
4438 will be asked for a problem-report subject and then you must insert a
4439 description of the problem. Please describe the problem as detailed as
4443 @deffn Command toggle-auto-expand-tag-tree &optional arg
4444 Toggle auto expanding of the ECB-methods-buffer. With prefix argument
4445 @var{ARG}, make switch on if positive, otherwise switch off. If the
4446 effect is that auto-expanding is switched off then the current value
4447 of @code{ecb-auto-expand-tag-tree} is saved so it can be used for
4448 the next switch on by this command.
4451 @deffn Command toggle-compile-window &optional arg
4452 Toggle the visibility of the compile-window of ECB. With prefix
4453 argument ARG, make visible if positive, otherwise invisible. The
4454 height of the compile-window is always the current value of
4455 @code{ecb-compile-window-height}! If called and
4456 @code{ecb-compile-window-height} is nil then ECB asks for the height
4457 of the compile-window, sets this height as new value of
4458 @code{ecb-compile-window-height} and displays the compile-window (so
4459 if you have called this command by mistake and you do not want a
4460 compile-window you have to quit with @key{C-g}).
4464 @deffn Command toggle-compile-window-height &optional arg
4465 Toggle whether the @code{ecb-compile-window} is enlarged or not. If
4466 @var{ARG} > 0 then shrink or enlarge the the compile-window according
4467 to the value of @code{ecb-enlarged-compilation-window-max-height}. But
4468 never shrink below the value of @code{ecb-compile-window-height}. If
4469 @var{ARG} <= 0 then shrink @code{ecb-compile-window} to
4470 @code{ecb-compile-window-height} and if @var{ARG} is nil then toggle
4474 @deffn Command toggle-ecb-windows &optional arg
4475 Toggle visibility of the ECB-windows. With prefix argument @var{ARG},
4476 make visible if positive, otherwise invisible. This has nothing to do
4477 with (de)activating ECB but only affects the visibility of the ECB
4478 windows. ECB minor mode remains active!
4481 @deffn Command toggle-layout &optional last-one
4482 Toggles between the layouts defined in
4483 @code{ecb-toggle-layout-sequence} (See also option
4484 @code{ecb-show-sources-in-directories-buffer}). Note: This function
4485 works by changing the options @code{ecb-layout-name} but only for
4486 current Emacs-session.
4488 If optional argument @var{LAST-ONE} is not nil (e.g. called with a
4489 prefix-arg) then always the last selected layout was choosen
4490 regardless of the setting in @code{ecb-toggle-layout-sequence}. The
4491 last selected layout is always that layout which was current direct
4492 before the most recent layout-switch. So now a user can switch to
4493 another layout via `ecb-change-layout' and always come back to his
4494 previous layout via @kbd{[C-u]} @code{ecb-toggle-layout}.
4497 @deffn Command toggle-scroll-other-window-scrolls-compile &optional ARG
4499 @code{ecb-scroll-other-window-scrolls-compile-window}. With prefix
4500 argument @var{ARG}, set it to @code{t}, otherwise to @code{nil}. For
4501 all details about the scroll-behavior of @code{scroll-other-window}
4502 see the advice documentation of @code{other-window-for-scrolling}.
4505 @deffn Command toggle-window-sync &optional arg
4506 Toggle auto synchronizing of the ECB-windows. With prefix argument
4507 @var{ARG}, switch on if positive, otherwise switch off. If the effect
4508 is that auto-synchronizing is switched off then the current value of
4509 the option @code{ecb-window-sync} is saved so it can be used for the
4510 next switch on by this command. See also the option
4511 @code{ecb-window-sync}.
4514 @deffn Command update-directories-buffer
4515 Updates the ECB directories buffer.
4518 @deffn Command upgrade-options
4519 Check for all ECB-options if their current value is compatible to the
4520 defined type. If not upgrade it to the new type or reset it to the
4521 default-value of current ECB. Try also to upgrade renamed options.
4522 Displays all upgraded or reset options with their old (before the
4523 upgrade/reset) and new values.
4526 @deffn Command window-sync
4527 Synchronizes all special ECB-buffers with current buffer.
4529 Depending on the contents of current buffer this command performs different
4530 synchronizing tasks but only if ECB is active and point stays in an
4535 If current buffer is a file-buffer then all special ECB-tree-buffers are
4536 synchronized with current buffer.
4539 If current buffer is a dired-buffer then the directory- and
4540 the sources-tree-buffer are synchronized if visible
4543 In addition to this the hooks in @code{ecb-current-buffer-sync-hook}
4547 Most of these functions are also available via the menu ``ECB'' and
4548 also via the ECB key-map with prefix @kbd{C-c .} (see
4549 @code{ecb-minor-mode} for a complete list of the keybindings).
4551 @node Customizing, Submitting problem report, Usage of ECB, Top
4552 @chapter Customizing ECB
4554 This chapter describes how to customize ECB for your personal taste.
4555 The first section introduces some general aspects (which you should
4556 really know!), the second one gives an overview of the most important
4557 options and the third one lists all options of ECB (divided into the
4561 * General aspects:: General aspects for customizing ECB
4562 * Most important options:: Which option you must know
4563 * Customizable options:: All customizable options of ECB
4566 @node General aspects, Most important options, Customizing, Customizing
4567 @section General aspects for customizing ECB
4569 This chapter contains all important informations you should know about
4570 customizing ECB. The first section gives an answer to the question
4571 ``@code{setq} or @code{customize}'' and the second section describes
4572 what to do when you have to customize ECB for a lot of people.
4575 * setq or customize:: Should i use setq or customize?
4576 * Site-wide customizing:: Site-wide customizing of ECB
4579 @node setq or customize, Site-wide customizing, General aspects, General aspects
4580 @subsection Setq or customize - what should i use?
4582 The best way to customize all the options of ECB is via the
4583 customize-feature of (X)Emacs, i.e. means calling the commands
4584 @code{customize-option} or @code{customize-group} etc. This is also
4585 the strongly recommended way!
4587 But of course you can also use @code{setq} or some Elisp-code to
4588 change the values of many but not all of the options. The values of
4589 the following options @strong{MUST NOT} be changed via @code{setq} or
4590 Elisp-code but only with the customize-feature!
4593 @item @code{ecb-advice-window-functions}
4594 @item @code{ecb-bucket-node-display}
4595 @item @code{ecb-compile-window-height}
4596 @item @code{ecb-compile-window-temporally-enlarge}
4597 @item @code{ecb-compile-window-width}
4598 @item @code{ecb-exclude-parents-regexp}
4599 @item @code{ecb-fix-window-size}
4600 @item @code{ecb-font-lock-tags}
4601 @item @code{ecb-highlight-tag-with-point-delay}
4602 @item @code{ecb-key-map}
4603 @item @code{ecb-layout-name}
4604 @item @code{ecb-layout-window-sizes}
4605 @item @code{ecb-mode-line-data}
4606 @item @code{ecb-mode-line-display-window-number}
4607 @item @code{ecb-mode-line-prefixes}
4608 @item @code{ecb-show-node-info-in-minibuffer}
4609 @item @code{ecb-show-tags}
4610 @item @code{ecb-source-path}
4611 @item @code{ecb-toggle-layout-sequence}
4612 @item @code{ecb-tag-display-function}
4613 @item @code{ecb-tree-RET-selects-edit-window}
4614 @item @code{ecb-type-tag-display}
4615 @item @code{ecb-type-tag-expansion}
4616 @item @code{ecb-use-speedbar-instead-native-tree-buffer}
4617 @item @code{ecb-window-sync-delay}
4618 @item @code{ecb-windows-height}
4619 @item @code{ecb-windows-width}
4622 @node Site-wide customizing, , setq or customize, General aspects
4623 @subsection Site-wide customizing of ECB
4625 If you are the administrator for an Emacs-site, means you are
4626 responsible for the basic customization of a lot of Emacs users, then
4627 you maybe need a way to customize Emacs and ECB without changing
4628 everyones @file{.emacs}-file and normally you will do this with the
4629 file @file{site-start.el}. You can customize all options of ECB in a
4630 central @file{site-start.el} (even the options mentioned above!) but
4631 you @strong{MUST NOT} do this via @code{setq} but you have to use a
4632 mechanism like the following@footnote{At least for the options for
4633 which @code{setq} is explicitly forbidden, but it is recommended to
4634 use always such a mechanism}!
4636 This section describes two methods how to pre-customize ECB site-wide.
4637 The elisp-code contained in the following two subsections has to be
4638 copied to the file @file{site-start.el} before it can be used.
4640 But ensure for both methods that you customize the options with the
4641 correct lisp format. Read carefully the docstrings of the options you
4642 want to customize from within Elisp-code!
4644 @subsubsection Storing all option-settings in the users custom-file
4646 The mechanism described here defines all site-wide-settings in a file
4647 @file{site-lisp.el} but stores the values in the users
4648 @code{custom-file} which is probably @file{.emacs}!
4650 First two helper functions are needed, namely
4651 @code{customize-option-get-value} and
4652 @code{customize-save-variable-save} whereas the latter one sets the
4653 value for an option via the customize-mechanism (and is therefore
4654 allowed for the setq-forbidden options!) but only if the option has no
4655 saved value until now (i.e. the user has not saved this option for
4656 future sessions until now)
4660 (defun customize-option-get-value (option type)
4661 "Return the value of a customizable option OPTION with TYPE, where TYPE
4662 can either be 'standard-value \(the default-value of the defcustom) or
4663 'saved-value \(the value stored durable by the user via customize)."
4664 (let ((val (car (get option type))))
4665 (cond ((not (listp val)) val)
4666 ((equal 'quote (car val)) (car (cdr val)))
4669 (defun customize-save-variable-save (option value &optional override)
4670 "Calls `customize-save-variable' with OPTION and VALUE if OPTION is a
4671 custom-type and if OPTION has no saved-value until now.
4672 If OVERRIDE is a function or lambda-form then it is called with two arguments:
4673 - OLD-SAVED-VAL: The saved value of OPTION
4674 - NEW-VALUE: see argument VALUE.
4675 OVERRIDE is only called if OPTION has already a saved-value. If OVERIDE
4676 returns not nil then `customize-save-variable' is called for OPTION with VALUE
4677 even if OPTION has no saved-value until now."
4678 (and (get option 'custom-type)
4679 (or (not (get option 'saved-value))
4680 (and (functionp override)
4682 (customize-option-get-value option 'saved-value)
4685 (message "Overriding saved value for option %s with %s" option value)
4686 (customize-save-variable option value))))
4690 With @code{customize-save-variable-save} all ECB-options can be
4691 site-wide pre-customized like follows:
4695 (customize-save-variable-save 'ecb-show-tags
4696 '((include collapsed nil)
4697 (parent collapsed nil)
4698 (type flattened nil)
4699 (variable collapsed name)
4700 (function flattened name)
4701 (rule flattened name)
4702 (section flattened nil)
4703 (def collapsed name)
4704 (t collapsed name)))
4705 (customize-save-variable-save 'ecb-font-lock-tags t)
4706 ;; add here more options of ECB it you want
4710 @subsubsection Using a special setq for site-wide settings
4712 The mechanism above saves the pre-customized values always in the
4713 users @code{custom-file} (probably @file{.emacs}). If this is not
4714 preferred, then you can use the following mechanism but of course the
4715 offered @code{setq-save} is only allowed for options which are not
4716 setq-forbidden (@pxref{setq or customize}).
4718 The mechanism below does not change the users @code{custom-file}. This
4719 mechanism is needed especially if ECB should be autoloaded and all
4720 site-wide settings should first loaded when ECB is activated by the
4721 user. This can be achieved for example via@footnote{The file
4722 @file{site-ecb.el} contains all site-wide settings for ECB}:
4726 (require 'ecb-autoloads))
4727 (eval-after-load "ecb"
4728 '(require 'site-ecb))
4732 In such a situation the whole @code{custom-file} of a user is mostly
4733 loaded @strong{before} ECB is activated and therefore before the
4734 site-wide-settings are loaded. So the users own customizations are
4735 loaded before the site-wide ones.
4737 The @code{setq-save}-mechanism described below prevents the users own
4738 customisations contained in his @code{custom-file} from being
4739 overridden by the site-wide setq-settings. If @code{setq} would be
4740 used for the site-wide settings then in an autoload-situation the
4741 site-wide settings would override the users-settings and this should
4744 First two helper-macros are needed:
4748 (defmacro custom-saved-p (option)
4749 "Return only not nil if OPTION is a defcustom-option and has a
4750 saved value. Option is a variable and is literal \(not evaluated)."
4751 `(and (get (quote ,option) 'custom-type)
4752 (get (quote ,option) 'saved-value)))
4754 (defmacro setq-save (option value)
4755 "Sets OPTION to VALUE if and only if OPTION is not already saved
4756 by customize. Option is a variable and is literal \(not evaluated)."
4757 `(and (not (custom-saved-p ,option))
4758 (set (quote ,option) ,value)))
4762 With @code{setq-save} all ``not-setq-forbidden''-ECB-options can be
4763 site-wide pre-customized like follows:
4767 (setq-save ecb-tree-indent 4)
4768 (setq-save ecb-tree-expand-symbol-before t)
4769 (setq-save ecb-primary-secondary-mouse-buttons 'mouse-1--mouse-2)
4773 @node Most important options, Customizable options, General aspects, Customizing
4774 @section The most important options of ECB
4776 Here are the most important options (it is recommended to check at
4777 least the following options before working with ECB). You can
4778 customize them via the customize-group ``ecb-most-important'' or via
4779 the command @code{ecb-customize-most-important}.
4782 @item ecb-source-path
4783 Where ECB can find your sources. You must set this option!
4784 @item ecb-show-help-format
4785 Should the online help of ECB be displayed in the standard Info format
4786 or in HTML format in a web-browser.
4787 @item ecb-auto-activate
4788 @item ecb-major-modes-show-or-hide
4789 Auto. activation of ECB after start (@pxref{Automatic activation}) or
4790 major-mode-based showing or hiding the ecb-windows.
4791 @item ecb-winman-escreen-number
4792 @itemx ecb-winman-winring-name
4793 Support of several window-managers (@pxref{Window-managers and ECB}).
4795 All ECB-keybindings incl. a common prefix-key (@pxref{Using the
4797 @item ecb-new-ecb-frame
4798 Should ECB create a new frame at activation time.
4799 @item ecb-primary-secondary-mouse-buttons
4800 @itemx ecb-mouse-click-destination
4801 Define how to use the mouse (@pxref{Using the mouse}).
4802 @item ecb-tree-buffer-style
4803 @itemx ecb-tree-expand-symbol-before
4804 @itemx ecb-tree-indent
4805 @itemx ecb-truncate-lines
4806 The look&feel of the trees in the tree-buffers. The former option
4807 defines the general style of the tree-buffers and the latter ones
4808 allow to customize the ascii-style tree-buffers (maybe you like a
4809 value of 4 for the latter one if you display the expand-symbol before
4810 (@pxref{Tree-buffer styles}).
4811 @item ecb-source-file-regexps
4812 Which files will (not) be shown in ECB.
4813 @item ecb-show-node-info-in-minibuffer
4814 When and which node-info should be displayed in the minibuffer?
4815 @item ecb-layout-name
4816 @itemx ecb-compile-window-height
4817 @itemx ecb-compile-window-width
4818 @itemx ecb-other-window-behavior
4819 The ECB layout, means which windows you want to be displayed in the
4820 ECB-frame and also the location of these windows (@pxref{Changing the
4822 @item ecb-compilation-buffer-names
4823 Which buffers should be treaten as ``compilation-buffers'' and
4824 therefore displayed in the compile-window of ECB - if there is any.
4825 @item ecb-tag-display-function
4826 @itemx ecb-type-tag-display
4827 @itemx ecb-type-tag-expansion
4828 @itemx ecb-show-tags
4829 How to display the entries in the ECB-method window for semantic
4830 supported sources (@pxref{Customizing the display}). These options
4831 take only effect for semantic-sources (@pxref{Definition of semantic-
4832 and non-semantic-sources}).
4833 @item ecb-process-non-semantic-files
4834 Displaying file-contents for not by semantic supported files too, e.g.
4835 for LaTeX- and perl-sources (@pxref{Non-semantic sources}).
4838 But to make ECB working best for you it is also recommended to have a
4839 look at @ref{Customizable options}!
4841 @node Customizable options, ,Most important options, Customizing
4842 @section All customizable options of ECB
4845 All customization of ECB is divided into the following ``customize
4846 groups''. You can highly customize all the ECB behavior/layout so just
4847 go to these groups and you will see all well documented ECB-options.
4849 @strong{Please note}: All options in the following subsections are
4850 listed without the prefix ``ecb-'' (e.g. the option
4851 @code{ecb-layout-name} is listed with name ``layout-name''). This has
4852 been done for a better readable option index. @xref{Option Index}.
4855 * ecb-general:: General customizing ECB
4856 * ecb-tree-buffer:: Customizing the general tree layout
4857 * ecb-directories:: Customizing the ECB-directories-tree
4858 * ecb-sources:: Customizing the ECB-sources-tree
4859 * ecb-methods:: Customizing the ECB-methods-tree
4860 * ecb-history:: Customizing the ECB-history-tree
4861 * ecb-layout:: Customizing the ECB-layout
4862 * ecb-compilation:: Customizing the compile-window
4863 * ecb-create-layout:: Customizing options for creating layouts
4864 * ecb-face-options:: Customizing options for faces
4865 * ecb-faces:: Customizing the faces
4866 * ecb-download:: Customizing how to download ECB
4867 * ecb-help:: Customizing the online help of ECB
4868 * ecb-eshell:: Customizing the eshell-integration
4869 * ecb-speedbar:: Customizing the speedbar-integration
4870 * ecb-non-semantic:: Customizing parsing non-semantic sources
4871 * ecb-winman:: Customizing window-manager support
4872 * ecb-mode-line:: Customizing the tree-buffer-modelines
4873 * ecb-version-control:: Customizing the version-control-support
4876 @node ecb-general, ecb-tree-buffer, Customizable options, Customizable options
4877 @subsection Group ecb-general
4880 This group contains general settings for the Emacs code browser:
4882 @defopt activate-before-layout-draw-hook
4883 Normal hook run at the end of activating the ecb-package by running
4884 @code{ecb-activate}. This hooks are run after all the internal setup
4885 process but directly before(!) drawing the layout specified in
4886 @code{ecb-layout} (means before dividing the frame into several
4889 A senseful using of this hook can be maximizing the Emacs-frame for
4890 example, because this should be done before the layout is drawn
4891 because ECB computes the size of the ECB-windows with the current
4892 frame size! If you need a hook-option for the real end of the
4893 activating process (i.e. after the layout-drawing) look at
4894 @code{ecb-activate-hook}.
4896 IMPORTANT: The difference between this hook and
4897 @code{ecb-redraw-layout-before-hook} is that the latter one is
4898 evaluated always before the layout is redrawn (for example after
4899 calling @code{ecb-redraw-layout}) whereas the former one (this hook)
4900 is only evaluated exactly once during the activation-process of ECB.
4901 So during the activation process there is the following sequence of
4904 @item @code{ecb-activate-before-layout-draw-hook} \(this one)
4905 @item @code{ecb-redraw-layout-before-hook}
4906 @item <Drawing the layout>
4907 @item @code{ecb-redraw-layout-after-hook}
4908 @item @code{ecb-activate-hook}
4912 @defopt activate-hook
4913 Hook run at the end of activating ECB by @code{ecb-activate}. This
4914 hooks are run at the real end of the activating process, means after
4915 the layout has been drawn!. If you need hooks which are run direct
4916 before the layout-drawing look at
4917 @code{ecb-activate-before-layout-draw-hook}.
4920 @defopt activation-selects-ecb-frame-if-already-active
4921 Trying to activate an already activated ECB selects the ECB-frame. If
4922 t then the ECB-frame is selected, if nil then it is not. If 'ask then
4923 ECB asks if the ECB-frame should be selected if the current-frame is
4924 not the @code{ecb-frame}.
4927 @defopt auto-activate
4928 Automatically startup ECB when Emacs starts up. This should only be
4929 true if you always want to run @code{ecb-activate}.
4932 @defopt auto-compatibility-check
4933 Check at ECB-startup if all ECB-options have correct values. If not
4934 nil then all ECB-options are checked if their current value have the
4935 correct type. It the type is incorrect the option is either auto.
4936 upgraded to the new type or reset to the default-value of current ECB
4937 if no upgrade is possible. This feature can also upgrade options which
4938 are renamed in current ECB and try to transform the old-value to the
4939 new named option. After startup all upgraded or reset options are
4940 displayed with their old (before upgrade/reset) and new values. See
4941 also the commands @code{ecb-upgrade-options} and
4942 @code{ecb-display-upgraded-options}. If this option is off then the
4943 user can perform the check and reset manually with
4944 @code{ecb-upgrade-options}.
4945 @xref{Auto. option-upgrading}.
4948 @defopt before-activate-hook
4949 Normal hook run at the beginning of activating the ecb-package by
4950 running @code{ecb-activate}. These hooks run before any other tasks of
4951 the activating process are performed. If any of these hooks returns
4952 nil then ECB will not be activated!
4954 This can be used to check some conditions and then only start ECB if
4955 all conditions are true. For example a function could be added which
4956 returns only nil if Gnus is running. Then calling @code{ecb-activate}
4957 or @code{ecb-minor-mode} will only start ECB if Gnus is not already
4961 @defopt before-deactivate-hook
4962 Normal hook run at the beginning of deactivating ECB by running
4963 @code{ecb-deactivate}. These hooks run before any other tasks of the
4964 deactivating process are performed. If any of these hooks returns nil
4965 then ECB will not be deactivated! See also
4966 @code{ecb-before-activate-hook}.
4969 @defopt bucket-node-display
4970 How ECB displays bucket-nodes in a ECB tree-buffer. Bucket-nodes have
4971 only one job: Nodes with similar properties will be dropped into one
4972 bucket for such a common property and all these nodes will be added as
4973 children to the bucket-node. Besides being expandable and collapsable
4974 a bucket-node has no senseful action assigned. Examples for
4975 bucket-nodes are ``[+] Variables, ``[+] Dependencies'' etc. in the
4976 Methods-buffer or buckets which combine filenames with same extension
4977 under a bucket-node with name this extension.
4979 This option defines how bucket-node should be displayed. The name of
4980 the bucket-node is computed by ECB but you can define a prefix, a
4981 suffix and a special face for the bucket-node
4983 The default are empty prefix/suffix-strings and
4984 @code{ecb-bucket-node-face}. But an alternative can be for example
4985 '(``['' ``]'' nil) which means no special face and a display like
4986 ``[+] [<bucket-name>]''.
4990 @defopt clear-caches-before-activate
4991 Clear all ECB internal caches before startup. If t then ECB clears all
4992 its internal caches before starting up. Caches are used for files- and
4993 subdirs (see @code{ecb-cache-directory-contents} and
4994 @code{ecb-cache-directory-contents-not}) for semantic-tags and for
4997 This caches are completely clean at load-time of the ECB-library!
4999 Default is nil, because is makes sense not to clear these caches at
5000 start-time because ECB is often deacticated temporally especially in
5001 combination with window-managers like escreen.el. In these situations
5002 the internal state of ECB should be preserved for next activation.
5006 @defopt current-buffer-sync-hook
5007 Normal hook run at the end of @code{ecb-current-buffer-sync}.
5009 See documentation of @code{ecb-current-buffer-sync} for conditions when
5010 synchronization takes place and so in turn these hooks are evaluated.
5012 Precondition for such a hook:
5013 Current buffer is the buffer of the current selected edit-window.
5015 Postcondition for such a hook:
5016 Point must stay in the same edit-window as before evaluating the hook.
5018 Important note: If @code{ecb-window-sync} is not nil
5019 @code{ecb-current-buffer-sync} is running either every time Emacs is
5020 idle or even after every command (see @code{ecb-window-sync-delay}).
5021 So these hooks can be really called very often! Therefore each
5022 function of this hook should/must check in an efficient way at
5023 beginning if its task have to be really performed and then do them
5024 only if really necessary! Otherwise performance of Emacs could slow
5027 It is strongly recommended that each function added to this hook uses
5028 the macro @code{ecb-do-if-buffer-visible-in-ecb-frame} at beginning!
5029 See @code{ecb-speedbar-current-buffer-sync} and
5030 @code{ecb-eshell-current-buffer-sync} for examples how to use this
5036 @defopt deactivate-hook
5037 Normal hook run at the end of deactivating (but before the ecb-layout
5038 is cleared!) ECB by running @code{ecb-deactivate}.
5042 If not nil ECB displays debug-information in the Messages-buffer. This
5043 is done for some critical situations concerning semantic-tags and
5044 their overlays (or extends for XEmacs). Normally you should not need
5045 this switched on! But if you get errors like ``destroyed extend'' for
5046 XEmacs or ``wrong-argument-type'' concerning overlays for GNU Emacs then
5047 you should switch on this option and submitting a bug-report to the
5048 ecb-mailing-list (@code{ecb-submit-problem-report}) after getting the
5052 @defopt grep-function
5053 Function used for performing a grep. The popup-menu of the
5054 tree-buffers ``Directories'', ``Sources'' and ``History'' offer to
5055 grep the ``current'' directory:
5058 Directory-buffer: The grep is performed in the current popup-directory
5059 after clicking the right mouse-button onto a node.
5061 Sources-buffer: The grep is performed in the current selected directory.
5063 History-buffer: The grep is performed in the directory of the current
5064 popup-source after clicking the right mouse-button onto a node.
5068 @defopt grep-find-function
5069 Function used for performing a recursive grep. For more Details see
5070 option `ecb-grep-function' and replace ``grep'' with ``recursive
5075 Specifies all keybindings for the ECB minor-mode key-map. The value is
5076 a cons-cell where the car is a common-prefix key for all the
5077 keybindings. The cdr is a list of keybindings each of them a list
5078 again. A key-binding has the following form:
5081 '(<common-prefix-flag> <keysequence> <function>) where
5085 @item <common-prefix-flag>
5086 If t then the common-prefix-key defined as car of the value (see above)
5090 If the common prefix-key is used then the final key-binding is the
5091 concatenation of the common-prefix-key (see above) and this
5095 The function to bind to the key. This can also be a lambda-expression
5099 It is highly recommended to use one of the standard keys C-c or C-x as
5100 first key of your common-prefix-key!
5102 You MUST change this option via customize to take effect!
5104 All keysequences must be inserted as a string and must follow the
5105 syntax needed by @code{read-kbd-macro} or @code{kbd}. This means you
5106 can insert the key in the same manner @kbd{C-h k} displays keysequences.
5107 Here is the summary of the syntax:
5109 Text is divided into ``words'' separated by whitespace. Except for the words
5110 described below, the characters of each word go directly as characters of the
5111 keysequence. The whitespace that separates words is ignored. Whitespace in the
5112 macro must be written explicitly, as in @kbd{C-c SPC}.
5116 The special words RET, SPC, TAB, DEL, LFD, ESC, and NUL represent
5117 special control characters. The words must be written in uppercase.
5120 A word in angle brackets, e.g., <return>, <down>, <left> or <f1>,
5121 represents a function key. (Note that in the standard configuration,
5122 the function key <return> and the control key RET are synonymous.).
5123 You can use angle brackets on the words RET, SPC, etc., but they are
5127 Keys can be written by their ASCII code, using a backslash followed by
5128 up to six octal digits. This is the only way to represent keys with
5132 One or more prefixes M- (meta), C- (control), S- (shift), A- (alt), H-
5133 (hyper), and s- (super) may precede a character or key notation. For
5134 function keys, the prefixes may go inside or outside of the brackets:
5135 C-<down> = <C-down>. The prefixes may be written in any order: M-C-x =
5136 C-M-x. Prefixes are not allowed on multi-key words, e.g., C-abc,
5137 except that the Meta prefix is allowed on a sequence of digits and
5138 optional minus sign: M--123 = M-- M-1 M-2 M-3.
5141 The @code{^} notation for control characters also works: ^M = C-m.
5145 @defopt major-modes-show-or-hide
5146 List of major-modes which show or hide the ecb-windows. The value is a
5147 cons-cell where the car contains all major-mode-symbols which should
5148 show the special ecb-windows and the cdr contains all
5149 major-mode-symbols which should hide the special ecb-windows. If the
5150 symbol of a major-mode is neither contained in the car-``show-list''
5151 nor in the cdr-``hide-list'' then the visibility-state of the
5152 ecb-windows does not change.
5156 @defopt minor-mode-text
5157 String to display in the mode line when ECB minor mode is active.
5158 (When the string is not empty, make sure that it has a leading space.)
5160 Because for ECB it is quite obvious if it is active or not when the
5161 ECB-windows are visible this text is only display in the modeline if
5162 the ECB-windows are hidden.
5166 @defopt mouse-click-destination
5167 Destination of a mouse-button click. Defines in which edit-window (if
5168 splitted) ECB does the ``right'' action (opening a source, jumping to
5169 a method/variable etc.) after clicking with the primary mouse-button
5170 (see @code{ecb-primary-secondary-mouse-buttons}) onto a node. There
5171 are two possible choices:
5174 @item @code{left-top}:
5175 Does the ``right'' action always in the left/topmost edit-window.
5176 @item @code{last-point}:
5177 Does the ``right'' action always in that edit-window which had the point
5180 This is if the user has clicked either with the primary mouse-button or
5181 has activated a popup-menu in the tree-buffer.
5183 If the edit-area is not splitted this setting doesn't matter.
5185 A click with the secondary mouse-button (see again
5186 @code{ecb-primary-secondary-mouse-buttons} does the ``right'' action
5187 always in another edit-window related to the setting in this option:
5188 If there are two edit-windows then the ``other'' edit-window is used
5189 and for more than 2 edit-windows the ``next'' edit-window is used
5190 (whereas the next edit-window of the last edit-window is the first
5193 Note: If the tree-buffers are used with the keyboard instead with the
5194 mouse then this option takes effect too because @kbd{RET} is
5195 interpreted as primary mouse-button and @kbd{C-RET} as secondary
5199 @defopt run-ediff-in-ecb-frame
5200 Run ediff-sessions in the same frame as ECB is running.
5201 If not nil then ECB ensures that ediff runs in the same frame as ECB and ECB
5202 restores exactly the ``before-ediff''-window-layout after quiting ediff. If
5203 nil then ediff decides in which frame it will run - depending on the current
5204 window-layout (e.g. if the ecb-windows are currently hidden) this can be the
5205 ecb-frame but this can also be a newly created frame or any other frame.
5208 @defopt stealthy-tasks-delay
5209 Time Emacs must be idle before ECB runs its stealthy tasks. Currently
5210 ECB performes the following stealthy tasks:
5213 @item Prescann directories for emptyness
5214 Prescann directories and display them as empty or not-empty in the
5215 directories-buffer. See the documentation of the option
5216 @code{ecb-prescan-directories-for-emptyness} for a description.
5218 @item File is read only
5219 Check if sourcefile-items of the directories- or sources-buffer are
5220 read-only or not. See documentation of the option
5221 @code{ecb-sources-perform-read-only-check}.
5223 @item Version-control-state
5224 Checks the version-control-state of files in directories which are
5225 managed by a VC-backend. See the option @code{ecb-vc-enable-support}.
5229 Here the interval is defined ECB has to be idle before starting with
5230 these stealthy tasks. It can be a floating-point value in seconds. The
5231 value can also be changed during running ECB.
5236 @defopt tip-of-the-day
5237 Show tip of the day at start time of ECB.
5240 @defopt tip-of-the-day-file
5241 File where tip-of-the-day cursor is stored.
5244 @defopt use-recursive-edit
5245 Tell ECB to use a recursive edit. If set then it can easily be
5246 deactivated by (keyboard-escape-quit).
5249 @defopt version-check
5250 Checks at start-time if the requirements are fulfilled.
5251 It checks if the required versions of the libraries semantic, eieio and
5252 speedbar are installed and loaded into Emacs.
5254 It is strongly recommended to set this option to not @code{nil}!
5258 Synchronize the ECB-windows automatically with current edit window. If
5259 @code{always} then the synchronization takes place always a buffer
5260 changes in the edit window, if @code{nil} then never. If a list of
5261 major-modes then only if the @code{major-mode} of the new buffer
5262 belongs NOT to this list.
5264 But in every case the synchronization takes only place if the
5265 current-buffer in the current active edit-window has a relation to
5266 files or directories. Examples for the former one are all
5267 programming-language-modes, @code{Info-mode} too, an example for the
5268 latter one is @code{dired-mode}. For all major-modes related to
5269 non-file/directory-buffers like @code{help-mode},
5270 @code{customize-mode} and others never an autom. synchronization will
5273 It's recommended to exclude at least @code{Info-mode} because it makes
5274 no sense to synchronize the ECB-windows after calling the Info help.
5275 Per default also @code{dired-mode} is excluded but it can also making
5276 sense to synchronize the ECB-directories/sources windows with the
5277 current directory in the dired-buffer.
5279 IMPORTANT NOTE: Every time the synchronization is done the hook
5280 @code{ecb-current-buffer-sync-hook} is evaluated.
5284 @defopt window-sync-delay
5285 Time Emacs must be idle before the ECB-windows are synchronized with
5286 current edit window. If nil then there is no delay, means
5287 synchronization takes place immediately. A small value of about 0.25
5288 seconds saves CPU resources and you get even though almost the same
5289 effect as if you set no delay.
5293 @node ecb-tree-buffer, ecb-directories, ecb-general, Customizable options
5294 @subsection Group ecb-tree-buffer
5297 This group contains general settings related to the tree-buffers of
5300 @defopt common-tree-buffer-after-create-hook
5301 Local hook running at the end of each tree-buffer creation. Every
5302 function of this hook is called once without arguments direct after
5303 creating a tree-buffer of ECB and it's local key-map. So for example a
5304 function could be added which performs calls of @code{local-set-key}
5305 to define new keybindings for EVERY tree-buffer.
5307 The following keys must not be rebind in all tree-buffers:
5309 @item @kbd{RET} and all combinations with @kbd{Shift} and @kbd{Ctrl}
5315 @defopt primary-secondary-mouse-buttons
5316 Primary- and secondary mouse button for using the ECB-buffers. A click
5317 with the primary button causes the main effect in each ECB-buffer:
5320 @item ECB Directories:
5321 Expanding/collapsing nodes and displaying files in the ECB
5324 @item ECB sources/history:
5325 Opening the file in that edit-window specified by the option
5326 @code{ecb-mouse-click-destination}.
5329 Jumping to the method in that edit-window specified by the option
5330 @code{ecb-mouse-click-destination}.
5333 A click with the primary mouse-button while the SHIFT-key is pressed called
5334 the POWER-click and does the following (depending on the ECB-buffer where the
5335 POWER-click occurs):
5338 @item ECB Directories:
5339 Refreshing the directory-contents-cache (see
5340 @code{ecb-cache-directory-contents}).
5342 @item ECB sources/history:
5343 Only displaying the source-contents in the method-buffer but not
5344 displaying the source-file in the edit-window.
5347 Narrowing to the clicked method/variable/ect... (see
5348 @code{ecb-tag-visit-post-actions}). This works only for semantic
5349 supported sources but not for imenu- or etags-supported ones!
5352 In addition always the whole node-name is displayed in the minibuffer after a
5353 POWER-click \(for this see also `ecb-show-node-info-in-minibuffer').
5355 The secondary mouse-button is for opening (jumping to) the file in
5356 another edit-window (see the documentation
5357 @code{ecb-mouse-click-destination}).
5359 The following combinations are possible:
5363 primary: mouse-2, secondary: C-mouse-2 (means mouse-2 while CTRL-key is
5364 pressed). This is the default setting.
5366 primary: mouse-1, secondary: C-mouse-1
5368 primary: mouse-1, secondary: mouse-2
5371 Please note: If the tree-buffers are used with the keyboard instead
5372 with the mouse then @kbd{RET} is interpreted as primary mouse-button and
5373 @kbd{C-RET} as secondary mouse-button!
5375 If you change this during ECB is activated you must deactivate and
5376 activate ECB again to take effect
5379 @defopt show-node-info-in-minibuffer
5380 Node info to display in a tree-buffer. Define which node info should
5381 displayed in a tree-buffer after mouse moving over the node or after a
5382 shift click onto the node.
5384 For every tree-buffer you can define ``when'' node info should be
5388 @item @code{always}:
5389 Node info is displayed by moving with the mouse over a node.
5390 @item @code{if-too-long}:
5391 Node info is only displayed by moving with the mouse over a node does
5392 not fit into the window-width of the tree-buffer window. In the ECB
5393 directories buffer this means also if a node is shortened or if the
5394 node has an alias (see @code{ecb-source-path}).
5395 @item @code{shift-click}:
5396 Node info is only displayed after a shift click with the primary mouse
5397 button onto the node.
5399 Node info is never displayed.
5402 For every tree-buffer you can define what info should be displayed:
5405 @item Directory-buffer:
5407 @item @code{name}: Only the full node-name is displayed.
5408 @item @code{path}: The full-path of the node is displayed.
5411 @item Sources-buffer:
5413 @item @code{name}: Only the full node-name is displayed.
5414 @item @code{file-info}: File infos for this file are displayed.
5415 @item @code{file-info-full}: Fill infos incl. full path for this file are
5418 @item History-buffer: see Directories-buffer.
5419 @item Methods-buffer:
5421 @item @code{name}: Only the full node name is displayed.
5422 @item @code{name+type}: The full name + the type of the node (function, class,
5423 variable) is displayed.
5427 Do NOT set this option directly via setq but use always customize!
5430 @defopt tree-RET-selects-edit-window
5431 In which tree-buffers RET should finally select an edit-window. If one
5432 of the symbols @code{ecb-directories-buffer-name},
5433 @code{ecb-sources-buffer-name}, @code{ecb-methods-buffer-name} or
5434 @code{ecb-history-buffer-name} is contained in this list then hitting
5435 RET in the associated tree-buffer selects as last action the right
5436 edit-window otherwise only the right action is performed (opening a
5437 new source, selecting a method etc.) but point stays in the
5440 A special remark for the @code{ecb-directories-buffer-name}: Of course
5441 here the edit-window is only selected if the name of the current
5442 layout is contained in @code{ecb-show-sources-in-directories-buffer}
5443 or if the value of @code{ecb-show-sources-in-directories-buffer} is
5444 'always and the hitted node represents a sourcefile (otherwise this
5445 would not make any sense)!
5447 The setting in this option is only the default for each tree-buffer.
5448 With @code{ecb-toggle-RET-selects-edit-window} the behavior of RET can
5449 be changed fast and easy in a tree-buffer without customizing this
5450 option, but of course not for future Emacs sessions!
5453 @defopt tree-buffer-style
5454 The style of the tree-buffers.
5455 There are three different styles available:
5457 Image-style (value @code{image}): Very nice and modern - just try it.
5458 For this style the options @code{ecb-tree-indent} and
5459 @code{ecb-tree-expand-symbol-before} have no effect! Note: GNU Emacs
5460 <= 21.3.X for Windows does not support image-display so ECB uses
5461 always 'ascii-guides even when here 'image is set!
5463 Ascii-style with guide-lines (value @code{ascii-guides}):
5484 Ascii-style without guide-lines (value @code{ascii-no-guides}) - this
5485 is the style used by ECB <= 1.96:
5506 With both ascii-styles the tree-layout can be affected with the
5507 options @code{ecb-tree-indent} and
5508 @code{ecb-tree-expand-symbol-before}.
5511 @defopt tree-easy-hor-scroll
5512 Scroll step for easy hor. scrolling via mouse-click in tree-buffers.
5513 XEmacs has horizontal scroll-bars so invisible parts beyond the right
5514 window-border of a tree-buffer can always made visible very easy.
5516 GNU Emacs does not have hor. scroll-bars so especially with the mouse
5517 it is quite impossible to scroll smoothly right and left. The
5518 functions @code{scroll-left} and @code{scroll-right} can be annoying
5519 and are also not bound to mouse-buttons.
5521 If this option is a positive integer S then in all ECB-tree-buffers
5522 the keys @kbd{M-mouse-1} and @code{M-mouse-3} are bound to scrolling
5523 left rsp. right with scroll-step S - clicking with @kbd{mouse-1} or
5524 @kbd{mouse-2} onto the edge of the modeline has the same effect, i.e.
5525 if you click with mouse-1 onto the left (rsp right) edge of the
5526 modeline you will scroll left (rsp. right).
5528 Additionally @code{C-M-mouse-1} and @code{C-M-mouse-3} are bound to
5529 scrolling left rsp. right with scroll-step @code{window-width} - 2.
5531 Default is a scroll-step of 5. If the value is @code{nil} then no keys
5532 for horizontal scrolling are bound.
5535 @defopt tree-expand-symbol-before
5536 Show the expand symbol before the items in a tree. When the
5537 expand-symbol is located before the items then the tree looks like:
5548 When located after then the tree looks like:
5559 The after-example above use a value of 2 for @code{ecb-tree-indent}
5560 whereas the before-example uses a value of 4.
5562 It is recommended to display the expand-symbol before because
5563 otherwise it could be that with a deep nested item-structure with
5564 and/or with long item-names (e.g. a deep directory-structure with some
5565 long subdirectory-names) the expand-symbol is not visible in the
5566 tree-buffer and the tree-buffer has to be horizontal scrolled to
5570 @defopt tree-image-icons-directories
5571 Directories where the images for the tree-buffer can be found.
5572 This is a five-element list where:
5574 @item element: Default directory where the default images for the
5575 tree-buffer can be found. It should contain an image for every name of
5576 @code{tree-buffer-tree-image-names}. The name of an image-file must
5577 be: ``ecb-<NAME of TREE-BUFFER-TREE-IMAGE-NAMES>.<ALLOWED
5579 @item element: Directory for special images for the Directories-buffer.
5580 @item element: Directory for special images for the Sources-buffer.
5581 @item element: Directory for special images for the Methods-buffer.
5582 @item element: Directory for special images for the History-buffer.
5585 The directories of the element 2 - 5 are additional image-directories
5586 which are searched first for images needed for the respective
5587 tree-buffer. If the image can not be found in this directory then the
5588 default-directory (1. element) is searched. If the image can't even
5589 found there the related ascii-symbol is used.
5591 All but the first element (the default directory) can be nil.
5593 ECB comes with images in four diffenent heights - so for the most
5594 senseful font-heights of a tree-buffer a fitting image-size should be
5595 available. The images reside either in the subdirectory ``ecb-images''
5596 of the ECB-installation or - if ECB is installed as regular
5597 XEmacs-package - in the ECB-etc data-directory.
5600 @defopt tree-incremental-search
5601 Enable incremental search in the ECB-tree-buffers. For a detailed
5602 explanation see the online help section ``Working with the keyboard in
5603 the ECB buffers''. If you change this during ECB is activated you must
5604 deactivate and activate ECB again to take effect.
5608 Indent size for tree buffer. If you change this during ECB is
5609 activated you must deactivate and activate ECB again to take effect.
5612 @defopt tree-mouse-action-trigger
5613 When the tree-buffer mouse-action should be triggered. This option
5614 determines the moment a mouse-action in a tree-buffer is triggered.
5615 This can be either direct after pressing a mouse-button (value
5616 @code{button-press}) or not until releasing the mouse-button (value:
5617 @code{button-release}).
5619 If you change this during ECB is activated you must deactivate and
5620 activate ECB again to take effect!
5624 @defopt tree-navigation-by-arrow
5625 Enable smart navigation in the tree-windows by horiz. arrow-keys. If
5626 not nil then the left- and right-arrow keys work in the ECB
5627 tree-window in the following smart way if onto an expandable node:
5631 If node is expanded then it will be collapsed otherwise point jumps to
5632 the next ``higher'' node in the hierarchical tree (higher means the next
5633 higher tree-level or - if no higher level available - the next higher
5634 node on the same level).
5637 If node is not expanded then it will be expanded. Onto a not
5638 expandable node the horizontal arrow-keys go one character in the
5639 senseful correct direction.
5642 If this option is changed the new value takes first effect after deactivating
5643 ECB and then activating it again!
5646 @defopt truncate-lines
5647 Truncate lines in ECB buffers. If you change this during ECB is
5648 activated you must deactivate and activate ECB again to take effect.
5651 @defopt truncate-long-names
5652 Truncate long names that don't fit in the width of the ECB windows. If
5653 you change this during ECB is activated you must deactivate and
5654 activate ECB again to take effect.
5658 @node ecb-directories, ecb-sources, ecb-tree-buffer, Customizable options
5659 @subsection Group ecb-directories
5662 This group contains settings for the directories-buffer in the ECB:
5664 @defopt add-path-for-not-matching-files
5665 Add path of a file to @code{ecb-source-path} if not already contained.
5666 This is done during the auto. windows synchronization which happens if
5667 a file is opened not via the file/directory-browser of ECB. In such a
5668 situation ECB adds the path of the new file auto. to
5669 @code{ecb-source-path} at least temporally for the current Emacs
5670 session. This option defines two things:
5674 Should only the root-part (which means for Unix-like systems always
5675 '/' and for windows-like systems the drive) of the new file be added
5676 as source-path to @code{ecb-source-path} or the whole directory-part?
5677 For remote-files (e.g. tramp, ange-ftp- or efs-files) the root-part is
5678 the complete host-part + the root-dir at that host (example:
5679 /berndl@@ecb.sourceforge.net:/ would be the root-part of
5680 /berndl@@ecb.sourceforge.net:/tmp/test.txt).
5682 Should this path be added for future sessions too?
5685 The value of this option is a cons-cell where the car is a boolean for
5686 1. and the cdr is a boolean for 2.
5688 A value of not nil for the car (1.) is reasonably if a user often
5689 opens files not via the ECB-browser which are not located in any of
5690 the paths of @code{ecb-source-path} because then only one path for
5691 each drive (windows) or the root-path (Unix) is added to the directory
5695 @defopt auto-expand-directory-tree
5696 Automatically expand the directory tree to the current source file.
5697 There are three options:
5700 @item @code{best}: Expand the best-matching source-path
5701 @item @code{first}: Expand the first matching source-path
5702 @item @code{nil}: Do not automatically expand the directory tree.
5706 @defopt after-directory-change-hook
5707 Hook which run directly after the selected directory has changed. This
5708 means not onyl after a click onto a directory in the directory-window
5709 of ECB but it means this hook runs always when the current directory
5710 changes regardless of the trigger of this change. So for example it
5711 runs also when you just switches from one buffer to another via
5712 @code{switch-to-buffer} or @code{switch-to-buffer-other-window} and
5713 the directory of these filebuffers is different but only when
5714 auto-synchronizing of the ECB-windows is on (see
5715 @code{ecb-window-sync}). It runs not when switching between buffers
5716 and the associated files reside in the same directory.
5718 Each function added to this hook will be called with two arguments:
5719 The directory which was current _before_ the directory-change-trigger
5720 and the directory which was now the current (i.e. after the trigger).
5722 Example: If you switch from a filebuffer ``~/.emacs'' to a filebuffer
5723 ``/tmp/test.txt'' then the functions of this hook will be called with
5724 the two arguments ``~'' and ``/tmp''.
5729 @defopt cache-directory-contents
5730 Cache contents of directories.
5732 This can be useful if @code{ecb-source-path} contains directories with
5733 many files and subdirs, especially if these directories are mounted
5734 net-drives (``many'' means here something > 500, dependent of the
5735 speed of the net-connection and the machine). Or if it contains
5736 remote-source-paths which means paths in the sense of tramp, ange-ftp
5737 or efs. For these directories actualizing the sources- and/or
5738 directories- buffer of ECB (if displayed in current layout!) can slow
5739 down dramatically so a caching increases speed a lot.
5741 The value of this option is a list where each element is a cons-cell
5745 (<dir-regexp> . <filenumber threshold>) with
5750 Regular expression a directory must match to be cached.
5751 @item <filenumber threshold>:
5752 Number of directory contents must exceed this number.
5755 A directory will only be cached if and only if the directory-name
5756 matches at least one rexexp of this option and its content-number
5757 exceeds the related threshold AND the directory-name matches NOT any
5758 regexp of @code{ecb-cache-directory-contents-not}!
5760 The cache entry for a certain directory will be refreshed and
5761 actualized only by using the POWER-click (see
5762 @code{ecb-primary-secondary-mouse-buttons}) in the directories-buffer
5763 of ECB (@pxref{Using the mouse}).
5765 Default-value: ECB caches the contents of all remote directories
5766 regardless of the size and all other directories if more than 50
5767 entries are contained.
5771 An entry @code{("/usr/home/john_smith/bigdir*" . 1000)} means the
5772 contents of every subdirectory of the home-directory of John Smith
5773 will be cached if the directory contains more than 1000 entries and
5774 its name begins with ``bigdir''.
5776 An entry @code{(".*" . 1000)} caches every directory which has more
5779 An entry @code{("^/\\([^:/]*@@\\)?\\([^@@:/]*\\):.*" . 0)} caches
5780 every remote (in the sense of tramp, ange-ftp or efs) directory
5781 regardless of the number of entries."
5783 Please note: If you want your home-dir being cached then you MUST NOT
5784 use ``~'' because ECB tries always to match full path-names!
5787 @defopt cache-directory-contents-not
5788 Do not cache the contents of certain directories. The value of this
5789 option is a list where the each element is a regular expression a
5790 directory must match if it should not being cached.
5792 If a directory-name matches at least one of the regexps of this option
5793 the directory-contents will never being cached. See
5794 @code{ecb-cache-directory-contents} to see when a directory will be
5797 This option can be useful when normally all directories with a certain
5798 amount of content (files and subdirs) should be cached but some
5799 special directories not. This can be achieved by:
5803 Setting @code{ecb-cache-directory-contents} to ((``.*'' . 500)):
5804 Caches all directories with more then 500 entries
5807 Setting @code{ecb-cache-directory-contents-not} to a value which
5808 matches these directories which should not being cached (e.g.
5809 (``/usr/home/john_smith'') excludes the HOME-directory of John Smith
5813 Please note: If you want your home-dir exclude from being cached then
5814 you MUST NOT use ``~'' because ECB tries always to match full
5820 @defopt directories-buffer-after-create-hook
5821 Local hook running after the creation of the directories-buffer. Every
5822 function of this hook is called once without arguments direct after
5823 creating the directories-buffer of ECB and it's local key-map. So for
5824 example a function could be added which performs calls of
5825 @code{local-set-key} to define new keybindings only for the
5826 directories-buffer of ECB.
5828 The following keys must not be rebind in the directories-buffer:
5829 @kbd{F2}, @kbd{F3} and @kbd{F4}
5833 @defopt directories-buffer-name
5834 Name of the ECB directory buffer. Because it is not a normal buffer
5835 for editing you should enclose the name with stars, e.g. `` *ECB
5838 If it is necessary for you you can get emacs-lisp access to the buffer-object of
5839 the ECB-directory-buffer by this name, e.g. by a call of @code{set-buffer}.
5841 Changes for this option at runtime will take affect only after
5842 deactivating and then activating ECB again!
5845 @defopt directories-menu-sorter
5846 Function which re-sorts the menu-entries of the directories buffer.
5848 If a function then this function is called to re-arrange the
5849 menu-entries of the combined menu-entries of the user-menu-extensions
5850 of @code{ecb-directories-menu-user-extension} and the built-in-menu
5851 @code{ecb-directories-menu}. If nil then no special sorting will be
5852 done and the user-extensions are placed in front of the
5855 The function get one argument, a list of menu-entries. For the format
5856 of this argument see @code{ecb-directories-menu-user-extension}. The
5857 function must return a new list in the same format. Of course this
5858 function can not only re-arrange the entries but also delete entries
5863 @defopt directories-menu-user-extension
5864 Static user extensions for the popup-menu of the directories buffer.
5865 Value is a list of elements of the following type: Each element
5866 defines a new menu-entry and is either:
5870 A list containing two sub-elements, whereas the first is the function
5871 (a function symbol) being called if the menu-entry is selected and the
5872 second is the name of the menu-entry.
5875 A one-element-list and the element is the string ``---'': Then a
5876 non-selectable menu-separator is displayed.
5879 A list where the first element is the title of the submenu displayed
5880 in the main-menu and all other elements are either menu-commands (see
5881 1) or separators (see 2) or another submenu (see c). This allows deep
5882 nested menu-submenu-structures. Currently a level of 4 is allowed but
5883 in general there could be an infinite depth of nesting but it makes no
5884 sense - if possible at all - to define infinite nested
5885 defcustom-types. So there is a limit of 4 levels but tis is not a hard
5886 limit: Just increase the value of the @code{ecb-max-submenu-depth}
5887 @strong{BEFORE} first loading ECB!
5890 The function of a menu-command must follow the following guidelines:
5891 Such a function must be defined with the macro
5892 @code{tree-buffer-defpopup-command}! This macro defines a new
5893 popup-command whereas the newly defined command gets one argument
5894 @var{NODE}. See the docstring of @code{tree-buffer-defpopup-command}
5895 for further details.
5897 Example for the definition of such a menu-function:
5900 (tree-buffer-defpopup-command ecb-my-special-dir-popup-function
5901 "Prints the name of the directory of the node under point."
5902 (let ((node-data=dir (tree-node-get-data node)))
5903 (message ``Dir under node: %s'' node-data=dir)))
5906 Per default the static user-extensions are added at the beginning of
5907 the built-in menu-entries of @code{ecb-directories-menu} but the whole
5908 menu can be re-arranged with @code{ecb-directories-menu-sorter}.
5910 These menu-extensions are static. A dynamic menu-extension can be
5911 achieved via @code{ecb-directories-menu-user-extension-function}.
5914 @defopt directories-menu-user-extension-function
5915 Dynamic user extensions for the popup-menu of the directories buffer.
5916 A function which has to return a list in the same format like the
5917 option @code{ecb-directories-menu-user-extension}. This function is
5918 called when the user opens the popup-menu for the directories buffer.
5920 Per default the dynamic user-extensions are added in front of the
5921 static extensions of @code{ecb-directories-menu-user-extension} but
5922 the whole menu can be re-arranged with
5923 @code{ecb-directories-menu-sorter}.
5928 @defopt display-default-dir-after-start
5929 Automatically display current default-directory after activating ECB.
5931 If a file-buffer is displayed in the current active edit-window then
5932 ECB synchronizes its tree-buffers to this file-buffer - at least if
5933 the option @code{ecb-window-sync} it not nil. So for this situation
5934 @code{ecb-display-default-dir-after-start} takes no effect but this
5935 option is for the case if no file-buffer is displayed in the
5936 edit-window after startup:
5938 If true then ECB selects autom. the current default-directory after
5939 activation even if no file-buffer is displayed in the current active
5940 edit-window. This is useful if ECB is autom. activated after startup
5941 of Emacs and Emacs is started without a file-argument. So the
5942 directory from which the startup has performed is auto. selected in
5943 the ECB-directories buffer and the ECB-sources buffer displays the
5944 contents of this directory.
5948 @defopt excluded-directories-regexps
5949 Directories that should not be included in the directories list. The
5950 value of this variable should be a list of regular expression.
5953 @defopt prescan-directories-for-emptyness
5954 Prescan directories for emptyness. ECB does this so directories are
5955 displayed as empty in the directories-buffer even without
5956 user-interaction (i.e. in previous ECB-versions the emptyness of a
5957 directory has been first checked when the user has clicked onto a
5958 directory). ECB optimizes this check as best as possible but if a
5959 directory contains a lot of subdirectories which contain in turn a lot
5960 of entries, then expanding such a directory or selecting it would take
5961 of course more time as without this check - at least at the first time
5962 (all following selects of a directory uses the cached information if
5963 its subdirectories are empty or not). Therefore ECB performs this
5964 check stealthy (see @code{ecb-stealthy-tasks-delay}) so normally there
5965 should no performance-decrease or additional waiting-time for the
5966 user. There is one exception: For remote directories (in the sense of
5967 tramp, ange-ftp, or efs) this check can descrease performance even if
5968 performed stealthy and interruptable. Therefore this option offers
5969 three possible settings:
5973 Switch on this feature
5975 @item @code{unless-remote}
5976 Switch on this feature but not for remote directories. The term
5977 ``remote'' means here directories which are used via tramp, ange-ftp
5978 or efs. So mounted directories are counted not as remote directories
5979 here even if such a directory is maybe hosted on a remote machine. But
5980 normally only directories in a LAN are mounted so there should be no
5981 performance-problems with such mounted directories.
5984 Switch off this feature completely.
5987 The option @code{ecb-prescan-directories-exclude-regexps} offers are
5988 more fine granularity to exclude certain directories from this
5992 @defopt host-accessible-check-valid-time
5993 Time in seconds a cached accessible-state of a remote host is valid.
5994 This option is a list where each element specifies how long for a
5995 certain remote host the cached ping-state (i.e. if the host is
5996 accessible or not) should be valid. During this time-intervall ECB
5997 pings such a remote host only once, all other checks use the cached
5998 value of that real check. But it the cached value is older than the
5999 value of this option ECB will ping again.
6001 Per default ECB discards after 1 minute the cached ping-state of each
6002 remote host. But if you are sure that a certain remote host is always
6003 accessible (i.e. means in consequence that you are always online when
6004 working with ECB and remote-paths) then add an entry to this option
6005 with a high valid-interval.
6007 Examples: An entry (``.*sourceforge.*'' . 3600) ensures that all
6008 remote hosts machting the string ``sourceforge'' will only once pinged
6009 during one hour. Or (``.*'' . 300) would ensure that every remote host
6010 would be pinged only once during 5 minutes.
6013 @defopt ping-options
6014 List of options for the ping program. These options can be used to
6015 limit how many ICMP packets are emitted. Ping is used to test if a
6016 remote host of a remote path (e.g. a tramp-, ange-ftp- or efs-path) is
6017 accessible See also @code{ecb-ping-program}.
6020 @defopt ping-program
6021 Program to send network test packets to a host. See also
6022 @code{ecb-ping-options}.
6025 @defopt prescan-directories-exclude-regexps
6026 Which directories should be excluded from the empty-prescan. If a
6027 directory matches any of the regexps of this option it will not be
6028 prescanned for emptyness - This option takes only effect if
6029 @code{ecb-prescan-directories-for-emptyness} is not nil.
6033 @defopt show-sources-in-directories-buffer
6034 Show source files in directories buffer.
6038 Paths where to find code sources. Each path can have an optional alias
6039 that is used as it's display name. If no alias is set, the path is
6040 used as display name.
6044 Paths where to find code sources. Each path can have an optional alias
6045 that is used as it's display name. If no alias is set, the path is
6046 used as display name.
6048 Lisp-type of tis option: The value must be a list L whereas each
6049 element of L is either
6052 a simple string which has to be the full path of a directory (this
6053 string is displayed in the directory-browser of ECB) or
6056 a 2-element list whereas the first element is the full path of a
6057 directory (string) and the second element is an arbitrary alias
6058 (string) for this directory which is then displayed instead of the
6059 underlying directory.
6065 @defopt use-speedbar-instead-native-tree-buffer
6066 If true then uses speedbar for directories, sources or methods. This
6067 means that speedbar is integrated in the ECB-frame and is displayed in
6068 that window normally displaying the standard ECB-directories-buffer,
6069 ECB-sources-buffer or ECB-methods-buffer.
6071 This option takes effect in all layouts which contain either a
6072 directory window, a sources window or a method window.
6074 This option can have four valid values:
6076 @item @code{nil}: Do not use speedbar (default)
6077 @item @code{dir}: Use speedbar instead of the standard directories-buffer
6078 @item @code{source}: Use speedbar instead of the standard sources-buffer
6079 @item @code{method}: Use speedbar instead of the standard methods-buffer
6082 Note: For directories and sources a similar effect and usability is
6083 available by setting this option to @code{nil} (or @code{method}) and
6084 setting @code{ecb-show-sources-in-directories-buffer} to not
6085 @code{nil}, because this combination displays also directories and
6086 sources in one window.
6088 @code{ecb-use-speedbar-instead-native-tree-buffer} is for people who
6089 like the speedbar way handling directories and source-files or methods
6090 and want it in conjunction with ECB.
6094 @node ecb-sources, ecb-methods, ecb-directories, Customizable options
6095 @subsection Group ecb-sources
6098 This group contains settings for the sources-buffer in the ECB:
6100 @defopt read-only-check-exclude-regexps
6101 Which directories should be excluded from the sources-read-only-check.
6102 If a directory matches any of the regexps of this option their sources
6103 will not be checked if they are writable - This option takes only
6104 effect if @code{ecb-sources-perform-read-only-check} is not nil.
6107 @defopt show-source-file-extension
6108 Show the file extension of source files.
6111 @defopt source-file-regexps
6112 Specifies which files are shown as source files.
6114 This is done on directory-base, which means for each directory-regexp
6115 the files to display can be specified. If more than one
6116 directory-regexp matches the current selected directory then always the
6117 first one (and its related file-exclude/include-regexps) is used! If
6118 no directory-regexp matches then all files are displayed for the
6119 currently selected directory.
6121 Important note: It is recommended that the *LAST* element of this list
6122 should contain an always matching directory-regexp (@code{".*"})!
6124 So the value of this option is a list of cons-cells where the car is a
6125 directory regexp and the cdr is a 2 element list where the first
6126 element is a list of exclude regexps and the second element is a list
6127 of include regexps. A file is displayed in the source-buffer of ECB
6128 iff: The file does not match any of the exclude regexps OR the file
6129 matches at least one of the include regexps.
6131 But regardless of the value of this option a file F is never displayed
6132 in the sources-buffer if the directory matches
6133 @code{ecb-sources-exclude-cvsignore} and the directory contains a file
6134 .cvsignore which contains F as an entry!
6136 There are three predefined and useful combinations of an exclude and
6142 @item All, but no backup, object, lib or ini-files (except .emacs and .gnus). This
6143 means all files except those starting with ``.'', ``#'' or ending with
6144 ``~'', ``.elc'', ``.obj'', ``.o'', ``.lib'', ``.dll'', ``.a'',
6145 ``.so''. (but including .emacs and .gnus)
6147 @item Common source file types (.c, .java etc.)
6150 In addition to these predefined values a custom exclude and include
6151 combination can be defined.
6153 Tips for the directory- and file-rexexps: @code{"$^"} matches no
6154 files/directories, @code{".*"} matches all files/directories.
6157 @defopt sources-buffer-after-create-hook
6158 Local hook running after the creation of the sources-buffer. Every
6159 function of this hook is called once without arguments direct after
6160 creating the sources-buffer of ECB and it's local key-map. So for
6161 example a function could be added which performs calls of
6162 @code{local-set-key} to define new keybindings only for the
6163 sources-buffer of ECB.
6167 @defopt sources-buffer-name
6168 Name of the ECB sources buffer. Because it is not a normal buffer for
6169 editing you should enclose the name with stars, e.g. ``*ECB Sources*''.
6171 If it is necessary for you you can get emacs-lisp access to the
6172 buffer-object of the ECB-sources-buffer by this name, e.g. by a call
6173 of @code{set-buffer}.
6175 Changes for this option at runtime will take affect only after
6176 deactivating and then activating ECB again!
6180 @defopt sources-exclude-cvsignore
6181 Specify if files contained in a @file{.cvsignore} should be
6184 Value is a list of regular expressions or nil. If you want to exclude
6185 files listed in a @file{.cvsignore}-file from being displayed in the
6186 ecb-sources-buffer then specify a regexp for such a directory.
6188 If you want to exclude the contents of @file{.cvsignore}-files for
6189 every directory then you should add one regexp ``.*'' which matches
6192 If you never want to exclude the contents of @file{.cvsignore}-files
6193 then set this option to nil.
6197 @defopt sources-menu-sorter
6198 Function which re-sorts the menu-entries of the directories buffer.
6200 If a function then this function is called to sort the menu-entries of
6201 the combined menu-entries of the user-menu-extensions of
6202 @code{ecb-sources-menu-user-extension} and the built-in-menu
6203 @code{ecb-sources-menu}. If nil then no special sorting will be done
6204 and the user-extensions are placed in front of the built-in-entries.
6206 For the guidelines for such a sorter-function see
6207 @code{ecb-directories-menu-sorter}.
6211 @defopt sources-menu-user-extension
6212 Static user extensions for the popup-menu of the sources buffer. For
6213 further explanations see @code{ecb-directories-menu-user-extension}.
6215 The node-argument of a menu-function contains as data the filename of
6216 the source for which the popup-menu has been opened.
6218 Per default the static user-extensions are added at the beginning of
6219 the built-in menu-entries of @code{ecb-sources-menu} but the whole
6220 menu can be re-arranged with @code{ecb-sources-menu-sorter}.
6223 @defopt sources-menu-user-extension-function
6224 Dynamic user extensions for the popup-menu of the sources buffer. A
6225 function which has to return a list in the same format like the option
6226 @code{ecb-sources-menu-user-extension}. This function is called when
6227 the user opens the popup-menu for the sources buffer.
6229 Per default the dynamic user-extensions are added in front of the
6230 static extensions of @code{ecb-sources-menu-user-extension} but the
6231 whole menu can be re-arranged with @code{ecb-sources-menu-sorter}.
6235 @defopt sources-perform-read-only-check
6236 Check if source-items in the tree-buffers are read-only. If a
6237 sourcefile is read-only then it will be displayed with that face set
6238 in the option @code{ecb-source-read-only-face}.
6240 Because this check can be take some time if files are used via a
6241 mounted net-drive ECB performs this check stealthy (see
6242 @code{ecb-stealthy-tasks-delay}) so normally there should no
6243 performance-decrease or additional waiting-time for the user. But to
6244 get sure this option offers three choices: @code{t},
6245 @code{unless-remote} and @code{nil}. See
6246 @code{ecb-prescan-directories-for-emptyness} for an explanation for
6247 these three choices.
6249 The option @code{ecb-read-only-check-exclude-regexps} offers are more
6250 fine granularity to exclude the sources of certain directories from
6251 the read-only state-check.
6255 @defopt sources-sort-ignore-case
6256 Ignore case for sorting the source-files of the Sources-buffer. See
6257 also @code{ecb-sources-sort-method}.
6260 @defopt sources-sort-method
6261 Defines how the source files are sorted.
6266 @item @code{extension}:
6267 Sorting first by extension and then by name.
6269 No sorting, means source files are displayed in the sequence returned
6270 by @code{directory-files} (called without sorting).
6273 See also @code{ecb-sources-sort-ignore-case}
6277 @node ecb-methods, ecb-history, ecb-sources, Customizable options
6278 @subsection Group ecb-methods
6281 This group contains settings for the methods-buffer in the ECB:
6283 @defopt auto-expand-tag-tree
6284 Expand the methods-tag-tree automatically if node invisible.
6286 This option has only an effect if option @code{ecb-highlight-tag-with-point} is
6287 switched on too. There are three possible choices:
6290 No auto. expanding of the method buffer.
6291 @item @code{expand-spec}:
6292 Auto expand the method-buffer nodes if the node belonging to current
6293 tag under point is invisible because its parent-node is collapsed.
6294 But expanding is only done if the type of the tag under point in the
6295 edit-buffer is contained in @code{ecb-methods-nodes-expand-spec}.
6297 Like expand-spec but expands all tags regardless of the setting in
6298 @code{ecb-methods-nodes-expand-spec}.
6301 This options takes only effect for semantic-sources - means sources
6302 supported by semantic!
6305 @defopt auto-expand-tag-tree-collapse-other
6306 Auto. expanding the tag-tree collapses all not related nodes. There
6307 are several choices:
6310 @item Only if on tag:
6311 This means collapsing all nodes which have no relevance for the
6312 currently highlighted node will be collapsed, because they are not
6313 necessary to make the highlighted node visible. But do this only if
6314 point stays onto a tag in the selected edit-window.
6317 Same as before but collapse also when point doesn't stays on a tag
6318 (e.g. between two defuns in elisp) in the selected edit-window. This
6319 means in such a situation a full collapsing of the methods-buffer.
6322 Do not automatically collapse the methods-buffer.
6327 @defopt auto-update-methods-after-save
6328 Automatically updating the ECB method buffer after saving a source.
6331 @defopt default-tag-filter
6332 Default tag-filters for certain files. This option allow to define
6333 default tag-filters for certain files which are applied automatically
6334 after loading such a file into a buffer. The possible filters are the
6335 same as offered by the command @code{ecb-methods-filter} and they are
6336 applied in the same manner - the only difference is they are applied
6337 automatically. Please be aware that symbol-filters (e.g.
6338 protection-symbols like public or private) must not be inserted with
6339 quotes whereas a filter-regexp has to be inserted with surrounding
6340 double-quotes! In addition backslashes in a regexp have to be doubled!
6342 For each file-spec (a major-mode plus a file-regexp which both specify
6343 a file for which filters should be applied) there can be as much
6344 filters as needed - they are layered like with
6345 @code{ecb-methods-filter} too.
6347 Tag-classes which are completely hidden or excluded by the option
6348 @code{ecb-show-tags} will never being displayed in the Methods-buffer
6349 regardless of the filters of this option!
6352 @defopt display-image-icons-for-semantic-tags
6353 Display nice and pretty icons for semantic-tags in the Methods-buffer.
6354 This option takes only effect if Emacs can display images and if
6355 @code{ecb-tree-buffer-style} is set to @code{image}.
6358 @defopt exclude-parents-regexp
6359 Regexps which parent classes should not be shown in the methods buffer
6360 (see also @code{ecb-show-parents}). If nil then all parents will be
6361 shown if @code{ecb-show-parents} is not nil.
6363 This options takes only effect for semantic-sources - means sources
6364 supported by semantic!
6367 @defopt expand-methods-switch-off-auto-expand
6368 Switch off auto expanding in the ECB-method buffer. If on then auto
6369 expanding is switched off after explicit expanding or collapsing by
6370 @code{ecb-expand-methods-nodes}.
6372 This is done with @code{ecb-toggle-auto-expand-tag-tree} so after
6373 the switch off the auto expanding feature can again switched on
6376 But after explicitly expanding/collapsing the methods-buffer to a
6377 certain level the auto. expanding could undo this when the node
6378 belonging to current tag under point in the current active edit-window
6379 is invisible after @code{ecb-expand-methods-nodes} - then the auto.
6380 expand feature would make this node immediately visible and destroys
6381 the explicitly set expand-level.
6385 @defopt font-lock-tags
6386 Adds font-locking (means highlighting) to the ECB-method buffer.
6388 This options takes only effect for semantic-sources - means sources
6389 supported by semantic!
6392 @defopt highlight-tag-with-point
6393 How to highlight the method or variable under the cursor.
6396 @item @code{highlight-scroll}:
6397 Always scroll the method buffer, so the current method of the
6398 edit-window is highlighted in the method-window.
6399 @item @code{highlight}:
6400 Only highlight the current method of the edit window in the
6401 method window if the method is visible in the method-window.
6403 No highlighting is done.
6406 See also @code{ecb-highlight-tag-with-point-delay}.
6408 This options takes only effect for semantic-sources - means sources
6409 supported by semantic!
6412 @defopt highlight-tag-with-point-delay
6413 Time Emacs must be idle before current tag is highlighted. If nil
6414 then there is no delay, means current tag is highlighted
6415 immediately. A small value of about 0.25 seconds saves CPU resources
6416 and you get even though almost the same effect as if you set no delay.
6417 But such a delay prevents also ``jumping backward/forward'' during
6418 scrolling within java-classes if point goes out of method-definition
6419 into class-definition. Therefore the default value is a delay of 0.25
6422 This options takes only effect for semantic-sources - means sources
6423 supported by semantic!
6426 @defopt methods-buffer-after-create-hook
6427 Local hook running after the creation of the methods-buffer. Every
6428 function of this hook is called once without arguments direct after
6429 creating the methods-buffer of ECB and it's local key-map. So for
6430 example a function could be added which performs calls of
6431 @code{local-set-key} to define new keybindings only for the
6432 methods-buffer of ECB.
6436 @defopt methods-buffer-name
6437 Name of the ECB methods buffer. Because it is not a normal buffer for
6438 editing you should enclose the name with stars, e.g. `` *ECB
6441 If it is necessary for you you can get emacs-lisp access to the
6442 buffer-object of the ECB-methods-buffer by this name, e.g. by a call
6443 of @code{set-buffer}.
6445 Changes for this option at runtime will take affect only after
6446 deactivating and then activating ECB again!
6449 @defopt methods-filter-replace-existing
6450 How the methods-filter should be applied to existing filters. There
6451 are three different choices:
6455 This is the default and means that calling @code{ecb-methods-filter}
6456 always adds the new filter on top of already existing filters. So you
6457 can combine several filter to one combined like this example: 'Display
6458 only all public methods having the string ``test'' in its name.' With
6459 this setting the filters can only be cleared by calling
6460 @code{ecb-methods-filter} and then choosing ``nothing''.
6462 @item @code{always}:
6463 This means that @code{ecb-methods-filter} always clears a previous
6464 filter before applying the new one.
6467 ECB asks if the new filter should replace the existing ones.
6473 @defopt methods-menu-sorter
6474 Function which re-sorts the menu-entries of the directories buffer.
6476 If a function then this function is called to sort the menu-entries of
6477 the combined menu-entries of the user-menu-extensions of
6478 @code{ecb-methods-menu-user-extension} and the built-in-menu
6479 @code{ecb-methods-menu}. If nil then no special sorting will be done
6480 and the user-extensions are placed in front of the built-in-entries.
6482 For the guidelines for such a sorter-function see
6483 @code{ecb-directories-menu-sorter}.
6487 @defopt methods-menu-user-extension
6488 Static user extensions for the popup-menu of the methods buffer. For
6489 further explanations see @code{ecb-directories-menu-user-extension}.
6491 The node-argument of a menu-function contains as data the semantic-tag
6492 of the method/variable/tag for which the popup-menu has been opened.
6494 Per default the static user-extensions are added at the beginning of
6495 the built-in menu-entries of @code{ecb-methods-menu} but the whole
6496 menu can be re-arranged with @code{ecb-methods-menu-sorter}.
6499 @defopt methods-menu-user-extension-function
6500 Dynamic user extensions for the popup-menu of the methods buffer. A
6501 function which has to return a list in the same format like the option
6502 @code{ecb-methods-menu-user-extension}. This function is called when
6503 the user opens the popup-menu for the methods buffer. For an example
6504 how such a function can be programmed see
6505 @code{ecb-methods-menu-editwin-entries}.
6507 Per default the dynamic user-extensions are added in front of the
6508 static extensions of @code{ecb-methods-menu-user-extension} but the
6509 whole menu can be re-arranged with @code{ecb-methods-menu-sorter}.
6513 @defopt methods-nodes-collapse-spec
6514 Semantic tag-types collapsed by @code{ecb-expand-methods-nodes}.
6515 For valid values of this option see @code{ecb-methods-nodes-expand-spec}!
6517 This options takes only effect for semantic-sources - means sources
6518 supported by semantic!
6522 @defopt methods-nodes-expand-spec
6523 Semantic tag-types expanded by @code{ecb-expand-methods-nodes}.
6525 The value of this option is either the symbol @code{all} (all tags
6526 are expanded regardless of their type) or a list of symbols where each
6527 symbol is a valid semantic tag-type. For a description of semantic
6528 tag types see option @code{ecb-show-tags}.
6530 But this option also defines if bucket-nodes in the ECB-method-buffer
6531 (e.g. ``[Variables]'') should be expanded. Therefore valid symbols for
6532 this list are also all cars of the variable returned by
6533 @code{ecb--semantic-symbol->name-assoc-list}.
6535 If there is a bucket-name (the node-name stripped of the settings in
6536 @code{ecb-bucket-node-display}) which is not contained as cdr in the
6537 value returned by @code{ecb--semantic-symbol->name-assoc-list} then
6538 the symbol with this bucket-name as name is also a valid symbol for
6539 this list. Example: In ECB there are buckets ``[Parents]''. The
6540 bucket-name is ``Parents'' and the valid symbol-name is then
6543 This options takes only effect for semantic-sources - means sources
6544 supported by semantic!
6547 @defopt methods-separate-prototypes
6548 Separate function-prototypes from the real functions. This is for
6549 example useful for C++ and C because these languages distinct between
6550 a method-prototype (rsp. function-prototype for C) and the method
6551 (rsp. function for C) itself. If this option is not nil then ECB
6552 separates the prototypes from the real function/methods. Then with
6553 @code{ecb-show-tags} the user can define different display-settings
6554 for each of them. If this option is nil then the prototypes and the
6555 real functions are filled in the same bucket and displayed plain and
6556 there is no sorting between prototypes and functions possible. If this
6557 option is switched on then it is senseful that @code{ecb-show-tags}
6558 contains for all modes which distinct between prototypes and real
6559 functions/methods two entries for the tag-type 'function - see the
6560 documentation of this option.
6563 @defopt post-process-semantic-taglist
6564 Define mode-dependent post-processing for the semantic-taglist. This
6565 is an alist where the car is a major-mode symbol and the cdr is a list
6566 of function-symbols of functions which should be used for
6567 post-processing the taglist (returned by
6568 @code{ecb--semantic-bovinate-toplevel}) for a buffer in this
6569 major-mode. The first function in the list is called with current
6570 semantic taglist of current buffer and must return a valid taglist
6571 again. All other functions are called with the result-taglist of its
6572 preceding function and have to return a new taglist again.
6574 For oo-programming languages where the methods of a class can be
6575 defined outside the class-definition (e.g. C++, Eieio) the function
6576 @code{ecb-group-function-tags-with-parents} can be used to get a much
6577 better method-display in the methods-window of ECB, because all method
6578 implementations of a class are grouped together.
6580 Another senseful usage is to filter out certain tags, e.g. prototype
6581 tags in @code{c-mode}. For this you can set
6582 @code{ecb-filter-c-prototyp-tags}.
6584 This options takes only effect for semantic-sources - means sources
6585 supported by semantic!
6588 @defopt show-only-positioned-tags
6589 Show only nodes in the method-buffer which are ``jump-able''. If not nil
6590 then ECB displays in the method-buffer only nodes which are
6591 ``jump-able'', i.e. after selecting it by clicking or with RET then ECB
6592 jumps to the corresponding location in the edit-window. Example: With
6593 CLOS or Eieio source-code there can exist some position-less nodes like
6594 variable-attributes in a @code{defclass} form which are only displayed
6595 if this option is nil. Displaying such nodes can be senseful even if
6596 they can not be jumped.
6598 This options takes only effect for semantic-sources - means sources
6599 supported by semantic!
6603 How to show tags in the methods buffer first time after find-file.
6604 This functionality is set on a major-mode base, i.e. for every
6605 major-mode a different setting can be used. The value of this option
6606 is a list of cons-cells:
6608 The car is either a major-mode symbol or the special symbol 'default
6609 which means if no setting for a certain major-mode is defined then the
6610 cdr of the 'default cons-cell is used. This option should always
6611 contain a default-setting!
6613 The cdr is a list where each element represents a type of tags:
6616 (<tag type> <display type> <sort method>)
6619 There can be more than 1 element for a certain <tag type>. This is for
6620 example useful for C++ and C because these languages distinct between
6621 a method-prototype (rsp. function-prototype for C) and the method
6622 (rsp. function for C) itself. The default value of these option
6623 contains two entries for <tag type> is @code{function} whereas the
6624 first one is responsible for the ``real'' methods (rsp. functions) and
6625 the second one for the prototypes. So if the methods should be
6626 flattened and the prototypes collapsed the show-tags-list for C++ and
6627 C must contain two entries for <tag type> @code{function}, the first
6628 one defined as @code{flattened} and the second one defined as
6631 The tags in the methods buffer are displayed in the order as they appear in
6636 A Semantic tag type symbol (function, variable, rule, include etc.)
6637 or one of the following:
6640 @item @code{t}: All tag types not specified anywhere else in the list.
6641 @item @code{parent}: The parents of a type.
6644 @item <display type>
6645 A symbol which describes how the tags of this type shall be shown:
6648 @item @code{expanded}: The tags are shown in an expanded node.
6649 @item @code{collapsed}: The tags are shown in a collapsed node.
6650 @item @code{flattened}: The tags are added to the parent node.
6651 @item @code{hidden}: The tags are not shown.
6655 A symbol describing how to sort the tags of this type:
6659 Sort by the tag name.
6660 @item @code{access}:
6661 Sort by tag access (public, protected, private) and then by name.
6663 Don't sort tags. They appear in the same order as in the source
6669 This options takes only effect for semantic-sources - means sources
6670 supported by semantic!
6673 @defopt tag-display-function
6674 Function to use for displaying tags in the methods buffer. This
6675 functionality is set on major-mode base, i.e. for every major-mode a
6676 different function can be used. The value of this option is a list of
6681 The car is either a major-mode symbol or the special symbol 'default which
6682 means if no function for a certain major-mode is defined then the cdr of
6683 the 'default cons-cell is used.
6685 The cdr is the function used for displaying a tag in the related
6689 Every function is called with 3 arguments:
6693 @item The parent-tag of tag (can be nil)
6694 @item The value of @code{ecb-font-lock-tags}.
6697 Every function must return the display of the tag as string,
6698 colorized if the third argument is not nil.
6700 The following functions are predefined:
6704 For each element E of @code{ecb--semantic-format-function-alist}
6705 exists a function with name ``ecb--<(cdr E)>''. These functions are
6706 just aliase to the builtin format-functions of semantic. See the
6707 docstring of these functions to see what they do. Example:
6708 (semantic-name-nonterminal . semantic-format-tag-name) is an element
6709 of @code{ecb--semantic-format-function-alist}. Therefore the
6710 alias-function for this element is named
6711 @code{ecb--semantic-format-tag-name}.
6714 For every cdr in @code{ecb--semantic-format-function-alist} with name
6715 ``semantic-XYZ'' a function with name ``ecb-XYC'' is predefined. The
6716 differences between the semantic- and the ECB-version are:
6720 The ECB-version displays for type tags only the type-name and nothing
6721 else (exception: In c++-mode a template specifier is appended to the
6722 type-name if a template instead a normal class).
6724 The ECB-version displays type-tags according to the setting in
6725 @code{ecb-type-tag-display}. This is useful for better recognizing
6726 different classes, structs etc. in the ECB-method window.
6729 For all tags which are not types the display of the ECB-version is
6730 identical to the semantic version. Example: For
6731 @code{ecb--semantic-format-tag-name} (one of the builtin semantic
6732 formatters) the pendant is @code{ecb-format-tag-name}.
6735 This functionality also allows the user to display tags as UML. To
6736 enable this functionality set the function for a major-mode \(e.g.
6738 @code{ecb--semantic-format-tag-uml-concise-prototype},
6739 @code{ecb--semantic-format-tag-uml-prototype}, or
6740 @code{ecb--semantic-format-tag-uml-abbreviate} the ECB-versions of
6743 If the value is @code{nil}, i.e. neither a function for a major-mode
6744 is defined nor the special 'default, then
6745 @code{ecb--semantic-format-tag-prototype} is used for displaying the
6748 This options takes only effect for semantic-sources - means sources
6749 supported by semantic!
6752 @defopt tag-jump-sets-mark
6753 Set the mark after jumping to a tag from the ECB-method buffer. If
6754 set the user can easily jump back.
6757 @defopt tag-visit-post-actions
6758 Actions to perform after visiting a tag from the Method-buffer. With
6759 this option actions can be added which will be performed after
6760 visiting the start of the tag in the source-buffer.
6762 This functionality is set on a @code{major-mode} base, i.e. for every
6763 @code{major-mode} a different setting can be used. The value of this
6764 option is a list of cons-cells:
6767 The car is either a @code{major-mode} symbol or the special symbol
6771 The cdr is a list of action-functions or nil.
6774 ECB first performs all actions defined for the special symbol 'default
6775 (if any) and then all actions defined for current @code{major-mode}
6778 ECB offers some predefined senseful action-functions. Currently there
6779 are: @code{ecb-tag-visit-highlight-tag-header}
6780 @code{ecb-tag-visit-smart-tag-start}
6781 @code{ecb-tag-visit-recenter} @code{ecb-tag-visit-recenter-top}
6782 @code{ecb-tag-visit-goto-doc-start}
6783 @code{ecb-tag-visit-narrow-tag} See the documentation of these
6784 function for details what they do.
6786 But you can add any arbitrary function if the following conditions are
6787 fulfilled: The function gets the semantic tag as argument, returns the
6788 (new) point after finishing its job and the function must not put the
6789 point outside the tag-boundaries of the tag-argument.
6794 @defopt type-tag-display
6795 How to display semantic type-tags in the methods buffer. Normally
6796 all tag displaying, colorizing and facing is done by semantic
6797 according to the value returned by
6798 @code{ecb--semantic-format-face-alist} and the semantic
6799 display-function (e.g. one from
6800 @code{ecb--semantic-format-tag-functions}). But sometimes a finer
6801 distinction in displaying the different type specifiers of type-tags
6802 can be useful. For a description when this option is evaluated look at
6803 @code{ecb-tag-display-function}!
6805 This functionality is set on a major-mode base, i.e. for every
6806 major-mode a different setting can be used. The value of this option
6807 is a list of cons-cells:
6811 The car is either a major-mode symbol or the special symbol 'default which
6812 means if no setting for a certain major-mode is defined then the cdr of
6813 the 'default cons-cell is used.
6816 The cdr is a list of 3-element-lists:
6820 First entry is a semantic type specifier in string-form. Current
6821 available type specifiers are for example ``class'', ``interface'',
6822 ``struct'', ``typedef'' and ``enum''. In addition to these ones there
6823 is also a special ECB type specifier ``group'' which is related to
6824 grouping tags (see @code{ecb-post-process-semantic-taglist} and
6825 @code{ecb-group-function-tags-with-parents}). Any arbitrary
6826 specifier can be set here but if it is not ``group'' or not known by
6827 semantic it will be useless.
6829 Second entry is a flag which indicates if the type-specifier string
6830 from (1.) itself should be removed (if there is any) from the display.
6832 Third entry is the face which is used in the ECB-method window to
6833 display type-tags with this specifier. ECB has some predefined faces
6834 for this (@code{ecb-type-tag-class-face},
6835 @code{ecb-type-tag-interface-face}, @code{ecb-type-tag-struct-face},
6836 @code{ecb-type-tag-typedef-face}, @code{ecb-type-tag-union-face},
6837 @code{ecb-type-tag-enum-face} and @code{ecb-type-tag-group-face}) but
6838 any arbitrary face can be set here. This face is merged with the faces
6839 semantic already uses to display a tag,
6840 i.e. the result is a display where all face-attributes of the ECB-face
6841 take effect plus all face-attributes of the semantic-faces which are not
6842 set in the ECB-face (with XEmacs this merge doesn't work so here the
6843 ECB-face replaces the semantic-faces; this may be fixed in future
6848 The default value is nil means there is no special ECB-displaying of
6849 type-tags in addition to the displaying and colorizing semantic
6850 does. But a value like the following could be a useful setting:
6855 ("class" t ecb-type-tag-class-face)
6856 ("group" nil ecb-type-tag-group-face))
6858 ("struct" nil ecb-type-tag-struct-face)
6859 ("typedef" nil ecb-type-tag-typedef-face)))
6863 This means that in @code{c-mode} only ``struct''s and ``typedef''s are
6864 displayed with special faces (the specifiers itself are not removed)
6865 and in all other modes ``class''s and grouping-tags (see
6866 @code{ecb-tag-display-function},
6867 @code{ecb-group-function-tags-with-parents}) have special faces and
6868 the ``class'' specifier-string is removed from the display.
6870 This options takes only effect for semantic-sources - means sources
6871 supported by semantic!
6874 @defopt type-tag-expansion
6875 Default expansion of semantic type-tags. Semantic groups type-tags in
6876 different type-specifiers. Current available type specifiers are for
6877 example ``class'', ``interface'', ``struct'', ``typedef'', ``union''
6878 and ``enum''. In addition to these ones there is also a special ECB
6879 type-specifier ``group'' which is related to grouping tags (see
6880 @code{ecb-post-process-semantic-taglist}).
6882 This option defines which type-specifiers should be expanded at
6883 file-open-time. Any arbitrary specifier can be set here but if it is
6884 not ``group'' or not known by semantic it will be useless.
6886 This functionality is set on a major-mode base, i.e. for every
6887 major-mode a different setting can be used. The value of this option
6888 is a list of cons-cells:
6892 The car is either a major-mode symbol or the special symbol
6893 @code{default} which means if no setting for a certain major-mode is
6894 defined then the cdr of the @code{default} cons-cell is used.
6897 The cdr is either a list of type-specifiers which should be expanded
6898 at file-open-time or the symbol @code{all-specifiers} (then a type-tag
6899 is always expanded regardless of its type-specifier).
6902 This options takes only effect for semantic-sources - means sources
6903 supported by semantic!
6907 @node ecb-history, ecb-layout, ecb-methods, Customizable options
6908 @subsection Group ecb-history
6911 This group contains settings for the history-buffer in the ECB:
6913 @defopt history-buffer-after-create-hook
6914 Local hook running after the creation of the history-buffer. Every
6915 function of this hook is called once without arguments direct after
6916 creating the history-buffer of ECB and it's local key-map. So for
6917 example a function could be added which performs calls of
6918 @code{local-set-key} to define new keybindings only for the
6919 history-buffer of ECB.
6923 @defopt history-buffer-name
6924 Name of the ECB history buffer. Because it is not a normal buffer for
6925 editing you should enclose the name with stars, e.g. ``*ECB
6928 If it is necessary for you you can get emacs-lisp access to the
6929 buffer-object of the ECB-history-buffer by this name, e.g. by a call
6930 of @code{set-buffer}.
6932 Changes for this option at runtime will take affect only after
6933 deactivating and then activating ECB again!
6936 @defopt history-exclude-file-regexps
6937 List of regexps which exclude source-files from being historized. Be
6938 aware that each always full filenames (ie. incl. full path) are
6939 matched against these regexps! Therefore be carefore with regexps
6943 @defopt history-item-name
6944 The name to use for items in the history buffer.
6947 @defopt history-menu-sorter
6948 Function which re-sorts the menu-entries of the directories buffer.
6950 If a function then this function is called to sort the menu-entries of
6951 the combined menu-entries of the user-menu-extensions of
6952 @code{ecb-history-menu-user-extension} and the built-in-menu
6953 @code{ecb-history-menu}. If nil then no special sorting will be done
6954 and the user-extensions are placed in front of the built-in-entries.
6956 For the guidelines for such a sorter-function see
6957 @code{ecb-directories-menu-sorter}.
6961 @defopt history-menu-user-extension
6962 Static user extensions for the popup-menu of the history buffer. For
6963 further explanations see @code{ecb-directories-menu-user-extension}.
6965 The node-argument of a menu-function contains as data the filename of
6966 the source for which the popup-menu has been opened.
6968 Per default the static user-extensions are added at the beginning of
6969 the built-in menu-entries of @code{ecb-history-menu} but the whole
6970 menu can be re-arranged with @code{ecb-history-menu-sorter}.
6973 @defopt history-menu-user-extension-function
6974 Dynamic user extensions for the popup-menu of the history buffer. A
6975 function which has to return a list in the same format like the option
6976 @code{ecb-history-menu-user-extension}. This function is called when
6977 the user opens the popup-menu for the history buffer.
6979 Per default the dynamic user-extensions are added in front of the
6980 static extensions of @code{ecb-history-menu-user-extension} but the
6981 whole menu can be re-arranged with @code{ecb-history-menu-sorter}.
6984 @defopt history-sort-ignore-case
6985 Ignore case for sorting the history-entries. See also
6986 @code{ecb-history-sort-method}.
6989 @defopt history-sort-method
6990 Defines how the entries in the history-buffer are sorted.
6993 Sorting by name (default).
6994 @item @code{extension}:
6995 Sorting first by extension and then by name.
6997 No sorting, means the most recently used buffers are on the top of the
6998 history and the seldom used buffers at the bottom.
7001 See also @code{ecb-history-sort-ignore-case}.
7004 @defopt kill-buffer-clears-history
7005 Define if @code{kill-buffer} should also clear the history. There are
7010 Removes automatically the corresponding history-entry after the buffer
7013 Asks, if the history-entry should be removed after the kill.
7015 @code{kill-buffer} does not affect the history (this is the default).
7019 @node ecb-layout, ecb-compilation, ecb-history, Customizable options
7020 @subsection Group ecb-layout
7023 This group contains settings for the screen-layout of the ECB:
7025 @defopt activate-before-new-frame-created-hook
7026 Normal hook run before the new ECB-frame is created if
7027 @code{ecb-new-ecb-frame} is not nil (otherwise this hook is not
7031 @defopt advice-window-functions
7032 Advice functions to be more intelligent if used with ECB. You can
7033 choose the following functions to be adviced by ECB so they behave as
7034 if the edit-window(s) of ECB would be the only windows(s) of the
7038 @item @code{other-window}
7039 For this one see also the option @code{ecb-other-window-behavior}!
7040 @item @code{delete-window}
7041 @item @code{delete-other-windows}
7042 @item @code{delete-windows-on}
7043 @item @code{split-window-horizontally}
7044 @item @code{split-window-vertically}
7045 @item @code{split-window}
7046 If this advice is enabled then @code{split-window-vertically} and
7047 @code{split-window-horizontally} are autom. enabled too!
7048 @item @code{switch-to-buffer}
7049 @item @code{switch-to-buffer-other-window}
7050 @item @code{display-buffer}
7051 Especially if @code{ecb-compile-window-height} is not nil it is
7052 strongly recommended not to disable this advice!
7053 @item @code{other-window-for-scrolling}
7054 If this advice is enabled then the behavior of the following functions
7055 depends on @code{ecb-other-window-behavior}:
7057 @item @code{scroll-other-window}
7058 @item @code{scroll-other-window-down}
7059 @item @code{beginning-of-buffer-other-window}
7060 @item @code{end-of-buffer-other-window}
7062 @item @code{balance-windows}:
7063 Only the edit-windows are balanced
7066 For working most conveniently with ECB it is the best to advice all
7067 these functions, because then all the standard shortcuts of these
7068 functions are also usable with ECB without doing anything else. Also
7069 other packages can interact best with ECB if these functions are all
7070 adviced. If these adviced functions are called in another frame than
7071 the ECB-frame they behave all exactly like the not adviced versions!
7073 But please read also the following:
7075 Normally all packages should work correct with ECB and it´s adviced
7076 functions but if there occur problems with a package cause of some of
7077 these adviced functions ECB offers the following fall-back solution:
7081 Deactivate in @code{ecb-advice-window-functions} all the
7082 adviced-functions which make problems with other packages.
7084 For every of the advice-able functions <adv-func> ECB offers a
7085 interactively function named ``ecb-<adv-func>'' which does exactly the
7086 same as the adviced version of <adv-func>. Use ``ecb-<adv-func>''
7087 instead the original one to get the proper ECB behavior even if the
7088 function is not adviced anymore.
7090 You can bind in @code{ecb-activate-hook} the standard-shortcut of
7091 <adv-func> to ``ecb-<adv-func>'' and rebind it in
7092 @code{ecb-deactivate-hook} to <adv-func>.
7094 Now you have the best of both worlds: The problematic package works
7095 and you have the ECB-behavior of <adv-func> as if it would be adviced.
7098 Here is an example: Suppose you must deactivating the advice for
7099 @code{switch-to-buffer-other-window}. Then you deactivate this
7100 function with this option and you can use
7101 @code{ecb-switch-to-buffer-other-window} instead. Bind the shortcut
7102 you normally use for @code{switch-to-buffer-other-window} to
7103 @code{ecb-switch-to-buffer-other-window} (use @code{ecb-activate-hook}
7104 for this) and rebind it to the original function in the
7105 @code{ecb-deactivate-hook}.
7108 @defopt advice-window-functions-signal-error
7109 Signal an error if an adviced function can not do its job. If not nil
7110 then an error is signaled if one of the adviced functions (see
7111 @code{ecb-advice-window-functions}) can not do its job. So for example
7112 if the user tries to split the compile-window or an ecb-tree-window or
7113 if one tries to switch to another buffer in one of the
7114 ecb-tree-windows. For details see the documentation of each of the
7115 adviced functions to get info when an error is signaled.
7117 If this option is nil then no error is signaled but the called adviced
7118 function does simply nothing.
7120 Default is nil but it can also be useful to signal errors - so you see
7121 when call a function in a situation which is not supported by this
7125 @defopt fix-window-size
7126 Fix size of the ECB-windows/buffers even after frame-resizing. The fix
7127 type (valid values are nil, t, width and height) can either be set on
7128 a layout-basis (means a different value for each layout) or one value
7129 can be set for all layouts.
7131 For a detailed description of the valid values see description of
7132 @code{window-size-fixed} which is newly introduced in GNU Emacs 21 and
7133 is only available there. Therefore this option takes only effect with
7136 Note1: Manually resizing the ECB-windows via @code{enlarge-window},
7137 @code{shrink-window}, @code{mouse-drag-vertical-line} and
7138 @code{mouse-drag-mode-line} is still possible even if the window-sizes
7139 are fixed for frame-resizing!
7141 Note2: The description of @code{window-size-fixed} in the
7142 Elisp-info-manual is more detailed than the description offered by
7145 Note3: With current Emacs 21.2.X there seems to be no distinction
7146 between @code{width}, @code{height} and @code{t}. Therefore this
7147 option takes no effect (means all ecb-windows have always unfixed
7148 sizes) if @code{ecb-compile-window-height} is not @code{nil}.
7150 Per default no window-size fixing has been done.
7153 @defopt hide-ecb-windows-after-hook
7154 Hooks run direct after the ECB windows have been hidden. Hiding was
7155 done either by @code{ecb-toggle-ecb-windows} or
7156 @code{ecb-hide-ecb-windows}.
7158 IMPORTANT: Hiding the ECB-windows is internally done by calling
7159 @code{ecb-redraw-layout} and therefore also the hooks
7160 @code{ecb-redraw-layout-before-hook} and
7161 @code{ecb-redraw-layout-after-hook} are evaluated. The hook-sequence
7162 is analogous to that described in
7163 @code{ecb-show-ecb-windows-after-hook}.
7166 @defopt hide-ecb-windows-before-hook
7167 Hook run direct before the ECB windows will be hidden. Hiding is done
7168 either by @code{ecb-toggle-ecb-windows} or
7169 @code{ecb-hide-ecb-windows}. This means that at runtime of this hook
7170 all the ECB-tree-windows of current layout are visible.
7172 IMPORTANT: Hiding the ECB-windows is internally done by calling
7173 @code{ecb-redraw-layout} and therefore also the hooks
7174 @code{ecb-redraw-layout-before-hook} and
7175 @code{ecb-redraw-layout-after-hook} are evaluated. The hook-sequence
7176 is analogous to that described in
7177 @code{ecb-show-ecb-windows-before-hook}.
7180 @defopt ignore-display-buffer-function
7181 Adviced @code{display-buffer} ignores @code{display-buffer-function}.
7182 This means, that the adviced version of @code{display-buffer} (see
7183 @code{ecb-advice-window-functions}) ignores the value of
7184 @code{display-buffer-function} when called for the @code{ecb-frame}.
7185 If this variable should not be ignored then the function of
7186 @code{display-buffer-function} is completely responsible which window
7187 is used for the buffer to display - no smart ECB-logic will help to
7188 deal best with the ECB-window-layout! You can define if and when
7189 @code{display-buffer-function} should be ignored:
7193 only when durable compile window is used - i.e. if
7194 @code{ecb-compile-window-height} is not nil
7197 always when ECB is active - that means ignore when ECB is active
7198 otherwise not - this is the default value
7201 never, the adviced version of @code{display-buffer} always uses the
7202 value of @code{display-buffer-function} if the value is a function.
7208 @defopt ignore-special-display
7209 Ignore special-display-handling. This means, that all values of
7210 @code{special-display-function}, @code{special-display-buffer-names}
7211 and @code{special-display-regexps} are ignored
7215 only when durable compile window is used - i.e. if
7216 @code{ecb-compile-window-height} is not nil - this is the default
7220 always when ECB is active - that means no special-display-handling of
7221 buffers when ECB is active
7224 never, i.e. special-dislay-handling depends on the values of the
7225 options @code{special-display-function},
7226 @code{special-display-buffer-names} and
7227 @code{special-display-regexps}.
7232 @defopt layout-always-operate-in-edit-window
7233 Adviced window functions work always in the edit-window. If we are in
7234 an ECB special buffer (methods, directories, etc), and any of the
7235 adviced windowing functions is called interactively (see
7236 @code{ecb-advice-window-functions}), we will select first an
7237 edit-window according to the value of
7238 @code{ecb-mouse-click-destination}. This is useful if you have any
7239 functions that use such functions and you don't want them to fail with
7240 an error complaining that the current buffer can not be split, or
7243 Because this may not be desirable in all situations and for all
7244 adviced functions this can be enabled separately for every advicable
7245 function (see also @code{ecb-advice-window-functions}). If the symbol
7246 of an adviced function is contained in the value of this option, then
7247 a edit-window is first selected otherwise either an error is
7248 reported or some other special reaction (depends on
7249 @code{ecb-advice-window-functions-signal-error}); see the
7250 documentation of the adviced functions for this.
7252 For @code{other-window}, @code{other-window-for-scrolling} and
7253 @code{switch-to-buffer-other-window} this makes no sense, therefore
7254 you can not enable this for them.
7256 Per default this is enabled for @code{switch-to-buffer} and
7257 @code{display-buffer}.
7261 @defopt layout-debug-mode
7262 Write debug-information about layout-operations in the
7263 Messages-buffer. Normally there should be no need to set this option
7264 to true but if there are problems to display buffers in the
7265 compile-window of ECB (e.g. buffers which should be displayed there
7266 aren't or the temporally enlarging-mechanism does not do what you
7267 think it should do etc...) then please do the following steps:
7271 Set @code{ecb-layout-debug-mode} to not nil
7274 Reproduce the wrong behavior exactly by repeating all the operations
7275 which lead to the problem.
7278 Now send immediately a bug report with
7279 @code{ecb-submit-problem-report}.
7282 Set @code{ecb-layout-debug-mode} back to nil if you do not want
7283 further debugging output in the *Messages* buffer
7290 Select a window layout of ECB. Value is any arbitrary string. There are
7291 four different types of layouts: left, right, top and left-right,
7292 which means the location of the ECB-tree-windows in the ECB-frame.
7293 Currently there are 20 predefined layouts; names see below. You can
7294 savely try out any of them by changing this value and saving it only
7295 for the current session. If you are sure which layout you want you can
7296 save it for future sessions. To get a picture of the layout for name
7297 <name> call `ecb-show-layout-help'. @code{ecb-layout-function-9}.
7299 Currently available layouts:
7303 left1 left2 left3 left4 left5 left6 left7 left8 left9 left10 left11
7304 left12 left13 left14 left15
7306 @item Right layouts:
7312 @item Left-right layouts:
7313 leftright1 leftright2
7316 Regardless of the settings you define here: If you have destroyed or
7317 changed the ECB-screen-layout by any action you can always go back to
7318 this layout with @code{ecb-redraw-layout}
7322 @defopt layout-window-sizes
7323 Specifies the sizes of the ECB windows for each layout. The easiest
7324 way (and also the strongly recommended way) to change this variable is
7325 to change the window sizes by dragging the window borders using the
7326 mouse and then store the window sizes by calling the command
7327 @code{ecb-store-window-sizes}. Next time the layout is redrawn the
7328 values stored in this option will be used.
7330 If @code{ecb-store-window-sizes} is used then the windows sizes are
7331 stored per default as fractions of current frame-width and -height of
7332 the ecb-frame, so the stored values will ``work'' for other frame
7333 sizes too. But if you call @code{ecb-store-window-sizes} with a
7334 prefix-argument then the fixed values of current width and height are
7337 If this option is set ``by hand'' (i.e. not by
7338 @code{ecb-store-window-sizes}) then the following is important:
7341 It is recommended to use fractions of frame-width and -height!.
7343 The order of the sequence of the inserted window sizes must be the same as
7344 @code{other-window} (the not-adviced version!) would walk!
7348 @defopt maximize-ecb-window-after-selection
7349 If not nil maximize current tree-window after selection. When
7350 selecting another not-tree-window after such an automatic maximizing
7351 all tree-windows of current layout are displayed again. But a
7352 tree-window is not maximized if either a node has been selected via
7353 primary- oder secondarc mouse-button or the popup-menu of that
7354 tree-buffer has been opened.
7357 @defopt new-ecb-frame
7358 Create a new frame at activation time of ECB.
7361 @defopt other-window-behavior
7362 The behavior of ECB concerning getting an ``other window''. This has
7363 an effect if either @code{other-window} or
7364 @code{other-window-for-scrolling} is adviced by ECB, see
7365 @code{ecb-advice-window-functions}. The following settings are
7370 ECB will cycle through all windows of the ECB-frame or scroll simply
7371 the next window in the ECB-frame, means it behaves like the original
7372 @code{other-window} rsp. the original
7373 @code{other-window-for-scrolling}.
7377 ECB will only cycle through the edit-windows of ECB or only scroll
7378 another edit-window. If the selected window is not an edit-window then
7379 it behaves like with value @code{all}.
7381 @code{edit-and-compile}:
7383 Like @code{only-edit} plus the compile window if any. If the selected
7384 window is neither an edit-window nor the compile-window then it
7385 behaves like with value @code{all}.
7389 With this setting ECB tries to choose the
7390 @code{other-window}-destination or the ``other window'' to scroll in a
7391 smart and intuitive way: If point is in one of the edit-windows and if
7392 the edit-area is splitted then always the ``next'' edit-window is
7393 choosen (whereas the next edit-window of the last edit-window is the
7394 first edit-window)- if the edit-area is unsplitted then the
7395 compile-window is used if there is one. In the context of an
7396 @code{other-window}-call the @var{ARG} of @code{other-window} will be
7399 If one of the special ecb-windows is selected then always the ``next''
7400 ecb-window is choosen (whereas the next ecb-window of the last
7401 ecb-window is the first ecb-window). In the context of an
7402 @code{other-window}-call the @var{ARG} of @code{other-window} will be
7403 taken into account. If there is only one ecb-window then ECB considers
7404 also the edit-windows
7406 If the compile-window is selected then always the last edit-window
7407 which had the point will be used unless @code{other-window} has been
7408 called with a prefix-argument unequal 1.
7410 If there is an active minibuffer:
7412 Regardless of the allowed values above ECB handles the situation of an
7413 active minibuffer during a call to @code{other-window} or
7414 @code{scroll-other-window} like follows:
7416 If the minibuffer-window is selected then ECB always chooses the
7417 window @code{minibuffer-scroll-window} points to (when this variable
7418 is set, otherwise the compile-window or the last selected edit-window
7419 is choosen) when the called command is called to choose the 1. next
7420 window (always true for scrolling another window or true when
7421 @code{other-window} called without prefix-arg or with prefix-arg equal
7422 1). Otherwise the window ARG steps away is choosen (in case of
7423 @code{other-window}).
7425 If there is an active minibuffer but the minibuffer-window is not
7426 selected then @code{other-window} and @code{scroll-other-window}
7427 behave like the original version.
7429 In addition to the allowed values above the value of this option can
7434 This function gets seven arguments:
7437 A canonical list of all currently visible windows of the
7440 A canonical list of all currently visible edit-windows
7442 A canonical list of all currently visible ecb-windows
7444 The window-object of the compile-window if there is any.
7446 The minibuffer-window of the ECB-frame if there is an active
7449 The result of the function @code{ecb-where-is-point} - see the
7450 documentation of this function for details.
7452 An integer which indicates how many steps away from the current
7453 selected window the ``other-window'' is. Is nil when this function is
7454 called in another context then for @code{other-window}.
7457 The function has to return a window-object which is then used as
7458 ``other window'' for the command @code{other-window} or for scrolling
7459 another window (e.g. with @code{scroll-other-window}). Such a function
7460 has to handle properly all situation for itself.
7461 @code{ecb-get-other-window-smart} is an example for such a function.
7464 @defopt redraw-layout-after-hook
7465 Hooks run direct before the ECB windows will be shown either by
7466 @code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
7467 means that at runtime of this hook the ECB-windows are already
7471 @defopt redraw-layout-before-hook
7472 Hooks run direct before the ECB-layout will be redrawn by either
7473 @code{ecb-redraw-layout}.
7476 @defopt redraw-layout-quickly
7477 If non-nil, we will attempt to redraw the layout quickly. Please read
7478 also carefully the documentation of @code{ecb-redraw-layout}.
7481 @defopt select-edit-window-on-redraw
7482 Select the first edit window on @code{ecb-redraw-layout}.
7485 @defopt show-ecb-windows-after-hook
7486 Hooks run direct before the ECB windows will be shown either by
7487 @code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
7488 means that at runtime of this hook the ECB-windows are already
7491 IMPORTANT: Showing the hidden ECB-windows is internally done by
7492 calling @code{ecb-redraw-layout} and therefore also the hooks
7493 @code{ecb-redraw-layout-before-hook} and
7494 @code{ecb-redraw-layout-after-hook} are evaluated. So there is the
7495 following sequence of hooks during the process of showing the hidden
7498 @item @code{ecb-show-ecb-windows-before-hook}
7499 @item @code{ecb-redraw-layout-before-hook}
7500 @item <redrawing the layout to show the hidden ECB-windows>
7501 @item @code{ecb-redraw-layout-after-hook}
7502 @item @code{ecb-show-ecb-windows-after-hook}
7504 So be aware which code you add to which hook!
7507 @defopt show-ecb-windows-before-hook
7508 Hooks run direct before the ECB windows will be shown either by
7509 @code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows}. This
7510 means that at runtime of this hook the ECB-windows are still hidden.
7512 IMPORTANT: Showing the hidden ECB-windows is internally done by
7513 calling @code{ecb-redraw-layout} and therefore also the hooks
7514 @code{ecb-redraw-layout-before-hook} and
7515 @code{ecb-redraw-layout-after-hook} are evaluated. So there is the
7516 following sequence of hooks during the process of showing the hidden
7519 @item @code{ecb-show-ecb-windows-before-hook}
7520 @item @code{ecb-redraw-layout-before-hook}
7521 @item <redrawing the layout to show the hidden ECB-windows>
7522 @item @code{ecb-redraw-layout-after-hook}
7523 @item @code{ecb-show-ecb-windows-after-hook}
7525 So be aware which code you add to which hook!
7529 @defopt split-edit-window-after-start
7530 Sets if and how the edit window should be splitted after ECB-start.
7531 But be aware: This option determines only if and how the edit-window
7532 should be splitted at start-time of ECB. There are five different
7533 values allowed for this option:
7537 Do not split the edit-area of ECB after activation, i.e. there will be
7538 only one edit-window after starting ECB.
7540 @item @code{horizontal}:
7541 Split the edit-area in 2 edit-windows side by side.
7543 @item @code{vertical}:
7544 Split the edit-area in 2 edit-windows, one above the other.
7546 @item @code{before-activation}:
7547 Split the edit-area as before the ECB-start, i.e. the edit-area will
7548 have after start a window-layout as the whole frame had before the
7551 @item @code{before-deactivation}:
7552 Split the edit-area into a window-layout ECB had in its edit-area
7553 direct before the ECB-deactivation. This value preserves the full
7554 state between activations of ECB, i.e. the visibility of the
7555 ECB-windows, the visibility of a compile-window and also the full
7556 split-state of the edit-area. But this can only be done if important
7557 layout-options have not been changed in the meanwhile. These are the
7558 options @code{ecb-layout-name}, @code{ecb-compile-window-height},
7559 @code{ecb-compile-window-width}, @code{ecb-windows-width} and
7560 @code{ecb-windows-height}.
7563 Default value is @code{before-deactivation}.
7565 Some remarks to the value @code{before-activation}: If this value has
7566 been set then ECB needs three permanent adivces even when ECB is
7567 deactivated: @code{split-window}, @code{delete-window} and
7568 @code{delete-other-windows}. But these advices do not change any
7569 behavior of these functions but only storing in an internal
7570 ECB-variable the facts that a window has been splitted or deleted. In
7571 addition to this these advices are 100% error-save, means the
7572 functionality of the original functions will be performed in every(!)
7573 case even if within the advice an error occurs (but normally there can
7574 no errors occur in these advices because they are very simple).
7575 Conclusion: If you want really all ECB-advices being disabled after
7576 deactivating ECB then you have to set this option to other values then
7577 @code{before-activation}. But setting this variable to this value is
7578 really completely save.
7581 @defopt toggle-layout-sequence
7582 Toggle sequence for layout toggling with @code{ecb-toggle-layout}.
7583 Every element of this list has to be a valid layout-name i.e. either
7584 one of the predefined layouts or one of the user-defined layouts.
7586 You can add here as many layouts as you want but to use this option
7587 most effective you should not add more than 2 or 3 layouts so every
7588 layout can be accessed very fast by toggling with
7589 @code{ecb-toggle-layout}. It is also senseful to add layouts which
7590 have the same principal outline, i.e. all their tree-buffers are on
7591 the same side of the frame and the tree-buffer-''column'' (or
7592 -''row'') has identical size for the layouts.
7594 Recommended values are for example:
7597 @item (``left10'' ``left15''), toggles between methods and directories/history
7598 @item (``left10'' ``left13''), toggles between methods and directories
7599 @item (``left10'' ``left14''), toggles between methods and history
7600 @item (``left10'' ``left13'' ``left14''), toggles between methods, history and directories
7603 See also option @code{ecb-show-sources-in-directories-buffer}.
7605 This option makes only sense if the value is a list with more than 1
7609 @defopt windows-height
7610 The height of the ECB windows in lines for top-layouts. If the number
7611 is less than 1.0 the width is a fraction of the frame height.
7614 @defopt windows-width
7615 The width of the ECB windows in columns for left- and right layouts.
7616 If the number is less than 1.0 the width is a fraction of the frame
7620 @node ecb-compilation, ecb-create-layout, ecb-layout, Customizable options
7621 @subsection Group ecb-compilation
7624 This group contains settings for the compile window of ECB:
7626 @defopt compilation-buffer-names
7627 Additional buffer names that should be displayed in the
7628 compile-window. Buffer names can either be defined as strings or as
7629 regexps. If the buffer-name of a buffer matches one of the defined
7630 string or regexp then it will be displayed in the compile-window of
7631 ECB even if @code{compilation-buffer-p} says nil for this buffer.
7633 It is not recommended to add the eshell-buffer-names to this list
7634 because ECB already handles the eshell-integration as best as
7635 possible (@pxref{Using eshell}).
7637 See also the options @code{ecb-compilation-major-modes} and
7638 @code{ecb-compilation-predicates}.
7641 @defopt compilation-major-modes
7642 Additional major-mode that should be displayed in the compile-window.
7643 All buffers of a major-mode contained in this list are displayed in
7644 the compile-window even if @code{compilation-buffer-p} says nil for
7647 It is not recommended to add @code{eshell-mode} to this list because
7648 ECB already handles the eshell-integration as best as possible
7649 (@pxref{Using eshell}).
7652 @defopt compilation-predicates
7653 Predicates when a buffer should be treated as compilation-buffer.
7654 Every element of this list has to be a function or lambda-expression
7655 which gets as argument a buffer-object and which has to return not nil
7656 when this buffer should be treated as compilation-buffer (even if
7657 @code{compilation-buffer-p} says nil) and therefore be displayed in
7658 the compile-window of ECB (if there is any).
7660 In combination with the values of @code{ecb-compilation-buffer-names}
7661 and @code{ecb-compilation-major-modes} ECB decides when a buffer is
7662 displayed in the compile-window.
7664 Default value is the function @code{comint-check-proc} which returns
7665 not nil when the buffer is related to a living process.
7668 @defopt compile-window-height
7669 Height of the durable compilation-window of ECB. If you want a
7670 compilation window shown at the bottom of the ECB-layout then set here
7671 the height of it (Default is a height of 5). If you redraw the current
7672 layout with @code{ecb-redraw-layout} then the compilation window (if
7673 any) has the height you set here. If the number is less than 1.0 the
7674 height is a fraction of the frame height.
7676 If you do not set a durable compilation window then doing a
7677 compilation or displaying temp-buffers (e.g. *Help*-buffers) splits
7678 temporally the edit window vertically if the edit window is not
7679 splitted already or uses another edit window temporally for
7680 compilation output if the edit window is already splitted. This is the
7681 recommended value for this option because this is the
7682 standard-behavior of Emacs.
7684 Beware: If you set a durable compilation window then ECB displays all
7685 buffers for which @code{ecb-compilation-buffer-p} returns not nil in
7686 that durable compilation window. If a buffer which should being
7687 displayed there is not displayed there then try to modify the options
7688 @code{ecb-compilation-buffer-names},
7689 @code{ecb-compilation-major-modes} or
7690 @code{ecb-compilation-predicates} (in this sequence).
7692 See also the options @code{ecb-compile-window-temporally-enlarge} and
7693 @code{ecb-enlarged-compilation-window-max-height} and also the command
7694 @code{ecb-toggle-compile-window-height}!
7696 ECB offers the functionality of such a durable compile-window
7697 regardless if the special ECB-windows are visible or not (see the
7698 command @code{ecb-toggle-ecb-windows}).
7700 Regardless of the settings you define here: If you have destroyed or
7701 changed the ECB-screen-layout by any action you can always go back to
7702 this layout with @code{ecb-redraw-layout}
7705 @defopt compile-window-prevent-shrink-below-height
7706 Allow the compile-window to be shrunken below its height. A non nil
7707 value means ECB prevents the compile-window from being shrunken below
7708 the threshold of @code{ecb-compile-window-height} by displaying
7709 temp-buffers (e.g. *Help* etc.) or after running compilations or
7710 greps. But interactively it is always allowed to shrink it to every
7713 If nil then ECB does nothing to prevent being shrunken below the value
7714 of @code{ecb-compile-window-height}.
7721 @defopt compile-window-temporally-enlarge
7722 Let Emacs temporally enlarge the compile-window of the ECB-layout.
7723 This option has only an effect if @code{ecb-compile-window-height} is
7726 The following values are possible:
7728 @item @code{after-display}:
7729 After displaying a ``compilation-buffer'' (in the sense of
7730 @code{ecb-compilation-buffer-p}!) in the compile-window of ECB. For
7731 the max. height of the enlarged compile-window see the option
7732 @code{ecb-enlarged-compilation-window-max-height}.
7734 @item @code{after-selection}:
7735 Selecting the @code{ecb-compile-window} auto. enlarges it and
7736 de-selecting (means leaving @code{ecb-compile-window}) auto. shrinks
7737 it. Enlarging and shrinking the @code{ecb-compile-window} is done with
7738 @code{ecb-toggle-compile-window-height}. See also the
7739 documentation of this function!
7742 The combination of 'after-display and 'after-selection.
7745 ECB fixes always the height of the @code{ecb-compile-window} at the
7746 value of @code{ecb-compile-window-height}.
7749 To restore the ECB-layout after such a buffer-enlarge just call
7750 @code{ecb-toggle-compile-window-height} or
7751 @code{ecb-redraw-layout}.
7754 @defopt compile-window-width
7755 Width of the compile-window.
7757 Possible values are @code{frame} and @code{edit-window}.
7758 With @code{frame} the compile-window looks like:
7763 -------------------------------------------------------
7767 |--------------| edit-window(s) |
7771 -------------------------------------------------------
7775 -------------------------------------------------------
7779 With @code{edit-window} the compile-window looks like:
7783 -------------------------------------------------------
7787 |--------------| edit-window(s) |
7791 | |---------------------------------------
7795 -------------------------------------------------------
7799 This option takes only effect if @code{ecb-compile-window-height} is
7803 @defopt change-layout-preserves-compwin-state
7804 Changing the layout preserves the state of the compile-window. This is
7805 for example useful if the user toggles between several layouts (see
7806 @code{ecb-toggle-layout}) and wants to preserve the hidden-state of
7811 @defopt enlarged-compilation-window-max-height
7812 The max height of the compile-window after enlarging it. The max
7813 height of the compilation window after enlarged by
7814 @code{ecb-toggle-compile-window-height}. The following values are
7819 ECB fits the height of the compile-window exactly to the size of its
7820 current contents but never shrinks below the value of
7821 @code{ecb-compile-window-height} or enlarges over the half of the
7822 frame-height of the ECB-frame. The values of the options
7823 @code{compilation-window-height} and @code{temp-buffer-max-height} are
7824 taken into account dependent of the current @code{major-mode} of the
7825 buffer in the compile-window: If @code{compilation-mode} then
7826 @code{compilation-window-height} is used otherwise
7827 @code{temp-buffer-max-height}.
7831 1/2 the frame-height of the ECB-frame
7835 Max height in lines. If the number is less than 1.0 the height is a
7836 fraction of the frame height (e.g. 0.33 results in a max-height of 1/3
7840 @defopt scroll-other-window-scrolls-compile-window
7841 @code{scroll-other-window} scrolls always the compile-window. For all
7842 details about the scroll-behavior of @code{scroll-other-window} see
7843 the advice documentation of @code{other-window-for-scrolling}.
7847 @node ecb-create-layout, ecb-face-options, ecb-compilation, Customizable options
7848 @subsection Group ecb-create-layout
7851 This group contains settings for creating new ECB-layouts:
7853 @defopt create-layout-file
7854 File where all layouts created by @code{ecb-create-new-layout} are
7858 @defopt ecb-create-layout-frame-height
7859 Frame height of the layout creation frame.
7862 @defopt ecb-create-layout-frame-width
7863 Frame width of the layout creation frame.
7866 @node ecb-face-options, ecb-faces, ecb-create-layout, Customizable options
7867 @subsection Group ecb-face-options
7870 This group contains settings for all faces used in ECB:
7872 @defopt directories-general-face
7873 Basic face for the ECB directories buffer. This defines the basic face
7874 the whole directory buffer should displayed with. If the face
7875 @code{ecb-default-general-face} is used then the display of all
7876 ECB-tree-buffers can be changed by modifying only the face
7877 @code{ecb-default-general-face}.
7879 Changes take first effect after finishing and reactivating ECB!
7882 @defopt directory-face
7883 Face used for highlighting current directory in the directories
7884 buffer. If the face @code{ecb-default-highlight-face} is used then the
7885 display of all ECB-tree-buffers can be changed by modifying only the
7886 face @code{ecb-default-highlight-face}.
7888 Changes take first effect after finishing and reactivating ECB!
7891 @defopt directory-not-accessible-face
7892 Face for not accessible dirs in the directories buffer.
7895 @defopt history-face
7896 Face used for highlighting current history-entry in the history
7897 buffer. If the face @code{ecb-default-highlight-face} is used then the
7898 display of all ECB-tree-buffers can be changed by modifying only the
7899 face @code{ecb-default-highlight-face}.
7901 Changes take first effect after finishing and reactivating ECB!
7904 @defopt history-general-face
7905 Basic face for the ECB directory buffer. This defines the basic face
7906 the whole history buffer should displayed with. If the face
7907 @code{ecb-default-general-face} is used then the display of all
7908 ECB-tree-buffers can be changed by modifying only the face
7909 @code{ecb-default-general-face}.
7911 Changes take first effect after finishing and reactivating ECB!
7915 Face used for highlighting current method, class or variable in the
7916 methods buffer. If the face @code{ecb-default-highlight-face} is used
7917 then the display of all ECB-tree-buffers can be changed by modifying
7918 only the face @code{ecb-default-highlight-face}.
7920 Changes take first effect after finishing and reactivating ECB!
7923 @defopt method-non-semantic-face
7924 Face used for for displaying tags of sources not supported by
7927 Changes take first effect after finishing and reactivating ECB!
7931 @defopt methods-general-face
7932 Basic face for the ECB methods buffer. This defines the basic face the
7933 whole methods buffer should displayed with. If the face
7934 @code{ecb-default-general-face} is used then the display of all
7935 ECB-tree-buffers can be changed by modifying only the face
7936 @code{ecb-default-general-face}.
7938 Changes take first effect after finishing and reactivating ECB!
7942 Face used for highlighting current source in the sources buffer. If
7943 the face @code{ecb-default-highlight-face} is used then the display of
7944 all ECB-tree-buffers can be changed by modifying only the face
7945 @code{ecb-default-highlight-face}.
7947 Changes take first effect after finishing and reactivating ECB!
7950 @defopt source-in-directories-buffer-face
7951 Face for source files in the directories buffer.
7954 @defopt sources-general-face
7955 Basic face for the ECB sources buffer. This defines the basic face the
7956 whole sources buffer should displayed with. If the face
7957 @code{ecb-default-general-face} is used then the display of all
7958 ECB-tree-buffers can be changed by modifying only the face
7959 @code{ecb-default-general-face}.
7961 Changes take first effect after finishing and reactivating ECB!
7964 @defopt source-read-only-face
7965 Face for read-only sources.
7968 @defopt tag-header-face
7969 Face used for highlighting the tag header after jumping to it by
7970 clicking onto a node in the methods buffer.
7975 @node ecb-faces, ecb-download, ecb-face-options, Customizable options
7976 @subsection Group ecb-faces
7979 This group contains all faces used in ECB:
7982 @item ecb-bucket-node-face:
7983 Face which can be used for displaying bucket tags in the methods
7984 buffer. See also @code{ecb-bucket-node-display}.
7986 @item ecb-default-general-face:
7987 Basic face for all ECB tree-buffers.
7988 It's recommended to define here the font-family, the font-size, the basic
7991 In GNU Emacs 21.X all faces (even the face
7992 @code{ecb-default-highlight-face}) used in the ECB tree-buffers inherit
7993 from this face. Therefore the default attributes like font etc. of a
7994 face used in a tree-buffer can be very easily changed with face
7995 @code{ecb-default-general-face}.
7997 With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the
7998 options @code{ecb-directories-general-face},
7999 @code{ecb-sources-general-face}, @code{ecb-methods-general-face} and
8000 @code{ecb-history-general-face} offer the choice to use the face
8001 @code{ecb-default-general-face} so also with XEmacs and GNU Emacs 20.X
8002 the basic face-settings can be easily changed just by customizing the
8003 face @code{ecb-default-general-face}!
8005 @item ecb-default-highlight-face:
8006 Define basic face for highlighting the selected node in an ECB
8009 In GNU Emacs 21.X all highlighting faces in the ECB tree-buffers
8010 inherit from this face. Therefore the default attributes like font
8011 etc. of a face used in a tree-buffer for highlighting the current
8012 tag can be very easily changed with face
8013 @code{ecb-default-highlight-face}.
8015 With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the
8016 options @code{ecb-directory-face}, @code{ecb-source-face},
8017 @code{ecb-method-face} and @code{ecb-history-face} offer the choice to
8018 use the face @code{ecb-default-highlight-face} so also with XEmacs and
8019 GNU Emacs 20.X the basic face-settings can be easily changed just by
8020 customizing the face @code{ecb-default-highlight-face}!
8022 @item ecb-directories-general-face:
8023 Basic face for the ECB directories buffer. It´s recommended to define
8024 here the font-family, the font-size, the basic color etc.
8026 @item ecb-directory-face:
8027 Define face used for highlighting current directory in the directories
8030 @item ecb-directory-not-accessible-face
8031 Define a face for not accessible dirs in the directories buffer.
8033 @item ecb-history-face:
8034 Define face used for highlighting current history-entry in the history
8037 @item ecb-history-general-face:
8038 Basic face for the ECB history buffer. It´s recommended to define here
8039 the font-family, the font-size, the basic color etc.
8041 @item ecb-method-face:
8042 Define face used for highlighting current method, class or variable in
8045 @item ecb-methods-general-face:
8046 Basic face for the ECB methods buffer. It´s recommended to define here
8047 the font-family, the font-size, the basic color etc.
8049 @item ecb-method-non-semantic-face:
8050 Define face used for displaying tags of sources not supported by semantic.
8052 @item ecb-mode-line-data-face
8053 Define face for the data in the mode-line. See
8054 @code{ecb-mode-line-data}.
8056 @item ecb-mode-line-prefix-face
8057 Define face for the prefix in the mode-line. See
8058 @code{ecb-mode-line-prefixes}.
8060 @item ecb-source-face:
8061 Define face used for highlighting current source in the sources
8064 @item ecb-source-in-directories-buffer-face:
8065 Define a face for displaying sources in the directories buffer.
8067 @item ecb-sources-general-face:
8068 Basic face for the ECB sources buffer. It´s recommended to define here
8069 the font-family, the font-size, the basic color etc.
8071 @item ecb-source-read-only-face
8072 Define a face for read-only sources
8074 @item ecb-tag-header-face:
8075 Define face used for highlighting the tag header after jumping to it
8076 by clicking onto a node in the methods buffer.
8078 @item ecb-tree-guide-line-face:
8079 Define face for the guide-lines in the tree-buffers. See the option
8080 @code{ecb-tree-buffer-style} for a explanation of guide-lines.
8082 @item ecb-type-tag-class-face:
8083 Define face used with option @code{ecb-type-tag-display}.
8085 @item ecb-type-tag-enum-face:
8086 Define face used with option @code{ecb-type-tag-display}.
8088 @item ecb-type-tag-group-face:
8089 Define face used with option @code{ecb-type-tag-display}.
8091 @item ecb-type-tag-interface-face:
8092 Define face used with option @code{ecb-type-tag-display}.
8094 @item ecb-type-tag-struct-face:
8095 Define face used with option @code{ecb-type-tag-display}.
8097 @item ecb-type-tag-typedef-face:
8098 Define face used with option @code{ecb-type-tag-display}.
8100 @item ecb-type-tag-union-face:
8101 Define face used with option @code{ecb-type-tag-display}.
8103 @item ecb-mode-line-win-nr-face
8104 Define face for the window-number in the mode-line. See
8105 @code{ecb-mode-line-display-window-number}.
8109 Just call @code{customize-face <face-name>} to customize these faces
8110 for your personal taste. Or customize the related option in the group
8111 @ref{ecb-face-options}.
8113 @node ecb-download, ecb-help, ecb-faces, Customizable options
8114 @subsection Group ecb-download
8117 This group contains settings for downloading and installing a new ECB
8120 @defopt download-delete-archive
8121 Should the downloaded archive be deleted after successful
8122 installation or after failure during the installation-process.
8123 Possible values are:
8126 @item @code{only-after-success}:
8127 Archive is only deleted after successful installation
8128 but not if a failure occurs during the installation process.
8129 @item @code{always}:
8130 Archive is also deleted if an error occurs.
8132 Archive will never be deleted.
8136 @defopt download-install-parent-dir
8137 Parent directory where downloaded packages are installed.
8139 ECB installs a downloaded package in this directory, i.e. the downloaded
8140 archive X.tar.gz will be extracted in this directory so afterwards this
8141 directory contains a new subdirectory X which contains the downloaded package.
8143 This directory must be write-able!
8146 @defopt download-package-version-type
8147 Version type ECB is allowed to download for upgrading.
8149 If you want to upgrade to a newer ECB-version via
8150 @code{ecb-download-ecb} or if you must upgrade to newer semantic-
8151 eieio- and/or speedbar-versions (because ECB requires these newer
8152 versions) then this option specifies which version-types are allowed.
8153 ECB checks on the download-sites of ECB/semantic/eieio/speedbar which
8154 versions are currently available and then downloads always the latest
8155 version matching the specified type:
8158 @item 2: Get the newest version of all stable versions available.
8159 @item 1: Get the newest version of all stable and beta versions available.
8160 @item 0: Get the newest version of all stable, beta and alpha versions
8162 @item -1: Ask before downloading in the minibuffer for a version
8163 (TAB-completion of all available versions is possible).
8166 So, 2 means stable, 1 means stable and betas, 0 means stable, betas and alphas
8167 and -1 means ask the user for a version.
8169 Per default stable and beta-versions are allowed (value 1).
8171 But all versions must match the restrictions of the specified min- and
8172 max-versions of the required packages. For this see the file README!
8175 @defopt download-url
8176 URL where download-able ECB-versions are located. The ECB-archive-file
8177 (e.g. ecb-1.70.tar.gz) will be appended to this URL and
8178 @code{ecb-download-ecb} will try to download this archive.
8180 Note: Normally this URL should never change but who knows...
8184 @node ecb-help, ecb-eshell, ecb-download, Customizable options
8185 @subsection Group ecb-help
8188 This group contains settings for the ECB online help:
8191 @defopt help-html-path
8192 Path where the ECB online help in HTML format resides. This must be
8193 the location of the @file{ecb.html} which comes with the ECB
8194 distribution. If is installed by unpacking the archive available on
8195 the ECB website then this is the subdir @code{ecb-help-html-subdir} of
8196 the installation directory of ECB. If it is installed as
8197 XEmacs-package (e.g. via the package manager of XEmacs) then this is
8198 probably either the directory ``../../html/'' or
8199 ``../../etc/ecb/html/'' (both relative to the Elisp directory of ECB).
8201 The path can either be an absolute path or a path relative to the directory
8202 where the Elisp files of ECB are.
8204 Normally there should be no need to change this option!
8208 @defopt help-info-path
8209 Path where the ECB online help in info format resides. This must be
8210 the location of the @file{ecb.info} which comes with the ECB
8211 distribution. If is installed by unpacking the archive available on
8212 the ECB website then this is the subdir @code{ecb-help-info-subdir} of
8213 the installation directory of ECB. If it is installed as
8214 XEmacs-package (e.g. via the package manager of XEmacs) then this is
8215 probably the directory ``../../info/'' (relative to the Elisp directory
8218 The path can either be an absolute path or a path relative to the directory
8219 where the Elisp files of ECB are.
8221 Normally there should be no need to change this option!
8225 @defopt show-help-format
8226 The format @code{ecb-show-help} shows its online help. Allowed values
8227 are 'info (for the Info format) and 'html (for HTML format). If the
8228 value is 'html then @code{browse-url-browser-function} says which
8231 Note: If you got ECB as a standard XEmacs-package maybe the
8232 HTML-online-documentation is not included.
8235 @node ecb-eshell, ecb-speedbar, ecb-help, Customizable options
8236 @subsection Group ecb-eshell
8239 This group contains settings for eshell integration within the ECB:
8241 @defopt eshell-auto-activate
8242 Startup the eshell and display it in the compile-window. If current
8243 layout does not display a compile-window (see
8244 @code{ecb-compile-window-height}) then nothing is done.
8247 @defopt eshell-enlarge-when-eshell
8248 Enlarge the compile-window if it is selected by @code{eshell}. This
8249 takes only effect if the command @code{eshell} is called!
8252 @defopt eshell-fit-window-to-command-output
8253 Fit the compile-window after an eshell-command to the output. This is
8254 done by the function @code{ecb-eshell-fit-window-to-output} which is
8255 added to @code{eshell-post-command-hook} ie. which is running autom.
8256 after each eshell-command.
8259 @defopt eshell-synchronize
8260 Synchronize eshell with the default-directory of current
8261 source-buffer. The synchronization is done by
8262 @code{ecb-eshell-current-buffer-sync} which can be called
8263 interactively but normally it is called autom. by the
8264 @code{ecb-current-buffer-sync-hook}.
8267 @node ecb-speedbar, ecb-non-semantic, ecb-eshell, Customizable options
8268 @subsection Group ecb-speedbar
8272 @node ecb-non-semantic, ecb-winman, ecb-speedbar, Customizable options
8273 @subsection Group ecb-non-semantic
8276 This group contains settings for parsing and displaying non-semantic files:
8278 @defopt auto-save-before-etags-methods-rebuild
8279 Automatic saving of current buffer before rebuilding its methods.
8281 This option is only relevant for sources which are supported and
8282 parsed by etags (see @code{ecb-process-non-semantic-files}). Because
8283 etags is an external tool a source-buffer can only be reparsed if the
8284 buffer is saved to disk. So the command
8285 @code{ecb-rebuild-methods-buffer} checks for sources which are not
8286 supported by semantic or imenu if either this option is t or if the
8287 major-mode of the source-buffer is contained in this list: In both
8288 cases ECB saves the current source-buffer before it re-runs etags for
8289 reparsing the source. If nil or if the major-mode is not contained
8290 then no automatic saving will be done!
8292 For all source supported by semantic or by imenu this option takes no
8296 @defopt non-semantic-exclude-modes
8297 Exclude modes from parsing with imenu or etags. Per default, ECB tries
8298 to parse all file-types not supported by semantic with imenu or etags
8299 or some other method (for details see the option
8300 @code{ecb-non-semantic-parsing-function}). If a file-type can not be
8301 parsed by semantic, imenu or etags than this simply results in an
8302 empty method-buffer for this file. But nevertheless you will get a
8303 message ``Sorry, no support for a file of that extension'' which comes
8304 from the speedbar-library and can not switched off. Therefore if a
8305 @code{major-mode} is known as not parse-able by semantic, imenu or etags
8306 it can be added to this option and then it will be excluded from being
8310 @defopt non-semantic-methods-initial-expand
8311 Initially expand all tags for not by semantic supported sources.
8312 This option can be customized on a major-mode basis, i.e. if a
8313 @code{major-mode} is contained in this option then all tags for this
8314 modes will be initially expanded - otherwise not.
8317 @defopt non-semantic-parsing-function
8318 Define mode-dependent parsing functions for non-semantic files. This
8319 is an alist where the car is a major-mode symbol and the cdr is a
8320 function-symbol of a function which should be used for parsing a
8321 non-semantic buffer, i.h. a buffer for which no semantic grammar
8322 exists. Such a function gets one argument - the filename of current
8323 buffer - and has to generate and return a tag/tag list which is
8324 understandable by @code{speedbar-insert-generic-list}. speedbar has
8325 already included two functions @code{speedbar-fetch-dynamic-imenu} and
8326 @code{speedbar-fetch-dynamic-etags} which can be used for parsing
8327 buffers with imenu rsp. etags.
8329 This option takes only effect if @code{ecb-process-non-semantic-files}
8330 is not nil: Then ECB checks for non-semantic buffers if current
8331 @code{major-mode} is contained in this option and if yes, then the
8332 specified parsing function is called; if not then the cars of the
8333 elements of @code{speedbar-dynamic-tags-function-list} are called in
8334 that sequence they are listed in this variable. See option
8335 @code{speedbar-dynamic-tags-function-list} for further details.
8337 In most cases imenu-parsing is preferable over etags-parsing because
8338 imenu operates on Emacs-buffers and needs no external tool and
8339 therefore parsing works also if current contents of a buffer are not
8340 saved to disk. But maybe sometimes etags may return better parsing
8343 IMPORTANT: if imenu-parsing should be used then the option
8344 @code{speedbar-use-imenu-flag} must be set to not nil!
8347 @defopt process-non-semantic-files
8348 Display content of non-semantic-files in the ECB-methods-buffer. See
8349 also @code{ecb-non-semantic-parsing-function}.
8352 @defopt rebuild-non-semantic-methods-before-hook
8353 Hook running at beginning of the function
8354 @code{ecb-rebuild-methods-buffer-for-non-semantic}. This function is
8355 always called by the command @code{ecb-rebuild-methods-buffer} for not
8356 semantic supported source-types.
8358 Every function of this hook gets one argument: The complete filename
8359 of the current source-buffer in the edit-window. The Method-buffer is
8360 only rebuild by @code{ecb-rebuild-methods-buffer-for-non-semantic} if
8361 either the hook contains no function (the default) or if no function
8362 of this hook returns nil! See @code{run-hook-with-args-until-failure}
8363 for description how these function are processed.
8366 @node ecb-winman, ecb-mode-line, ecb-non-semantic, Customizable options
8367 @subsection Group ecb-winman
8370 This group contains settings for supporting several window-managers:
8372 @defopt winman-escreen-number
8373 Number of the escreen which is reserved for ECB. If you go to the
8374 escreen with this number you go always to the escreen with activated
8375 ECB. All other escreen-numbers are escreens with deactivated ECB!
8378 @defopt winman-winring-name
8379 Name of the winring-window-configuration reserved for ECB. If you go
8380 to the window-configuration with this name you go always to the
8381 window-configuration with activated ECB. All other
8382 window-configuration are configurations with deactivated ECB!
8385 @node ecb-mode-line, ecb-version-control, ecb-winman, Customizable options
8386 @subsection Group ecb-mode-line
8389 This group contains settings for the modelines of the
8392 @defopt mode-line-data
8393 Data shown in the modelines of the special ECB-buffers. Everey element
8394 of this list is a cons-cell where the car is used to define a
8395 buffer-name and the cdr to define the modeline-data for that buffer.
8396 For details about how to defining a buffer-name see
8397 @code{ecb-mode-line-prefixes} - its completely the same.
8399 The cdr is the data for ths modeline and can either be the symbol
8400 @code{sel-dir} or @code{sel-source} whereas the former one displays
8401 the current selected directory as modeline-data and the latter one the
8402 current selected source-file (without path).
8404 In addition to these two predefined values for every special
8405 ECB-buffer a plain string (which is displayed) or a function can be
8406 specified which gets three args (name of the buffer, current selected
8407 directory and current selected source-file) and must return a string
8408 which will be displayed in the modeline (or nil if no data should be
8409 displayed). Such a function can add the text-property @code{help-echo}
8410 to the result-string. Then this help-string will be displayed when the
8411 user moves the mouse over this section of the modeline.
8413 If a special ECB-buffer should not display special data in its
8414 modeline then this buffer-name should either not being added to this
8415 option or added with ``No data'' (= nil as cdr).
8417 The whole modeline of the special ECB-buffer consists of the prefix of
8418 @code{ecb-mode-line-prefixes} and the data of
8419 @code{ecb-mode-line-data} - eventually prepended by the window-number,
8420 see @code{ecb-mode-line-display-window-number}.
8423 @defopt mode-line-data-face
8424 Face used for the data in the mode-line. See
8425 @code{ecb-mode-line-data}. For XEmacs the face should inherit from the
8426 face @code{modeline} (see @code{set-face-parent})!
8430 @defopt mode-line-display-window-number
8431 Display in the modeline of every special ECB-window the window-number.
8432 The left-top-most window in a frame has the window-number 0 and all
8433 other windows are numbered with increasing numbers in the sequence,
8434 functions like @code{other-window} or @code{next-window} would walk
8437 This can be used to jump to windows by number with commands like:
8441 (defun my-switch-to-window-number (number)
8442 ``Switch to the nth window''
8444 (if (integerp number)
8445 (select-window (nth number (window-list)))))
8449 Currently this feature is only available for GNU Emacs 21.X, because
8450 neither GNU Emacs < 21 nor XEmacs can evaluate dynamically forms in
8454 @defopt mode-line-prefixes
8455 Prefixes shown in the modelines of the special ECB-buffers. The
8456 displayed prefix then looks like: ``[ <PREFIX>[: ]]'', means if a
8457 prefix is defined for an special ECB-buffer then a single space is
8458 prepended and if there is additional text to display (e.g. the current
8459 directory in the sources buffer, see @code{ecb-mode-line-data}) then
8460 also the string ``: '' is appended.
8462 Everey element of this list is a cons-cell where the car is used to
8463 define a buffer-name and the cdr to define the modeline-prefix for
8466 The buffer-name can either be defined as plain string or with a symbol
8467 which contains the buffer-name as value. The latter one is recommended
8468 to define a prefix for one of the builtin ECB-tree-buffers because
8469 then simply the related option-symbol can be used. To add a prefix for
8470 the builtin directories tree-buffer just set the symbol
8471 @code{ecb-directories-buffer-name} as car.
8473 The cdr is the prefix for a buffer and can either be a string which
8474 used as it is or a function-symbol which is called with three argument
8475 (the buffer-name, the current selected directory and the current
8476 selected source-file) and must return either nil (for no prefix) or a
8477 string which is then used a prefix. Such a function can add the
8478 text-property @code{help-echo} to the result-string. Then this
8479 help-string will be displayed when the user moves the mouse over this
8480 section of the modeline.
8482 If a special ECB-buffer should not have a prefix in its modeline then
8483 this buffer-name should either not being added to this option or added
8484 with ``No prefix'' (= nil as cdr).
8487 @defopt mode-line-prefix-face
8488 Face used for the prefix in the mode-line. See
8489 @code{ecb-mode-line-prefixes}. For XEmacs the face should inherit from
8490 the face @code{modeline} (see @code{set-face-parent})!
8493 @defopt mode-line-win-nr-face
8494 Face used for the window-number in the mode-line. See
8495 @code{ecb-mode-line-display-window-number}. For XEmacs the face should
8496 inherit from the face @code{modeline} (see @code{set-face-parent})!
8499 @node ecb-version-control, ,ecb-mode-line, Customizable options
8500 @subsection Group ecb-version-control
8503 This group contains settings for the version-control-support of ECB:
8505 @defopt vc-directory-exclude-regexps
8506 Which directories should be excluded from VC-state-check. If a
8507 directory matches any of the regexps of this option the VC-state of
8508 its sources will not be checked - This option takes only effect if
8509 @code{ecb-vc-enable-support} is not nil.
8513 @defopt vc-enable-support
8514 Enable support for version-control (VC) systems. If on then in the
8515 directories-buffer (if the value of the option
8516 @code{ecb-show-sources-in-directories-buffer} is on for current
8517 layout), the sources-buffer and the history-buffer all file-items are
8518 displayed with an appropriate icon in front of the item-name to
8519 indicate the VC-state of this item. If off then no
8520 version-control-state checking is done.
8522 Because this check can be take some time if files are managed by a not
8523 local Version-control-server ECB performs this check stealthy (see
8524 @code{ecb-stealthy-tasks-delay}) so normally there should no
8525 performance-decrease or additional waiting-time for the user. But to
8526 get sure this option offers three choices: @code{t},
8527 @code{unless-remote} and @code{nil}. See the option
8528 @code{ecb-prescan-directories-for-emptyness} for an explanation for
8529 these three choices.
8531 The option @code{ecb-vc-directory-exclude-regexps} offers are more
8532 fine granularity to exclude the sources of certain directories from
8535 See @code{ecb-vc-supported-backends} and @code{ecb-vc-state-mapping}
8536 how to customize the VC-support itself.
8539 @defopt vc-state-mapping
8540 Mapping between VC-states from the backends and ECB-known VC-states.
8541 ECB understands the following state-values:
8545 The working file is unmodified with respect to the latest version on
8546 the current branch, and not locked.
8549 The working file has been edited by the user. If locking is used for
8550 the file, this state means that the current version is locked by the
8554 The file has not been edited by the user, but there is a more recent
8555 version on the current branch stored in the master file.
8558 The file has been edited by the user, and there is also a more recent
8559 version on the current branch stored in the master file. This state
8560 can only occur if locking is not used for the file.
8563 The working file has already been added/registered to the VC-system
8564 but not yet commited.
8566 @item unlocked-changes
8567 The current version of the working file is not locked, but the working
8568 file has been changed with respect to that version. This state can
8569 only occur for files with locking; it represents an erroneous
8570 condition that should be resolved by the user.
8573 The version-control-system ignores this file (e.g. because included in
8574 a .cvsignore-file in case of CVS).
8577 The state of the file can not be retrieved; probably the file is not
8578 under a version-control-system.
8582 All state-values a check-vc-state-function of
8583 @code{ecb-vc-supported-backends} can return must have a mapping to one
8584 of the ECB-state-values listed above. If for a certain
8585 backend-VC-state no mapping can be found then per default 'edited is
8588 The default value of this option maps already the possible returned
8589 state-values of @code{vc-state} and @code{vc-recompute-state} (both
8590 GNU Emacs) and @code{vc-cvs-status} (Xemacs) to the
8591 ECB-VC-state-values.
8594 @defopt vc-supported-backends
8595 Define how to to identify the VC-backend and how to check the state.
8596 The value of this option is a list containing cons-cells where the car
8597 is a function which is called to identify the VC-backend for a
8598 DIRECTORY and the cdr is a function which is called to check the
8599 VC-state of the FILEs contained in DIRECTORY.
8601 Identify-backend-function: It gets a full directory-name as argument -
8602 always without ending slash (rsp. backslash for native Windows-XEmacs)
8603 - and has to return a unique symbol for the VC-backend which manages
8604 that directory (e.g. 'CVS for the CVS-system or 'RCS for the
8605 RCS-system) or nil if the file is not managed by a
8606 version-control-system.
8608 Check-vc-state-function: It gets a full filename (ie. incl. the
8609 complete directory-part) and has to return a symbol which indicates
8610 the VC-state of that file. The possible returned values of such a
8611 check-vc-state-function have to be mapped with
8612 @code{ecb-vc-state-mapping} to the allowed ECB-VC-state values.
8614 ECB runs for a certain DIRECTORY all identify-backend-functions in
8615 that order they are listed in this option. For the first which returns
8616 a value unequal nil the associated check-state-function is used to
8617 retrieve the VC-state of all sourcefiles in that DIRECTORY.
8619 There is no need for the identify-backend-function or the
8620 check-vc-state-function to cache any state because ECB automatically
8621 caches internally all necessary informations for directories and files
8622 for best possible performance.
8624 To prepend ECB from checking the VC-state for any file set
8625 @code{ecb-vc-enable-support} to nil.
8627 Default value for GNU Emacs: Support for CVS, RCS, SCCS and Subversion
8628 (for the later one the most recent version of the VC-package incl. the
8629 vc-svn library is needed) is added per default. To identify the
8630 VC-backend the functions @code{ecb-vc-managed-by-CVS},
8631 @code{ecb-vc-managed-by-RCS} rsp. @code{ecb-vc-managed-by-SCCS} rsp.
8632 @code{ecb-vc-managed-by-SVN} are used. For all three backends the
8633 function @code{ecb-vc-state} of the VC-package is used.
8635 Default value for XEmacs: XEmacs contains only a quite outdated
8636 VC-package, especially there is no backend-independent
8637 check-vc-state-function available (like @code{vc-state} for GNU
8638 Emacs). Only for CVS a check-vc-state-function is available:
8639 @code{vc-cvs-status}. Therefore ECB adds per default only support for
8640 CVS and uses @code{ecb-vc-managed-by-CVS} rsp. @code{vc-cvs-status}.
8642 Example for GNU Emacs: If @code{vc-recompute-state} (to get real
8643 state-values not only heuristic ones) should be used to check the
8644 state for CVS-managed files and @code{vc-state} for all other backends
8645 then an element (ecb-vc-dir-managed-by-CVS . vc-recompute-state)
8646 should be added at the beginning of this option.
8649 @defopt vc-xemacs-exclude-remote-cvs-repository
8650 Exclude directories with a remote cvs-repository from VC-check. This
8651 option takes only effect for XEmacs and is needed cause of the
8652 outdated VC-package of XEmacs which offers no heuristic state-checking
8653 and also no option @code{vc-cvs-stay-local}. So this option takes only
8654 effect if @code{vc-cvs-stay-local} is not avaiable. In this case ECB
8655 treats directories which are managed by CVS but have a remote
8656 repository as if the directory would be not managed by CVS (so the
8657 files are not checked for their VC-state). This si done to avoid
8658 blocking XEmacs when running full cvs-commands (e.g. ``cvs status'')
8661 Note: When ECB can find the option @code{vc-cvs-stay-local} then this
8662 option will automatically take no effect regardless which
8663 Emacs-version is used.
8667 @node Submitting problem report, Upgrading, Customizing, Top
8668 @chapter Submitting a problem report
8671 @cindex Problem report
8672 If you run into problems with ECB you should first take a look into
8676 @item @ref{Conflicts and bugs} or
8677 @item @ref{Tips and tricks} or
8678 @item the appropriate section of this online-manual.
8681 If your problem(s) still remain you can/should send a problem report
8682 to the ECB mailing list @email{ecb-list@@lists.sourceforge.net}. ECB
8683 offers you a command which does all necessary for you to send a
8684 problem report. Just call @code{ecb-submit-problem-report}! Please
8685 read the documentation of this command, see @ref{Interactive ECB
8688 @strong{IMPORTANT}: Cause of extra appearance of SPAM in the
8689 mailing-lists, SourceForge has changed its policy: Now it is only
8690 possible to post to the mailing-list for users who have subscribed
8691 this mailing-list. So please be aware you will not be able to send
8692 comments, bug reports and improvement suggestions before you have
8693 subscribed the ECB-mailing-list. See the section "Mailing-list" at the
8696 @uref{http://ecb.sourceforge.net}
8699 @url{http://ecb.sourceforge.net}
8703 If you think there are problems concerning parsing-results for certain
8704 sources supported by semantic then you should call
8705 @code{ecb-dump-semantic-toplevel} for the problematic source-buffer
8706 @strong{BEFORE} you call @code{ecb-submit-problem-report} because this
8707 ``dump''-command generates for the current-buffer a new buffer with
8708 name ``*ecb-tag-dump*'' which contains all semantic-tags for this
8709 source. The contents of this ``*ecb-tag-dump*'' will then autom. be
8710 added to the problem-report generated by
8711 @code{ecb-submit-problem-report}!
8713 This command creates a problem-report buffer for you. After that you
8714 get a menu ``Mail'' (dependent on the mail-package used, the menu can
8715 have a different name) with commands to send the problem report. But
8716 for this the variable @code{mail-user-agent} must be configured right for
8717 your system. If you can´t get working this mechanism you can simply
8718 copy the whole problem-report buffer after filling it out and sending
8719 it with your standard mail-client to
8720 @email{ecb-list@@lists.sourceforge.net}!
8722 Please read also the documentation of the option @code{ecb-debug-mode} and
8723 switch on the debug mode of ECB (also available in the Help-menu of
8724 ECB!) before submitting a problem-report!
8726 @node Upgrading, Tips and tricks, Submitting problem report, Top
8727 @chapter Upgrading and downloading packages
8729 This chapter describes all aspects of upgrading to a newer version of
8732 The first section describes how to download and install a new
8733 package from the web, where ``package'' means either ECB itself or the
8734 required libraries semantic, eieio and speedbar.
8736 After installing a new ECB-version ECB checks if the values of the
8737 customized ECB-options are still compatible. If not ECB does some
8738 smart things. This is the topic of the second section.
8741 * Downloading new versions:: How to download newer versions of packages
8742 * Auto. option-upgrading:: ECB can auto. upgrade your options
8745 @node Downloading new versions, Auto. option-upgrading, Upgrading, Upgrading
8746 @section Downloading new versions of ECB and/or required packages
8749 ECB offers the possibility to upgrade to newer versions direct from
8750 the ECB-website. This can be done if the following requirements are
8754 @item A connection to the web is available
8755 @item The tools ``wget'', ``tar'' and ``gzip'' are installed
8757 With Unix-systems these tools are in the
8758 standard-distribution. If you are running any Microsoft Windows system
8759 then you need cygwin@footnote{cygwin is available at
8761 @uref{http://cygwin.com/}
8764 @url{http://cygwin.com/}
8766 } which offers these tools too. On every
8767 system these tools must reside in the @env{PATH} environment-variable!
8769 If you are behind a firewall and you have to use a proxy you maybe
8770 need the following wget-configuration in your file @file{~/.wgetrc}:
8774 # Define your proxies (where 8080 and 8081 are examples
8775 # for the port-numbers)
8776 http_proxy = http://your.proxy.com:8080
8777 ftp_proxy = http://your.ftpproxy.com:8081
8779 # If you do not want to use proxy at all, set this to off.
8785 If these requirements are satisfied you can download and install both
8786 ECB itself and also the required versions of semantic, eieio and
8790 @item Download a new ECB-version with @code{ecb-download-ecb}:
8792 A description for this command you will find in @ref{Interactive ECB
8793 commands}. Check also the options of the customize-group
8794 'ecb-download' (@pxref{ecb-download}).
8796 @anchor{Download required packages}
8797 @item Download and install of required packages:
8799 ECB checks at load-time if the packages semantic, eieio and speedbar
8800 are at least installed and at start-time if the required versions of
8801 semantic, eieio and speedbar (see @file{README}) are installed and
8802 loaded into Emacs. If not you will be asked if you want auto. download
8803 and install them. If you confirm this then ECB does the following:
8807 Checking which versions are available at the download-site of the
8808 required packages. With the option
8809 @code{ecb-download-package-version-type} you can specify which type of
8810 versions (only stable, stable and betas or stable, betas and alphas)
8811 you allow to download and install. This option offers also the choice
8812 of asking you for a certain version. Depending of this setting ECB
8813 either ask you which version it should download and install or chooses
8814 autom. the newest version available which is matching both its
8815 min-max-requirements and the setting in
8816 @code{ecb-download-package-version-type}.
8818 NOTE: Currently there are only beta-versions of speedbar available
8819 therefore this option has to be set to 1 (allow stable and beta
8820 versions). But the speedbar beta-versions are very stable!
8823 Downloading and installing the right version (see 1.) of the required
8824 packages. ECB downloads and installs the new package versions in
8825 subdirectories of @code{ecb-download-install-parent-dir}.
8828 If both of these actions succeed then you will get a message-buffer
8829 which tells you something like:
8833 -----------------------------------------------------------------
8834 Current state of the required packages semantic, eieio, speedbar:
8836 - semantic author-version must be [1.4, 1.4.9]:
8837 Installed in /usr/local/lib/site-lisp/semantic-1.4
8839 - eieio author-version must be [0.17, 0.17.9]:
8840 Correct version already loaded!
8842 - speedbar author-version must be [0.14beta1, 0.15.9]:
8843 Correct version already loaded!
8845 After adding the new directory to your @code{load-path} and then
8846 restarting Emacs the new package(s) can be activated.
8847 -----------------------------------------------------------------
8852 @strong{Remark 1}: "P author-version must be [x y]" means, that ECB
8853 requires package P in a version-number >= x and <= y.
8855 @strong{Remark 2}: By setting the option @code{ecb-version-check} to
8856 @code{nil} you can prevent ECB from checking correct versions of
8857 semantic, eieio and speedbar but it's strongly recommended not to do
8861 @node Auto. option-upgrading, , Downloading new versions, Upgrading
8862 @section Automatic upgrading of options
8865 * User interface:: Options and commands you should know
8866 * Background information:: Maybe some interesting informations
8869 @node User interface, Background information, Auto. option-upgrading, Auto. option-upgrading
8870 @subsection User interface for option-upgrading
8872 There are two interactive commands (@pxref{Interactive ECB commands}):
8875 @item @code{ecb-upgrade-options}:
8876 Does all necessary beginning with a incompatibility-check for all
8877 options, upgrading/resetting incompatible options and ending with the
8878 display of all upgraded or reset options.
8880 @item @code{ecb-display-upgraded-options}:
8881 Displays an information-buffer which options have been upgraded or
8882 reset. Offers two buttons where the user can decide if the upgraded
8883 options should also being saved by ECB for future settings or if the
8884 buffer should be killed.
8887 If the option @code{ecb-auto-compatibility-check} has a non-nil value
8888 (which is the default) then ECB does all this stuff automatically at
8889 startup. This is very recommended!
8891 If you are interested in some background information, read
8892 @ref{Background information}!
8894 @node Background information, , User interface, Auto. option-upgrading
8895 @subsection Background information
8897 Big packages like ECB will be enhanced and developed continuously so
8898 sometimes a new version must be released. Such packages offer in
8899 general a lot of customizable options so probably some of these
8900 options change the type or are renamed because the old type and/or
8901 name of the option makes no sense in the new release.
8903 Especially options which have changed the type of their value are now
8904 a problem for the user which want to upgrade to the latest
8905 ECB-version: If the user has saved a certain value for option X in its
8906 file @file{.emacs} but the type of this saved value doesn't match the
8907 new defined type in the defcustom-form after an ECB-upgrade then there
8908 can occur serious problems like ECB can not be started anymore or even
8909 Emacs can not be started without errors.
8911 Until now there was only one way to fix these problems: The user must
8912 manually edit his file @file{.emacs} and remove all entries for
8913 options which have now another type. After this and after restarting
8914 Emacs the new default-values of the type-changed options in the new
8915 ECB-release are active and the user can go on using Emacs and ECB. But
8916 this approach to fix the incompatible-option-problem has two serious
8921 The user must manually edit the customize-section in his file
8922 @file{.emacs}. This should normally not be done and if then only by
8923 old-handed Emacs-users.
8926 The customized value of the option X in the old-release (with the old
8927 type) is lost because after removing the related entry from the
8928 file @file{.emacs} the new default-value is active, so the user must
8929 re-customize the option X.
8932 OK, this is one half of the option-upgrade-problem but a new ECB-release
8933 can also rename a option from name X to name Y because the new name Y makes
8934 much more sense and/or is more mnemonic. If only the name has changed but
8935 not the type this is not a serious problem like above but also annoying
8936 because the customized value of the old-option X takes no effect in the new
8937 release but instead the default-value of the new-option Y is now active.
8938 But nevertheless this problem has the drawback number 2 (see above).
8940 The last category of upgrade-problems is a renamed option which has also
8944 ECB has a solution for all these problems:
8949 It checks all customized values of all ECB-options if they are still
8950 type-compatible. If not then it tries to upgrade the old-value to the
8951 new value-type and if this is not possible then it resets the option
8952 to the new default value and offers then to store it via customize in
8953 the .emacs-file (or in any file which is used for customized options).
8954 But ECB does not touch any customization-file without asking the user!
8957 It offers a special constant @code{ecb-upgradable-option-alist} which
8958 allows the ECB-maintainers to define special transformings for renamed
8959 options so even the value of an old-option X can be savely transformed
8960 to the new-option Y and the old setting is not lost.
8963 All these checks and transformings are done at beginning of activating
8964 ECB - if the option @code{ecb-auto-compatibility-check} is not nil. If
8965 ECB has recognized incompatible or renamed options it does its
8966 upgrading/reseting-job so all ECB-options have correct types so ECB
8967 can start correct. After ECB is started it displays a list of all
8968 upgraded or reseted option with their old and new values.
8971 @node Tips and tricks, Elisp programming, Upgrading, Top
8972 @chapter Tips and tricks
8974 This chapter contains some tips and tricks how to deal best with some
8978 * Changing faces:: Changing faces in the ECB tree-buffers
8979 * Small screens:: Working with small screens
8980 * Big screens:: Working with big screens
8981 * Simulating speedbar:: Simulating speedbar without an extra frame
8982 * Integrating speedbar:: Integrating speedbar in the ECB-frame
8983 * Optimize scrolling:: Optimize scrolling in the edit-window
8984 * Large directories:: Working with large directories
8985 * Remote directories:: Working with remote directories
8986 * Version-control support:: Supporting Version control systems
8987 * Using eshell:: Optimal using of eshell in ECB
8988 * Grepping directories:: Grepping directories with ECB
8989 * Working with JDEE:: Working best with ECB and JDEE
8990 * Compile-window on demand:: Displaying the compile-window on demand
8991 * Non-semantic sources:: Parsing and displaying non-semantic sources
8992 * Hide-show:: Using hide-show from the methods-buffer-menu
8993 * Window-managers and ECB:: Support of several Emacs-window-managers
8994 * Tree-buffer styles:: Displaying the trees with different styles
8995 * Using semanticdb:: Using semanticdb for going to external nodes
8998 @node Changing faces, Small screens, Tips and tricks, Tips and tricks
8999 @section Changing faces in the ECB tree-buffers
9002 There are two basic faces:
9005 @item @code{ecb-default-general-face}:
9006 Basic face for displaying an ECB-tree-buffer.
9008 It´s recommended to define the font-family, the font-size, the basic
9009 color etc. with this face.
9011 In GNU Emacs 21.X all faces (even the face
9012 @code{ecb-default-highlight-face}) used in the ECB tree-buffers
9013 inherit from this face. Therefore the default attributes like font
9014 etc. of a face used in a tree-buffer can be very easily changed with
9015 face @code{ecb-default-general-face}.
9017 With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the
9018 options @code{ecb-directories-general-face},
9019 @code{ecb-sources-general-face}, @code{ecb-methods-general-face} and
9020 @code{ecb-history-general-face} offer the choice to use the face
9021 @code{ecb-default-general-face} so also with XEmacs and GNU Emacs 20.X
9022 the basic face-settings can be easily changed just by customizing the
9023 face @code{ecb-default-general-face}.
9025 @item @code{ecb-default-highlight-face}:
9026 Basic face for highlighting the current node in an ECB-tree-buffer.
9028 In GNU Emacs 21.X all highlighting faces used in the ECB tree-buffers
9029 inherit from this face. Therefore the default attributes like font
9030 etc. of a highlighting face used in a tree-buffer can be very easily
9031 changed with face @code{ecb-default-highlight-face}.
9033 With XEmacs and GNU Emacs 20.X there is no inheritance-feature but the
9034 options @code{ecb-directory-face}, @code{ecb-source-face},
9035 @code{ecb-method-face} and @code{ecb-history-face} offer the choice to
9036 use the face @code{ecb-default-highlight-face} so also with XEmacs and
9037 GNU Emacs 20.X the basic face-settings can be easily changed just by
9038 customizing the face @code{ecb-default-highlight-face}.
9042 With these faces you can change the basic attributes easily and fast
9043 for ALL ECB-tree-buffers. But you are also able to display each
9044 ECB-tree-buffer with different faces, see the different options for
9045 every tree-buffer mentioned above.
9047 @strong{Please note} (only for XEmacs users): Cause of the lack of the
9048 font-inheritance feature using ONE other font for the ECB-methods
9049 buffer can NOT be achieved just by setting
9050 @code{ecb-methods-general-face} to @code{ecb-default-general-face} and
9051 changing the font of this default face. In addition you have to set
9052 the same font also for the face @code{ecb-bucket-node-face} like in
9053 the following example:
9056 (defconst my-ecb-font
9057 "-outline-Courier-normal-normal-13-97-96-96-c-*-iso8859-1")
9058 (set-face-font 'ecb-default-general-face my-ecb-font)
9059 (set-face-font 'ecb-bucket-node-face my-ecb-font)
9062 This code sets the new defined font @code{my-ecb-font} as font for
9063 all@footnote{Of course @code{ecb-directories-general-face},
9064 @code{ecb-sources-general-face}, @code{ecb-methods-general-face} and
9065 @code{ecb-history-general-face} must be set to
9066 @code{ecb-default-general-face}!} ECB-tree-buffers (incl. the methods
9069 @node Small screens, Big screens, Changing faces, Tips and tricks
9070 @section Working with small screens
9072 @cindex Small screen
9073 If your screen is very small so you need every square-centimeter for
9074 displaying the buffer which you want to edit, ECB offers you a special
9075 layouts, where only the ECB-methods buffer is displayed on top or on
9076 left-side. Here comes what you should/can do to work best with ECB in
9080 @item First customize your ECB:
9084 Customize @code{ecb-layout-name} to layout-name ``top2'' (on top) or
9085 ``left9'' (on left-side)
9088 Ensure that @code{ecb-compile-window-height} is nil.
9091 Optional: Adjust the @code{ecb-windows-height} rsp. @code{ecb-windows-width}.
9097 @item To edit your buffers:
9098 Call @code{ecb-toggle-ecb-windows} (also available via the menu ``ECB'' and
9099 by @kbd{C-c . lw}) or @code{ecb-hide-ecb-windows} to hide the ECB-method buffer
9100 so you get all the place of your screen for editing.
9102 @item To browse and select functions:
9103 Call @code{ecb-toggle-ecb-windows} or @code{ecb-show-ecb-windows} to
9104 make the ECB-method buffer visible if not already. If you want select
9105 a method/variable with the keyboard instead with the mouse you should
9106 read the section @ref{Using the keyboard} in this online help!
9109 The possibility of hiding temporally the ECB windows like described
9110 above is also useful for all the other layouts.
9113 @node Big screens, Simulating speedbar, Small screens, Tips and tricks
9114 @section Working with big screens
9116 ECB offers a layout type ``left-right'' with special ECB-tree-windows
9117 on the left and right side of the edit-area. The layouts
9118 ``leftright1'' and ``leftright2''are examples for this layout type.
9119 See @ref{Creating a new ECB-layout} and @ref{The layout-engine}
9120 for details about how to create or program more layouts of this type.
9122 Such a layout is eventually the best choice for big screens because
9123 the several ECB-tree-windows are bigger and can display more
9124 informations without scrolling.
9126 With such a layout it can could be senseful to reduce the value of the
9127 option @code{ecb-windows-width} compared to layouts of type left or
9128 right. A value of max. 0.25 should be enough.
9130 @node Simulating speedbar, Integrating speedbar, Big screens, Tips and tricks
9131 @section Simulating speedbar without an extra frame
9134 You can simulate a speedbar-like layout within ONE frame by doing the
9139 Customize @code{ecb-layout-name} to layout name ``left9'', ``left12'',
9140 ``left13'' or ``left14'' dependent to what you like.
9143 Optional: Ensure that @code{ecb-compile-window-height} is nil.
9146 Optional: Adjust the @code{ecb-windows-width}.
9149 Optional: Customize @code{ecb-toggle-layout-sequence} and toggle very fast
9150 between several layouts by @code{ecb-toggle-layout}. See the doc-strings!
9153 Optional: Customize @code{ecb-show-sources-in-directories-buffer} to
9154 not nil if the chosen layout (see 1. and 4.) contains a
9155 directories-tree-buffer.
9161 But not only simulating speedbar is possible but also full integrating
9162 it into the ECB and the ECB-frame, @xref{Integrating speedbar}.
9164 @node Integrating speedbar, Optimize scrolling, Simulating speedbar, Tips and tricks
9165 @section Integrating speedbar in the ECB-frame
9167 It is very easy to integrate speedbar into ECB. There are two
9168 different ways to do this:
9172 You can either use speedbar in the directories-, sources- or
9173 methods-window of ECB instead of the built-in directory-, sources- or
9174 methods-browser of ECB. This can be done via the option
9175 @code{ecb-use-speedbar-instead-native-tree-buffer}.
9178 Or you can integrate an extra speedbar-window into a layout
9179 independent of the existence of a directory-, sources- or
9180 methods-window. For this you can either use the built-in layout
9181 ``left-dir-plus-speedbar'' or you have to create your own layout
9182 interactively with the command @code{ecb-create-new-layout}. This way
9183 is not described in more details because there is nothing more to
9184 describe - just create your layout.
9187 In general integrating speedbar into the ECB-frame makes sense for
9192 ...who like the speedbar way of handling directories and source-files
9193 but also like the ECB-way of displaying the buffer-contents (like
9194 methods and variables in a source-file). This people should use the
9195 option @code{ecb-use-speedbar-instead-native-tree-buffer} and set it
9199 ...who like the speedbar way of browsing things like directories,
9200 files, file-contents etc. but who dislike the extra speedbar-frame.
9203 Note: It is not necessary to integrate speedbar if you only want
9204 parsing sources not supported by semantic. From version 1.94 on ECB
9205 supports native parsing and displaying of such sources
9206 (@pxref{Non-semantic sources})!
9208 Regardless the group you belong, with the speedbar-integration feature
9209 of ECB you can combine both worlds, the speedbar- and the ECB-world:
9212 @item Choose a layout which either contains a directories- or a
9213 sources-window but not both of them@footnote{Only one of them is
9214 needed if you use speedbar because speedbar displays directories and
9215 sources in one window. But if you like wasting space then you can also
9216 use a layout with both windows...}.
9218 Because speedbar has also display-modes for buffers and info-nodes and
9219 some other useful things (which can be changed by the speedbar-command
9220 @code{speedbar-change-initial-expansion-list} we recommend layouts
9221 like ``left15'' or ``leftright3'' for using with speedbar.
9223 @item Set the option
9224 @code{ecb-use-speedbar-instead-native-tree-buffer} to not nil. After
9225 this the chosen window of ECB will contain a full featured speedbar
9226 (the only difference to standard speedbar is not residing in an extra
9230 Note: If you belong to the first group of people (s.a.) a similar
9231 effect and usability is available by setting
9232 @code{ecb-use-speedbar-instead-native-tree-buffer} to nil and setting
9233 @code{ecb-show-sources-in-directories-buffer} to not nil, because this
9234 combination displays also directories and sources in one window.
9236 So with the option @code{ecb-use-speedbar-instead-native-tree-buffer}
9237 you have the choice which way of displaying and handling ``things''
9238 (directories, sources, methods...) you want (the speedbar- or the
9241 During speedbar is running within ECB (i.e.
9242 @code{ecb-use-speedbar-instead-native-tree-buffer} is not nil) the
9243 speedbar-command @code{speedbar} is disabled and the speedbar-command
9244 @code{speedbar-get-focus} switches between the speedbar-window and the
9245 edit-window@footnote{The standard behavior is switching between the
9246 speedbar-frame and the attached frame, but this make obviously no
9247 sense during running speedbar with ECB.}.
9249 @strong{IMPORTANT}: ECB can only integrate speedbar-versions >=
9250 0.14beta1! If you use lower versions of speedbar
9251 @code{ecb-use-speedbar-instead-native-tree-buffer} has no effect.
9253 @node Optimize scrolling, Large directories, Integrating speedbar, Tips and tricks
9254 @section Optimize scrolling in the edit-window
9257 Emacs 20.X seems to slow down scrolling if there is a horizontal split
9258 in the frame and/or a lot of overlays in the buffer which is scrolled.
9259 This is independent of ECB! But because almost all layouts of ECB uses
9260 horizontal splits of the frame and because ECB is based on semantic
9261 which uses overlays intensively there can be poor scrolling
9262 performance in large buffers, especially with java-buffers in
9265 This scrolling performance can be increased a lot if the options
9266 @code{scroll-conservatively} and @code{scroll-step} are set
9267 appropriately: The former one should have a value of 0 during ECB is
9268 active and the latter one a value of either 0 or > 1 (the exact value
9269 depends on the power of your machine).
9271 As far as we know this is not a problem of Emacs 21.X or XEmacs. With
9272 these versions of Emacs there should be no scrolling problem even with
9273 @code{scroll-step} has value 1.
9276 @node Large directories, Remote directories, Optimize scrolling, Tips and tricks
9277 @section Working with large directories
9279 If @code{ecb-source-path} contains directories with many files and
9280 subdirs, especially if these directories are mounted net-drives
9281 (``many'' means here something > 500, dependent on the speed of the
9282 net-connection and the machine), actualizing the sources- and/or
9283 directories- buffer of ECB (if displayed in current layout!) can slow
9284 down dramatically. If this is a problem the contents of certain
9285 directories and also the contents of the sources-buffer can be cached
9286 which increases the speed a lot. See the option
9287 @code{ecb-cache-directory-contents}.
9289 IMPORTANT: The full speed-advantage of this cache-mechanism is only
9290 available if @code{ecb-show-sources-in-directories-buffer} is
9291 @code{nil}, i.e. sources of a directory are displayed in the
9292 ECB-sources-window. The reason is that only with a sources window the
9293 tree-buffer contents for the sources can be cached (i.e. the
9294 buffer-content of the ECB-sources-window) whereas with sources
9295 displayed in the directories buffer only the disk-contents of a
9296 directory are cached - which increases speed too but not so much as
9297 with sources displayed in the extra window ECB-sources.
9299 The cache of a directory can be only refreshed by a POWER-click (with
9300 mouse or keyboard) onto the related directory-node in the
9301 directories-buffer of ECB (@pxref{Using the mouse}).
9303 See also the option @code{ecb-cache-directory-contents-not}. Here are
9304 some useful settings for both of these options:
9307 @item Cache all directories with more than 500 entries:
9308 Set @code{ecb-cache-directory-contents} to ((``.*'' . 500)) and set
9309 @code{ecb-cache-directory-contents-not} to nil.
9311 @item Cache only all directories > 200 beginning with /usr/
9312 Set @code{ecb-cache-directory-contents} to ((``^/usr/.*'' . 200)) and
9313 set @code{ecb-cache-directory-contents-not} to nil.
9315 @item Cache all directories > 500 but NOT these beginning with /usr/:
9316 Set @code{ecb-cache-directory-contents} to ((``.*'' . 500)) and set
9317 @code{ecb-cache-directory-contents-not} to (``^/usr/.*'').
9320 Another way for getting a faster overlook for large directories with
9321 many source-entries is to apply an online-filter to the
9322 sources-buffer. This can be done via the command
9323 @code{ecb-sources-filter} or via the popup-menu of the sources-buffer.
9325 @node Remote directories, Version-control support, Large directories, Tips and tricks
9326 @section Working with remote directories
9328 The term ``remote'' means directories which are remote in the sense of
9329 TRAMP@footnote{TRAMP stands for 'Transparent Remote (file) Access,
9330 Multiple Protocol'. This package provides remote file editing, similar
9331 to ANGE-FTP.}, ANGE-FTP@footnote{This package attempts to make
9332 accessing files and directories using FTP from within Emacs as simple
9333 and transparent as possible.} or EFS@footnote{A system for transparent
9334 file-transfer between remote hosts using the FTP protocol within
9335 Emacs}. Each of these Emacs-addons is intended to make editing
9336 directories and files on remote machines as transparent as possible.
9338 @subsection General remarks
9340 ECB supports such remote directoires out of the box and completely
9341 transparently, i.e. you can add remote directories to the option
9342 @code{ecb-source-path} without any restriction. ECB will handle these
9343 directories transparently with the appropriate tool - either TRAMP,
9344 ANGE-FTP or EFS. So when working with such a remote directory is
9345 possible without ECB it will be possible too with active ECB - at
9346 least as long you are ``connected''!
9348 @strong{Caution}: Suppose you have added a remote dir (e.g.
9349 ``user@@host.at.a.server:/dir/'') to @code{ecb-source-path} and you
9350 start ECB when you are offline, means there can be no connection
9351 established to the remote computer (e.g. ``host.at.a.server''). Each
9352 time ECB has to process a remote path ECB pings via the ping-program
9353 the remote host (in the example above it would ping the host
9354 ``host.at.a.server'') to test if it is accessible. If not then this
9355 path will be ignored by ECB@footnote{This avoids long lasting and
9356 annoying blocking of ECB when a remote-path is not accessible: Without
9357 a ping ECB would always try to open this directory through the
9358 appropriate library (e.g. TRAMP) and it would depend on the
9359 timeout-mechanism of this library (e.g. TRAMP has 60 seconds) how long
9360 ECB would be blocked. First after this timeout ECB could start
9361 working! A fast ``pre''-ping avoids this problem!}. Ensure that ECB
9362 calls your ping-program (see @code{ecb-ping-program}) with the right
9363 options (see @code{ecb-ping-options}). To avoid to many pings to the
9364 same host ECB caches the ping result so there should be no performance
9365 decrease. But to ensure still correct accessible-results and to avoid
9366 using outdated cache-results ECB discards the cached value of the
9367 accessible-state of a certain host after a customizable time-interval
9368 (please read the documentation of
9369 @code{ecb-host-accessible-check-valid-time}!).
9372 @subsection Excluding remote directories from time-consuming tasks
9374 ECB performs some tasks stealthy and interruptable by the user (see
9375 the option @code{ecb-stealthy-tasks-delay} for additional
9376 explanations) because these tasks are time-consuming and could
9377 otherwise ECB block. Especially for remote directories these special
9378 tasks can cause annoying blocks of Emacs (@pxref{Stealthy background
9381 Therefore it is probably the best to switch on each of the stealthy
9382 tasks with the @code{unless-remote} which is the default activation
9383 (@pxref{Stealthy background tasks}). So a certain stealthy task will
9384 be swtiched on for all local directories (and also for all mounted
9385 drives in the LAN) but not for real remote directories used via TRAMP,
9388 @subsection Caching the contents of remote directories
9390 ECB caches per default the contents of remote directories to avoid
9391 annoying delays. The cache is done via the option
9392 @code{ecb-cache-directory-contents} which contains an entry which
9393 covers the syntax of remote directories. If you do not want this
9394 caching (which is strongly recommened) you have to remove this entry
9397 @node Version-control support, Using eshell, Remote directories, Tips and tricks
9398 @section Supporting Version control systems
9400 Beginning with version 2.30 ECB supports Version-control systems (in
9401 the following named VC-systems). This means the special tree-buffers
9402 of ECB display files managed by a VC-system with an appropriate
9403 image-icon@footnote{Of course only when Emacs is capable to display
9404 images; otherwise a suitable ascii-icon will be displayed.} in front
9407 The following four options allow full control over this feature (see
9408 also @ref{ecb-version-control}:
9411 @item ecb-vc-enable-support
9412 Enable or disable this feature.
9413 @item ecb-vc-supported-backends
9414 The most important option for this feature. Allows to specify how ECB
9415 should test if a directory is managed by a VC-system (how to identify
9416 the VC-backend of a directory) and - if yes - how it should check the
9417 VC-state of a certain file. The former ones are called
9418 @dfn{identify-backend-functions} and the latter ones
9419 @dfn{check-state-functions}.
9420 @item ecb-vc-directory-exclude-regexps
9421 Allows excluding certain directories (on a regexp-basis) from the
9422 VC-support even if they are managed by a VC-system.
9423 @item ecb-vc-state-mapping
9424 Defines the mapping between the state-values returned by a
9425 check-state-function (a function set in
9426 @code{ecb-vc-supported-backends} and used for getting the VC-state of
9427 a file, e.g. @code{vc-state}) and the allowed state-values ECB can
9431 Probably the default settings will fit your needs but to get sure you
9432 should carefully read the documentation of these options!
9434 The following subsection give you important informations about
9435 identify-backend-functions, check-state-functions, about working with
9436 remote repositories.
9439 * Identifying backends:: How ECB identifies the VC-backend of a dir
9440 * Checking the state:: How ECB checks the VC-state of a file
9441 * Remote repositories:: What you should now about this
9442 * Refreshing the VC-state:: How to refresh when state changed outside
9443 * Adding new backends:: Necessary steps for adding new backends
9444 * Known VC-problems:: Currently known problems of the VC-support
9447 @node Identifying backends, Checking the state, Version-control support, Version-control support
9448 @subsection How ECB identifies the VC-backend of a dir
9450 ECB tries all functions added as identify-backend-funtions to the
9451 option @code{ecb-vc-supported-backends} until one of them returns not
9452 @code{nil} but a symbol which identifies the backend (e.g.
9453 @code{CVS}). After this check ECB stores the result of this check
9454 (i.e. either the identified backend or the fact that the directory is
9455 not managed by a VC-system) for that directory in a special cache, so
9456 the identify-backend-process will be performed only once per
9457 directory. If for a directory a VC-backend could be identified ECB
9458 stores not only the backend itself for that directory but also the
9459 associated check-state-function defined in
9460 @code{ecb-vc-supported-backends} (@pxref{Checking the state}).
9462 You can add arbitrary functions to this options as long they get one
9463 directory-argument and return either nil oder a backend-symbol. Per
9464 default ECB offers the following functions to identify the VC-backend
9465 CVS, RCS, SCCS or Subversion@footnote{For this the most recent version
9466 of the VC-package (incl. the library vc-svn.el) is needed - as
9467 contained in CVS Emacs}:
9470 @item ecb-vc-dir-managed-by-CVS DIRECTORY
9471 Return @code{CVS} if DIRECTORY is managed by CVS. nil if not.
9473 This function tries to be as smart as possible: First it checks if
9474 DIRECTORY is managed by CVS by checking if there is a subdir
9475 @code{CVS}. If no then nil is returned. If yes then for GNU Emacs it
9476 takes into account the value of @code{vc-cvs-stay-local}: If t then
9477 just return @code{CVS}. Otherwise ECB checks the root repository if it
9478 is a remote repository. If not just @code{CVS} is returned. If a
9479 remote repository it checks if the value of @code{vc-cvs-stay-local}
9480 is a string and matches the host of that repository. If yes then just
9481 @code{CVS} is returned. If not then ECB checks if that host is
9482 currently accessible by performing a ping. If accessible @code{CVS} is
9483 returned otherwise nil. This has the advantage that ECB will not be
9484 blocked by trying to get the state from a remote repository while the
9485 host is not accessible (e.g. because the user works offline).
9487 Special remark for XEmacs: XEmacs has a quite outdated VC-package
9488 which has no option @code{vc-cvs-stay-local} so the user can not work
9489 with remote CVS-repositories if working offline for example. So if
9490 there is no option @code{vc-cvs-stay-local} then ECB performs always
9491 the repository check mentioned above.
9493 @item ecb-vc-dir-managed-by-RCS DIRECTORY
9494 Return @code{RCS} if DIRECTORY is managed by RCS. nil if not.
9496 @item ecb-vc-dir-managed-by-SCCS DIRECTORY
9497 Return @code{SCCS} if DIRECTORY is managed by SCCS. nil if not.
9499 @item ecb-vc-dir-managed-by-SVN DIRECTORY
9500 Return @code{SVN} if DIRECTORY is managed by Subversion. nil if not.
9501 Returns always nil if the library vc-svn.el can not be found.
9505 If ECB should support other VC-backends than CVS, RCS, SCCS or
9506 Subversion you have to write your own identify-backend-funtion for the
9507 used VC-backend (e.g. Clearcase)!
9509 @subsubsection Special remarks for XEmacs
9511 XEmacs contains only a quite outdated VC-package, especially there is
9512 no backend-independent check-vc-state-function available (like
9513 @code{vc-state} for GNU Emacs). Only for CVS a check-vc-state-function
9514 is available: @code{vc-cvs-status}. Therefore ECB adds per default
9515 only support for CVS and uses @code{ecb-vc-managed-by-CVS} rsp.
9516 @code{vc-cvs-status}. See also @ref{Known VC-problems}!
9518 @node Checking the state, Remote repositories, Identifying backends, Version-control support
9519 @subsection How ECB checks the VC-state of a file
9521 After ECB has identified the VC-backend of a directory it will display
9522 the VC-state (e.g. up-to-date, edited, needs-mergs etc...) with a
9523 suitable image-icon in the tree-windows of the ECB-file-browser. To
9524 get this state for a certain file ECB uses that check-state-function
9525 stored in the cache for the directory of that file (@pxref{Identifying
9528 You can add any arbitrary functions as check-state-function to
9529 @code{ecb-vc-supported-backends} as long they get one
9530 filename-argument and return a state-symbol (e.g. @code{up-to-date}.
9531 ECB can understand a certain set of state-values wghich are then
9532 mapped to suitable image-icons which will in turn be displayed in
9533 front of the filename in the file-browser. Because the values a
9534 check-state-function return can differ from that state-values ECB
9535 understands, ECB offers an option to define a appropriate
9536 state-mapping. The name of this option is @code{ecb-vc-state-mapping}.
9537 See the documentation of this option to get a list of all state-value
9540 Per default ECB uses - when running under GNU Emacs - the function
9541 @code{vc-state} of the VC-package@footnote{The VC-package of Emacs
9542 offers a standardised and uniform interface for several backends; per
9543 default CVS, RCS, SCCS and Subversion are supported by the
9544 VC-package.} to check the state for the backends CVS, RCS, SCCS and
9545 Subversion. So the default-value of @code{ecb-vc-state-mapping}
9546 contains a mapping between these values @code{ecb-vc-state} can return and
9547 that state-values ECB understands.
9549 If ECB should support other VC-backends than CVS, RCS, SCCS and
9550 Subversion (e.g. Clearcase) you should add a that new backend to the
9551 VC-package (see the initial comments of vc.el how to do this) then ECB
9552 will automatically support this new backend. Alternatively it can be
9553 enough if you write your own check-state-function for this backend and
9554 add the needed mapping to @code{ecb-vc-state-mapping} if necessary.
9556 @subsubsection Getting heuristic state-values or real ones for CVS
9558 The interface of GNU Emacs' VC-package offers two different ways to
9559 get the VC-state of a file:
9562 @item The real, fresh and expensive approach
9563 VC has a function @code{vc-recompute-state} which always performs a
9564 command ``cvs status'' to get a fresh and real state for a file. As
9565 you can imagine this operation can be very expensive and long lasting
9566 depending on the location of the repository. But the CVS-backend of VC
9567 offers with the option @code{vc-cvs-stay-local} a way to tell Emacs to
9568 stay local even for the sake of getting a real state.
9570 @item The heuristic approach:
9571 The function @code{vc-state} always returns a ``heuristic'' state
9572 which should be used when a fresh and real state is not necessary.
9573 With @code{vc-state} the option @code{vc-cvs-stay-local} will never
9577 VC/CVS actually does it this way (regardless if ECB is active or not):
9578 When you visit a file, it always uses just the heuristic to get the
9579 state (comparing file times), regardless of the setting of
9580 @code{vc-cvs-stay-local}. This is because the "fresh-but-slow" state
9581 is determined by calling "cvs status" on the file, and this was deemed
9582 unacceptably slow if done at visiting time under any conditions.
9584 The state is updated by calling @code{vc-recompute-state} prior to
9585 @code{vc-next-action} (C-x v v) which either checks a file in or out.
9586 IF @code{vc-cvs-stay-local} is nil, then this does in fact call "cvs
9587 status" to get the "fresh-but-slow-state", but if
9588 @code{vc-cvs-stay-local} is t, then it just compares the file times
9591 But under certain conditions (e.g. if called for files not already
9592 visited or for files their VC-state has been changed from outside
9593 Emacs, e.g. by checking in the file via command line) @code{vc-state}
9594 does not compute a new heuristic state but returns a cached one
9595 (cached by the VC-package itself not by ECB) which does not reflect
9596 the current VC-state. Example: if you have edited a file within Emacs
9597 and then checked in from outside Emacs @code{vc-state} returns a wrong
9598 state until you call @code{revert-buffer} for this file. Therefore ECB
9599 offers the check-state-function @code{ecb-vc-state} which does the
9600 same as @code{vc-state} but it clears the internal caches of the
9601 VC-package for that file before calling @code{vc-state}.
9603 The bottom line for you is this: If you use @code{ecb-vc-state} in
9604 @code{ecb-vc-supported-backends} to get the version control state,
9605 then you get the same policy that VC uses and you get always a
9606 ``correct'' heuristic state (as correct as possible a heuristic state
9607 can be). There should no harm if you use @code{vc-recompute-state} as
9608 a replacement function if you want to get fresh and real state-values,
9609 but then (a) you must make sure to set @code{vc-cvs-stay-local} to
9610 nil, and (b) fetching the state over the network under all conditions
9611 was deemed unacceptably slow in VC.
9613 @node Remote repositories, Refreshing the VC-state, Checking the state, Version-control support
9614 @subsection Important informations about remote repositories
9616 At least CVS can be used in a mode called ``Client/Server'' which
9617 means the root repository is located on a remote machine. We call a
9618 repository which can not being mounted by the client-machine (which
9619 contains the working directory) a @dfn{remote repository}. In most
9620 cases getting the fresh and real VC-state for such repositories will
9621 be unacceptable slow or often users will work offline means with no
9622 connection available to the remote host. To avoid problems like these
9623 ECB offers first an option @code{ecb-vc-directory-exclude-regexps} to
9624 exclude such directories with a remote repository from the VC-support
9625 of ECB and secondary the identify-backend-funtion
9626 @code{ecb-vc-dir-managed-by-CVS} behaves smart with that respect
9627 (@pxref{Identifying backends}). See also
9628 @code{ecb-vc-xemacs-exclude-remote-cvs-repository}!
9630 @subsubsection Remote paths and the VC-support of ECB
9632 ECB supports working with remote directories like TRAMP- or
9633 EFS-directories (@pxref{Remote directories}). Do not confuse remote
9634 directories with remote repositories. A local directory located on
9635 your disk and set in @code{ecb-source-path} can have a remote
9636 repository if managed by a VC-system. A remote directory means a path
9637 in the format of TRAMP, ANGE-FTP or EFS set in @code{ecb-source-path}.
9638 Its very likely that getting the VC-state of files contained in such a
9639 remote directory would be extremly expensive and therefore ECB would
9640 be blocked quite long even if the VC-check is performed stealthy
9641 (@pxref{Stealthy background tasks}).
9643 To avoid problems with such remote directories ECB prevents per
9644 default such directories from being processed by the VC-support of
9645 ECB. But if a user is dying to having the VC-state being displayed in
9646 the tree-buffers ECB offers two ways to switch on the VC-support - see
9647 the option @code{ecb-vc-enable-support}: This option is set per
9648 default to the value @code{unless-remote} which means remote paths
9649 will not be processed but it can be set to @code{t} which means
9650 process all directories regardless if remote or not. It's strongly
9651 recommended to use @code{unless-remote}!
9653 @node Refreshing the VC-state, Adding new backends, Remote repositories, Version-control support
9654 @subsection How to refresh ECB-state-display when changed outside
9656 If all actions concerning version controlling of a file are performed
9657 within Emacs with commands offeres by VC then the displayed state for
9658 such a file in the tree-buffers of ECB will be always correct - in
9659 that sense that ECB will always display that state which the
9660 check-state-function for the file will return. At least with GNU Emacs
9661 for the backends CVS, RCS, SCCS and Subversion this will be true. With
9662 XEmacs only for CVS. For other backends see @ref{Adding new backends}.
9664 But if the VC-state of a file will be changed outside of Emacs
9665 (unfortunately PCL-CVS must be called ``outside'' too because PCL-CVS
9666 doesn't use the functions of the VC-package of Emacs for checking-in
9667 or -out) then ECB can not automatically recognize this and therefore
9668 it can not aurtomatically update the displayed state-image-icon. You
9669 have to tell ECB for which files in the tree-buffers the VC-state
9670 should be recomputed. This can be done via the popup-menus of the
9671 ECB-tree-buffers - The following popup-commands are offered in the
9672 submenu ``Version Control'':
9675 @item ECB-directories-buffer (if sources are displayed within):
9676 ``Recompute state for file'' and ``Recompute state for dir'' whereas
9677 the latter one recomputes the VC-state for all files of that directory
9679 @item ECB-sources-buffer
9680 ``Recompute state for file'' and ``Recompute state for dir'' whereas
9681 the latter one recomputes the VC-state for all files currently
9682 displayed in the sources-buffer.
9683 @item ECB-history-buffer
9684 ``Recompute state for file'' and ``Recompute state for whole history''
9685 whereas the latter one recomputes the VC-state for all file-entries currently
9686 displayed in the history-buffer.
9689 @strong{Caution}: The state will only recomputed right under all
9690 situations if you use either @code{ecb-vc-state} or
9691 @code{vc-recompute-state} as check-state-function in
9692 @code{ecb-vc-supported-backends} (@pxref{Checking the state}).
9694 Of course all these commands update the VC-state in all visible
9695 tree-buffers the file is currently displayed (e.g. often a file is
9696 displayed in the sources- and the history-buffer)!
9698 For general informations about the usage of popup-menus in ECB see
9699 @ref{Using the mouse} (subsection ``The right mouse button'').
9701 In addition to these popup-commands using the POWER- rsp. Shift-click
9702 (@pxref{Using the mouse}) onto a directory in the directory-window of
9703 ECB refreshes the VC-state-values of all files contained in this
9706 @node Adding new backends, Known VC-problems, Refreshing the VC-state, Version-control support
9707 @subsection Necessary steps and informations for adding new backends
9709 There are mainly three necessary steps for adding a new@footnote{i.e.
9710 not already supported by the VC-package because all these backends are
9711 automatically supported by ECB too!} backend BE which should be
9715 @item Adding an identify-backend-function to @code{ecb-vc-supported-backends}
9716 ECB needs a function how to identify the new backend BE for a certain
9717 directory. If there exists already a library (other then VC)
9718 supporting this backend then this library propably contains already
9719 such a function which can be used or can be used at least with a small
9720 elisp-wrapper. If no elisp-library for backend BE exists then you have
9721 probably write the full identify-backend-function for your self. This
9722 function has to be added to @code{ecb-vc-supported-backends}.
9724 @item Adding an check-state-function to @code{ecb-vc-supported-backends}
9725 Associated to the new identify-backend-function mentioned in step 1 a
9726 new check-state-function is needed which can be used by ECB to get the
9727 VC-state for a file. See @ref{Checking the state} for a description
9728 about the needed interface of such a function. In combinatio with the
9729 identify-backend-function from step 1 this function has to be added to
9730 @code{ecb-vc-supported-backends}.
9732 @item Enabling automatic state-update after checkin/out
9734 This step is not essential if you do not need the displayed VC-state
9735 automatically updated after a checkin/out of a file via the commands
9736 available for backend BE (e.g. clearcase.el offers for the backend
9737 Clearcase elisp-commands to checkin and checkout a file which then
9738 should also update the displayed state in the ECB-tree-buffers. All
9739 you need is a way to tell these commands that they should clear the
9740 ECB-VC-cache for the file and then restart the ECB-VC-check-mechanism.
9741 This should be done after these commands have finished their original
9744 ECB enables this per default for all backends supported by the
9745 VC-package with the following code. Maybe this is a good starting
9750 (defvar ecb-checkedin-file nil
9751 "Stored the filename of the most recent checked-in file. Is only set by the
9752 after-advice of `vc-checkin' and `ecb-vc-checkin-hook' \(resets it to nil).
9753 Evaluated only by `ecb-vc-checkin-hook'.
9755 This is the communication-channel between `vc-checkin' and
9756 `ecb-vc-checkin-hook' so this hook-function gets the filename of the
9759 (defadvice vc-checkin (after ecb)
9760 "Simply stores the filename of the checked-in file in `ecb-checkedin-file'
9761 so it is available in the `vc-checkin-hook'."
9762 (setq ecb-checkedin-file (ecb-fix-filename (ad-get-arg 0))))
9764 (defun ecb-vc-checkin-hook ()
9765 "Ensures that the ECB-cache is reset and the entry for the most recent
9766 checkedin file is cleared. Uses `ecb-checkedin-file' as last checked-in file."
9767 (when ecb-checkedin-file
9768 (ecb-vc-cache-remove ecb-checkedin-file)
9769 (ecb-vc-reset-vc-stealthy-checks)
9770 (setq ecb-checkedin-file nil)))
9776 @node Known VC-problems, ,Adding new backends, Version-control support
9777 @subsection Currently know problems with the VC-support
9779 @subsubsection Remote repositories and XEmacs
9781 Currently there are mostly problems related to XEmacs - cause of its
9782 outdated VC-package which allows no heuristic state-computation but
9783 always runs ``cvs status'' to get the VC-state for a file (done by
9784 @code{vc-cvs-status}). This can be horrible slow for remote
9785 CVS-root-repositories. Now ECB performs the VC-check stealthy and only
9786 in idle-time of Emacs but even so XEmacs can be blocked espcially if
9787 the cygwin-build of XEmacs is used: This XEmacs-version is
9788 substantially slower concering file-operations and has sometimes a
9789 very slow and delayed response-behavior for mouse- and keyboard
9790 interrupts - so even ECB let the user interrupt by using
9791 @code{input-pending-p} before getting the VC-state of a file XEmacs
9792 sometimes does not react to such user-interrupts and seems to be
9795 Current solution: ECB offers the option
9796 @code{ecb-vc-xemacs-exclude-remote-cvs-repository} which excludes
9797 remote repositories from being checked. This option is per default t
9798 for XEmacs. Whenever XEmacs syncs up its VC-package with the Emacs one
9799 this option will automatically take no effect.
9801 @node Using eshell, Grepping directories, Version-control support, Tips and tricks
9802 @section Optimal using of eshell in ECB
9805 ECB offers a very smart integration of the ``eshell'' if you are using
9806 a compile window (@pxref{Temp- and compile-buffers})@footnote{Of
9807 course you can use eshell also if there is no compile-window. Then it
9808 is just displayed in the edit-area and there is no special
9811 Here is a short summary of provided features:
9815 Ability to jump to the eshell buffer within the compilation window by
9816 simply call @code{eshell} (bound to @kbd{C-c . e}). If the eshell
9817 isn't running it will be started.
9820 Expands the compilation window when you run commands. So for example
9821 it allows you to view the eshell in minimized mode and then when you
9822 run ``ls'' the window automatically expands (but always depending of
9823 the output of the command you run).
9826 Synchronizes the current directory of the eshell with the current
9827 buffer in the current active edit-window of ECB.
9830 Provides smart window layout of the eshell buffer. This makes sure
9831 that the eshell is taking up the exact amount of space and that
9835 Here comes a detailed explanation of these features and how to use it
9836 (all these features are only available if you use a durable
9837 compile-window, i.e. if @code{ecb-compile-window-height} is not nil):
9839 You have not to learn a new command for the eshell-start - just call
9840 @code{eshell} (for convenience also bound to @kbd{C-c . e}) and the
9841 eshell will displayed in the compile-window of ECB (if eshell is not
9842 already alive then it will be started automatically).
9844 ECB tries to display the contents of the eshell-buffer as best as
9845 possible, means ECB can autom. enlarge and shrink the compile-window
9846 so the contents of the eshell are fitting the window. See option
9847 @code{ecb-eshell-enlarge-when-eshell} and
9848 @code{ecb-eshell-fit-window-to-command-output}. Normally this is done
9849 autom. but you can also you the standard compile-window
9850 enlarging-command of ECB: @code{ecb-toggle-compile-window-height}.
9852 ECB tries also to recenter the eshell-buffer as best as possible.
9853 Normally this is done autom but you can do it on demand with the
9854 command @code{ecb-eshell-recenter}.
9856 If option @code{ecb-eshell-synchronize} is true then ECB always
9857 synchronizes the command prompt of eshell with the directory of
9858 current source-buffer of the current active edit-window.
9860 With the option @code{ecb-eshell-auto-activate} you can start eshell
9861 autom. in the compile-window when ECB is started but of course if a
9862 compile-window exists.
9864 @node Grepping directories, Working with JDEE, Using eshell, Tips and tricks
9865 @section Grepping directories with ECB
9867 ECB offers in the popup-menus in the directories- and
9868 sources-tree-buffer commands for easy (recursive) grepping the current
9869 directory under point (directory-buffer) rsp. the current-directory
9870 (sources-buffer). In every case just the function of the options
9871 @code{ecb-grep-function} rsp. @code{ecb-grep-find-function} is called
9872 and the @code{default-directory} is tempor. set to the chosen
9873 directory so the grep will performed in this directory regardless of
9874 the @code{default-directory} of current buffer in the edit-window.
9876 Other smart things beyond that are not done by ECB, see also
9877 @code{ecb-grep-function}!
9879 So, how to exclude some subdirectories or files from the grep?
9881 Basically this has to be done with the ``-prune'' option of the
9882 find-utility: If the standard-grep facility of Emacs is used then this
9883 is not easy but with the library @file{igrep.el} there is a convenient
9884 way to exclude things like CVS- or RCS-directories from the find-call:
9885 See the variable @code{igrep-find-prune-clause} of the library
9888 @node Working with JDEE, Compile-window on demand, Grepping directories, Tips and tricks
9889 @section Working best with ECB and JDEE
9891 ECB is completely language independent, i.e. it works with any
9892 language supported by semantic (e.g. C, C++, Java, Elisp etc.).
9894 But there are some special integrations for the great
9895 Java-Development-Environment JDEE:
9898 @item Displaying contents of class under point
9900 With the command @code{ecb-jde-display-class-at-point} you can display
9901 the contents of the class which contains the definition of the
9902 ``thing'' at point (which can be a method, variable etc.).
9904 @item Creating new source-files
9906 The popup-menus in the directories- and the sources-buffer offer a
9907 command ``Create Source'' which allows easy creating new java-sources
9908 by calling the command @code{jde-gen-class-buffer}.
9910 @item Adding user-extensions to the popup-menus
9912 The options @code{ecb-directories-menu-user-extension} and
9913 @code{ecb-sources-menu-user-extension}@footnote{If you need a dynamic
9914 way of menu-extension then you should have a look at the options
9915 @code{ecb-directories-menu-user-extension-function} and
9916 @code{ecb-sources-menu-user-extension-function}.} allow adding often
9917 used JDEE-commands to the popup-menus of the directories- or
9918 sources-buffer. One example is to add building the project of current
9919 directory. Here is a function which could be added to
9920 @code{ecb-directories-menu-user-extension}:
9924 (defun ecb-dir-popup-jde-build (node)
9925 "Build project in directory."
9927 (expand-file-name jde-ant-buildfile (tree-node-get-data node))))
9928 (jde-ant-build project-file "build")))
9932 Of course you can add entries to the option
9933 @code{ecb-methods-menu-user-extension} and
9934 @code{ecb-methods-menu-user-extension} too.
9940 @node Compile-window on demand, Non-semantic sources, Working with JDEE, Tips and tricks
9941 @section Displaying the compile-window on demand
9943 If you like displaying all output of compile/grep/etc. an all
9944 temp-buffers like *Help*-buffers in an extra compile-window
9945 (@pxref{Temp- and compile-buffers}) but you dislike wasting the space
9946 of this compile-window if you are just editing then you can get a
9947 compile-window ``on demand''. Just do the following:
9951 Customize @code{ecb-compile-window-height} to not nil and save it for
9952 future sessions. This gives you an extra compile-window at the
9956 Add the following to your .emacs:
9959 (add-hook 'ecb-activate-hook
9961 (let ((compwin-buffer (ecb-get-compile-window-buffer)))
9962 (if (not (and compwin-buffer
9963 (ecb-compilation-buffer-p compwin-buffer)))
9964 (ecb-toggle-compile-window -1)))))
9967 This hides the extra compile-window direct after the start of ECB
9968 because there is no need for a compile-window at this moment. But the
9969 hiding will not be done if there is a compile-window and if a
9970 ``compile-buffer'' in the sense of @code{ecb-compilation-buffer-p} is
9971 displayed in this compile-window. Without this additional check the
9972 compile-window would always be hidden after the ECB-start even when
9973 ECB is reactivated after a deactivation by the window-manager-support
9974 of ECB (@pxref{Window-managers and ECB}); but in these cases we want
9975 to preserve the state before deactivation as good as possible (see
9976 also option @code{ecb-split-edit-window-after-start}).
9980 This is all you have to do. Now if you run @code{compile} (or
9981 @code{grep} or other compile-modes) or display temp-buffers like
9982 *Help*-buffers then ECB autom. displays the compile-window at the
9983 bottom and display the output there.
9985 If you have finished with using the compile- or temp-output (e.g.
9986 fixing errors) then you can throw away the compile-window just by
9987 @code{ecb-toggle-compile-window} - ECB will reactivate it autom.
9988 before next compilation or help-buffer-display.!
9990 @node Non-semantic sources, Hide-show, Compile-window on demand, Tips and tricks
9991 @section Parsing and displaying non-semantic sources
9993 ECB is mostly designed to display parsing information for files
9994 supported by semantic. But beginning with version 1.94 it also
9995 supports other parsing engines like imenu and etags, so also files not
9996 supported by semantic but by imenu/etags can be displayed in the
9997 Method-buffer of ECB. See @ref{Definition of semantic- and
9998 non-semantic-sources} for a description of ``semantic-sources'' and
9999 ``non-semantic-sources''.
10001 If support of non-semantic-sources is enabled then ECB will display
10002 the contents of all sources which can be displayed by speedbar too.
10003 This comes from the fact that ECB uses speedbar-logic to parse sources
10004 with imenu or etags.
10006 In most cases imenu-parsing is preferable over etags-parsing because
10007 imenu operates on Emacs-buffers and needs no external tool and
10008 therefore parsing works also if current contents of a buffer are not
10011 This section describes all important aspects about parsing and
10012 displaying file-contents of file-types not supported by semantic but
10013 by imenu and/or etags.
10015 @subsection Enabling parsing and displaying of non-semantic-sources
10017 Enabling is simply done with the option @code{ecb-process-non-semantic-files}.
10019 ECB offers an option @code{ecb-non-semantic-parsing-function} to
10020 specify on a major-mode basis which parsing-method should be used:
10021 imenu or etags. Normally there should be no need to change this option
10022 but read the documentation of this option (@pxref{ecb-non-semantic})
10023 for further details.
10029 If imenu-parsing should be used then the option
10030 @code{speedbar-use-imenu-flag} must be set to not @code{nil}!
10033 If some non-semantic-sources are not parsed (i.e. there is an empty
10034 Methods-buffer) and you think that they should then maybe they are neither
10035 supported by imenu nor by etags or you have to check the options
10036 @code{ecb-non-semantic-parsing-function} and
10037 @code{speedbar-dynamic-tags-function-list} and - especially for etags -
10038 @code{speedbar-fetch-etags-parse-list}, @code{speedbar-fetch-etags-arguments}
10039 and @code{speedbar-fetch-etags-command}.
10042 Even with support for semantic-, imenu- and etags-parsing there will
10043 remain some file-types rsp. @code{major-modes} which are not
10044 parse-able, neither by semantic, imenu nor etags. This is no problem
10045 because these files simply have an empty Methods-buffer. But
10046 nevertheless you will get a message ``Sorry, no support for a file of
10047 that extension'' which comes from the speedbar-library and can not
10048 switched off. Therefore if a @code{major-mode} is known as not
10049 parse-able by semantic, imenu or etags it can be added to the option
10050 @code{ecb-non-semantic-exclude-modes} and then it will be excluded
10051 from being tried to parsed and this (annoying) message will not occur.
10054 @subsection Automatic rescanning/reparsing of non-semantic-sources
10056 In contrast to semantic (see @code{global-semantic-auto-parse-mode})
10057 there is no built-in mechanism for autom. reparsing
10058 non-semantic-sources and then updating the contents of the
10061 For non-semantic-sources you have always at least to call
10062 @code{ecb-rebuild-methods-buffer} (bound to @kbd{C-c . r}) or saving
10063 the source-file (if @code{ecb-auto-update-methods-after-save} is true)
10064 to update the Method-buffer@footnote{Maybe future versions of ECB (>
10065 1.94) will offer an autom. mechanism for this.}.
10067 Depending on the parsing-mechanism the following options have to be
10068 switched on so ECB can rebuild the methods-buffer for
10069 non-semantic-sources:
10074 The imenu-option @code{imenu-auto-rescan} must be enabled and
10075 @code{imenu-auto-rescan-maxout} has to be set big enough to auto-parse
10076 big files too! But this results not directly in an autom. updated
10077 Method-buffer. This is first done after calling the command
10078 @code{ecb-rebuild-methods-buffer} or saving the source-file (if
10079 @code{ecb-auto-update-methods-after-save} is true).
10083 Only if @code{ecb-auto-save-before-etags-methods-rebuild} is switched on
10084 the command @code{ecb-rebuild-methods-buffer} rebuilds the
10085 method-buffer with current source-contents. See description of this
10086 option for an explanation.
10089 Tip: If you want to program your own real. automatic
10090 rescan/reparse/rebuild mechanism for non-semantic-sources you can do:
10092 Adding to @code{after-change-functions} a function F which either runs
10093 itself @code{ecb-rebuild-methods-buffer-for-non-semantic} or which
10094 adds only another function FF to an idle-timer and the function FF
10095 runs @code{ecb-rebuild-methods-buffer-for-non-semantic}. The latter
10096 approach has the advantage that the reparse/rebuild is not performed
10097 immediately after every change but first after Emacs is idle for a
10098 senseful interval (e.g. 4 seconds) after last change. Of course the
10099 function FF has to cancel its own idle-timer at the end, so the next
10100 idle-timer is first started again after the next change (i.e. by
10101 function F which is still contained in @code{after-change-functions}.
10103 @subsection Customizing the display of the tags
10105 For non-semantic-sources ECB uses does no special organizing of tags
10106 in groups and sub-tags but it completely uses the tag-hierarchy the
10107 imenu- and etags-parsers of speedbar return. So the displayed tag
10108 hierarchy can only be customized with some options speedbar offers for
10111 @code{speedbar-tag-hierarchy-method},
10112 @code{speedbar-tag-group-name-minimum-length},
10113 @code{speedbar-tag-split-minimum-length} and
10114 @code{speedbar-tag-regroup-maximum-length}. See the speedbar
10115 documentation for details about these options.
10117 With the option @code{ecb-method-non-semantic-face} you can define the
10118 face used for displaying the tags in the Method-buffer for
10119 non-semantic-sources.
10121 @code{ecb-non-semantic-methods-initial-expand} can be useful too.
10124 @node Hide-show, Window-managers and ECB, Non-semantic sources, Tips and tricks
10125 @section Using hide-show from the methods-buffer-menu
10127 The popup-menu of the Methods-buffer offer two entries for either
10128 hiding or showing the block which is related to the selected tag
10129 (that tag for which the popup-menu was opened):
10132 @item ``Jump to tag and hide block'':
10133 Jumps to the tag and calls @code{hs-hide-block} from the
10134 hideshow-library which is shipped with (X)Emacs. After that the block
10135 is hidden, i.e. only the header-line of that tag (method, variable
10136 etc.) is visible, the rest is hidden behind the ``...''.
10138 @item ``Jump to tag and show block'':
10139 Jumps to the tag and calls @code{hs-show-block}. This shows the related
10140 hidden block if the block was hidden via @code{hs-hide-block} or the
10141 menu-entry ``Jump to tag and hide block'' (s.a.).
10144 For this feature the library @file{hideshow.el} is used which should
10145 normally being included in the (X)Emacs-distribution. If this library
10146 is not loaded into Emacs, ECB does this automatically before the first
10147 call to one of these menu-entries.
10149 IMPORTANT: If in some @code{major-mode} hiding and showing does not
10150 work as you expect it to work then you must probably add an entry for
10151 this @code{major-mode} to the hideshow-variable
10152 @code{hs-special-modes-alist}. See the documentation of this variable
10153 for further details. One example of such a @code{major-mode} is
10154 @code{jde-mode} of the Java Development Environment JDEE; just add an
10155 entry for it like the already contained entries for @code{c++-mode} or
10156 @code{java-mode} and hiding and showing will work for you with JDEE
10159 @node Window-managers and ECB, Tree-buffer styles, Hide-show, Tips and tricks
10160 @section Support of several Emacs-window-managers
10164 @cindex window-manager
10165 There are several window-managers available which offer an easy
10166 interface to jump between different window-configurations within the
10167 same frame. A window configuration is the layout of windows and
10168 associated buffers within a frame. There is always at least one
10169 configuration, the current configuration. You can create new
10170 configurations and cycle through the layouts in either direction.
10171 Window configurations are often named or numbered, and you can jump to
10172 and delete named rsp. numbered configurations.
10174 Without special support by ECB these window-managers would not work in
10175 combination with ECB!
10177 ECB currently supports the following managers:
10181 Written by Barry A. Warsaw @email{bwarsaw@@python.org}, available at
10183 @uref{http://www.python.org/emacs/}
10186 @url{http://www.python.org/emacs/}
10190 Written by Noah Friedman @email{friedman@@splode.com}, available at
10192 @uref{http://www.splode.com/~friedman/software/emacs-lisp/}
10195 @url{http://www.splode.com/~friedman/software/emacs-lisp/}
10199 @strong{IMPORTANT}: With one of these window-managers installed and
10200 active you can run applications like Gnus, VM or BBDB in the same
10201 frame as ECB! Just use different window-configurations (winring.el) or
10202 escreens (escreen.el) for ECB and the other applications. Especially
10203 with winring.el you can give every configuration a descriptive name
10204 like ``ECB'' or ``Gnus''; afterwards you can jump to a
10205 window-configuration by name!
10207 When you go back to the ECB-window-configuration (winring.el) or the
10208 ECB-escreen (escreen.el) with any of the special
10209 window-manager-commands then the state of ECB will be restored exactly
10210 as you have left it when going to another window-configuration rsp.
10211 escreen. This includes the whole splitting state of the edit-area and
10212 the visibilty of the ecb-windows and of the compile-window!
10214 The rest of this section describes how to enable the special
10215 ECB-support for these window-managers and how to use them.
10217 @subsection Enabling of the support
10219 Every support must be enabled explicitly:
10222 Call @code{ecb-winman-winring-enable-support}. This @strong{MUST} be
10223 done @strong{BEFORE} the first call to any winring-command, so also
10224 before calling @code{winring-initialize}!
10227 Call @code{ecb-winman-escreen-enable-support}. This @strong{MUST} be
10228 done @strong{BEFORE} the first call to any escreen-command, so also
10229 before calling @code{escreen-install}!
10232 If a window-manager-support should be enabled autom. after Emacs-start
10233 just put the following into your @file{.emacs}:
10237 (ecb-winman-winring-enable-support)
10238 (winring-initialize)
10240 ;; or - if you like escreen more
10242 (ecb-winman-escreen-enable-support)
10247 @subsection Usage of a window-manager in combination with ECB
10249 After enabling the support of one of the supported window-managers
10250 just go on as described in the commentary or introduction of the
10251 respective library-file(s) of the window-manager. Here is a short
10256 First you have to define how to identify the ECB-window-configuration,
10257 i.e. the configuration with activated ECB. This done with the option
10258 @code{ecb-winman-winring-name}. There is always only one
10259 window-configurations with name @code{ecb-winman-winring-name}!
10261 Then run @code{winring-initialize}. If ECB is active then the
10262 resulting window-configuration is the ECB-window-configuration.
10263 Otherwise you can create the ECB-window-configuration when you first
10264 time call @code{winring-new-configuration} with name equal to
10265 @code{ecb-winman-winring-name}. In general you can run all commands of
10266 the winring-library. If you jump to the ECB-window-configuration then
10267 ECB will be autom. activated and if you leave the
10268 ECB-window-configuration then ECB will autom. deactivated.
10271 First you have to define how to identify the ECB-escreen
10272 i.e. that escreen with activated ECB. This done with the option
10273 @code{ecb-winman-escreen-number}. There is always only one
10274 escreen with number @code{ecb-winman-escreen-number}!
10276 Then run @code{escreen-install} (deactivates ECB if currently
10277 running). After that you can call @code{escreen-create-screen} and
10278 @code{escreen-goto-screen}@footnote{And of course all other
10279 @code{escreen-goto-*} commands!}. These commands autom. activate ECB
10280 if creating or selecting the escreen with number
10281 @code{ecb-escreen-number} (default = 1) and autom. deactivate ECB if
10282 leaving the ECB-escreen.
10285 @subsection Disabling the support
10287 There is normally no need to do this but nevertheless it can be done
10288 by @code{ecb-winman-escreen-disable-support} rsp.
10289 @code{ecb-winman-winring-disable-support}.
10291 @node Tree-buffer styles, Using semanticdb, Window-managers and ECB, Tips and tricks
10292 @section Displaying the trees of the ECB-windows with different styles
10294 ECB offers three different styles for the tree-buffers in the
10295 ECB-windows. Two of the styles are ascii-based and one style uses
10296 images for drawing the tree-structure.
10299 * Style basics:: Basic knowledge about the styles
10300 * Ascii-based styles:: How to customize the ascii-styles
10301 * Tree-buffers with images:: Which images are used for the tree
10302 * Images for Methods-buffer:: Images for the tags in the Methods-buffer
10305 @node Style basics, Ascii-based styles, ,Tree-buffer styles
10306 @subsection Basic knowledge about the styles
10308 There are nine image-names which define the control- and guide-symbols
10309 to draw the tree. Here is the list of the allowed image-names and the
10310 related corresponding ascii-symbols:
10313 @item open (``[-]''):
10314 The control-symbol displayed for an opened tree-node which has several
10315 subnodes. Clicking onto this control closes the node.
10317 @item close (``[+]''):
10318 The control-symbol displayed for a closed tree-node, i.e. an
10319 expandable node with subnodes but all subnodes are hidden. Clicking
10320 onto this control opened the node and displays its subnodes - if
10321 there are any. If it has no subnodes the empty-symbol will be
10324 @item empty (``[x]''):
10325 The symbol displayed for an empty node. An empty node is a
10326 node which could have subnodes but has currently none.
10328 @item leaf (``*''):
10329 The symbol displayed for a node which can not have any subnodes so it
10330 is a ``leaf'' in the tree.
10332 @item guide (`` |''):
10333 The symbol used for drawing vertical ``guide-lines'' for opened nodes.
10334 See the example below.
10336 @item no-guide (`` ''):
10337 Sometimes invisible guide-lines are needed to draw the tree.
10339 @item end-guide (`` `''):
10340 The symbol used for the guide-line of the last subnode of an opened
10343 @item handle (``-''):
10344 The symbol displayed before every subnode. Each handle is connected to
10345 a guide-line - either a normal guide or an end-guide.
10347 @item no-handle (`` ''):
10348 An invisible handle.
10351 A tree will be build-up with these elements like follows:
10355 [-] node-with-subnodes (open)
10356 |-[+] not-empty-subnode1 (guide+handle+close)
10357 |-[x] empty-subnode (guide+handle+empty)
10358 `-[-] not-empty-subnode2 (end-guide+handle+open)
10359 |-* leaf-1 (no-guide+no-handle+guide+handle+leaf)
10360 `-* leaf-2 (no-guide+no-handle+end-guide+handle+leaf)
10364 @node Ascii-based styles, Tree-buffers with images, Style basics, Tree-buffer styles
10365 @subsection How to customize the ascii-styles
10367 The ECB-option @code{ecb-tree-buffer-style} offers two different
10368 styles completely drawn with ascii-controls and -guides.
10370 Ascii-style with guide-lines (value @code{ascii-guides})@footnote{For
10371 a better look&feel of such a tree-buffer ECB displays only the last
10372 subnode of an opened node with a handle!}:
10394 Ascii-style without guide-lines (value @code{ascii-no-guides}) - this
10395 is the style used by ECB <= 1.96:
10417 The tree-layout of both ascii-styles can be affected with the options
10418 @code{ecb-tree-indent} and @code{ecb-tree-expand-symbol-before} (the
10419 examples above have set 4 for the former and true for the latter one).
10420 For the guide-style the face and color of the guide- and
10421 handle-symbols can be customized with the option
10422 @code{ecb-tree-guide-line-face} (default is the equal-named face).
10424 @node Tree-buffers with images, Images for Methods-buffer, Ascii-based styles, Tree-buffer styles
10425 @subsection Which images are used for the tree
10427 Depending on the value of @code{ecb-tree-buffer-style} and the
10428 image-support of (X)Emacs, the tree-buffer try to use images instead
10429 of strings to draw a nice-looking tree.
10431 If images can and should be used then the option
10432 @code{ecb-tree-image-icons-directories} tells ECB where to search for
10433 suitable image-icons for each of the nine image-names (see above). An
10434 image is used for displaying a control with name ``XXX'' if one of the
10435 directories of @code{ecb-tree-image-icons-directories} contains an
10436 image-file with basename ``ecb-XXX'' and an extension which is
10437 supported by (X)Emacs. Currently supported extensions are ``.xpm'',
10438 ``.png'', ``.gif'', ``.jpeg'', .''jpg'' and ``.xbm''.
10440 Example: To display the control with name ``open'' with a suitable
10441 image then one of the directories of
10442 @code{ecb-tree-image-icons-directories} must contain a file with name
10443 ``ecb-open.xpm'' or ``ecb-open.png'' etc. See the description of this
10444 option to get all important details how and in which sequence ECB
10445 searches the directories of @code{ecb-tree-image-icons-directories}.
10447 ECB comes with predefined default-images usable for every tree-buffer
10448 and special images for the Directories- and the Methods-tree-buffer.
10449 They are defined in several different heights - so for the most
10450 senseful font-heights of a tree-buffer a fitting image-size should be
10451 available. The shipped images reside either in the subdirectory
10452 "ecb-images" of the ECB-installation or - if ECB is installed as
10453 regular XEmacs-package - in the ECB-etc data-directory (the directory
10454 returned by evaluating (locate-data-directory "ecb"). If you do not
10455 want to change the images then you normally have nothing to do because
10456 the default value of @code{ecb-tree-image-icons-directories} points
10457 already to the correct image-directories.
10459 @subsubsection A special note for XEmacs
10461 At least XEmacs 21.14 (but probably previous versions too) has a bug
10462 in its display-engine which prevents adjacent images to be displayed
10463 correctly. The effect is, that in a row of two or more adjacent images
10464 (e.g. end-guide+handle+open - see the tree-example above) always all
10465 images are masked by the last one, means only the last one is visible.
10466 If at least one normal character (e.g. a space) is placed between two
10467 images then the images are displayed correctly. Therefore ECB has
10468 implemented the following work-around to get best possible results
10469 with XEmacs: open-, close-, empty-, leaf-, guide-, end-guide- and
10470 no-guide-images are displayed with images and the handle- and the
10471 no-handle-images are displayed with the corresponding ascii-symbols
10472 (which is ``-'' rsp. `` ''). The face (the color) of the handle-symbol
10473 is customizable via the option @code{ecb-tree-guide-line-face}.
10475 This bug is already reported to the XEmacs-team. If your XEmacs has
10476 fixed this bug then add the following to your @file{.emacs}-file (or
10477 whereever your emacs-setup is located):
10480 (setq tree-buffer-enable-xemacs-image-bug-hack nil)
10483 Then ECB uses images without any special work-around with XEmacs too.
10484 Just try it - if the tree-buffers look ugly then the XEmacs-bug is
10485 probably not fixed correctly.
10487 @node Images for Methods-buffer, ,Tree-buffers with images, Tree-buffer styles
10488 @subsection Special images for the Methods-buffer
10490 ECB can display all the semantic-tags in the Method-buffer with
10491 special icons for methods, variables and classes - each of them with a
10492 different icon dependend of the protection of the tag. This feature
10493 can be disabled/enabled via the option
10494 @code{ecb-display-image-icons-for-semantic-tags}. All the special
10495 images are located in that directory where the option
10496 @code{ecb-tree-image-icons-directories} point to for methods.
10498 @node Using semanticdb, , Tree-buffer styles, Tips and tricks
10499 @section Using semanticdb to jump to type-tags defined in other files
10501 In OO-languages like CLOS, eieio and C++ there can be type-tags in the
10502 method-buffer which are somehow virtual because there is no definition
10503 in the current source-file. But such a virtual type collects all its
10504 outside defined members like methods in C++ which are defined in the
10505 @file{*.cc} file whereas the class-definition is defined in the
10506 associated header-file. ECB uses semanticdb to open the definition-file
10507 of such a tag and to jump to the definition of this tag. Same for
10508 parent-tags in the methods-buffer. This feature can only work
10509 correctly if semanticdb is well configured!
10511 Here is a C++-example:
10513 This class is defined in a file @file{ParentClass.h}:
10525 This class is defined in a file @file{ClassWithExternals.h}
10529 #include "ParentClass.h"
10531 class ClassWithExternals : public ParentClass
10537 ClassWithExternals();
10538 ~ClassWithExternals();
10543 Both the constructor and the desctructor of the class
10544 ``ClassWithExternals'' are defined in a file
10545 @file{ClassWithExternals.cc}:
10551 ClassWithExternals::ClassWithExternals(int i,
10559 ClassWithExternals::~ClassWithExternals()
10566 ECB displays the contents of @file{ClassWithExternals.cc} in its methods-buffer like
10573 [-] ClassWithExternals
10574 | +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals
10575 `- +~ClassWithExternals ():void
10579 Both the constructor and the desctructor of the class
10580 ``ClassWithExternals'' are grouped under their class-type. ECB now
10581 uses semanticdb to jump to the definition of class
10582 ``ClassWithExternals'' when you click onto the type-node
10583 ``ClassWithExternals'' in the methods-buffer.
10585 The contents of @file{ClassWithExternals.h} are displayed like
10592 [-] ClassWithExternals:class
10597 | +ClassWithExternals ():ClassWithExternals
10598 | +~ClassWithExternals ():void
10603 ECB uses semanticdb to jump to the definition of the class
10604 ``ParentClass'' when you click onto the node ``ParentClass''.
10606 To enable this feature @code{global-semanticdb-minor-mode} must be
10607 enabled and semanticdb must be correctly configured. This means
10608 mainly that the option @code{semanticdb-project-roots} must be setup
10609 well. See the manual of semanticdb for further informations about
10612 @node Elisp programming, Conflicts and bugs, Tips and tricks, Top
10613 @chapter Entry points for Elisp programmers
10615 This chapter describes how ECB can be used/programmed/driven by an
10616 Elisp-program. This contains:
10619 * List of variables:: Which variables an Elisp-program can use
10620 * List of hooks:: All available hooks
10621 * tree-buffer:: Some words to the tree-buffer-library
10622 * Adviced functions:: How to deal with the adviced functions
10623 * The layout-engine:: Programming new layouts and special windows
10626 @node List of variables, List of hooks, Elisp programming, Elisp programming
10627 @section Variables for Elisp-programs
10629 Variables an Elisp-program can use beyond those ones mentioned in
10630 @ref{The layout-engine}:
10633 @item @code{ecb-source-path-functions}
10636 Look at the documentation of these variables to get a description.
10638 @node List of hooks, tree-buffer, List of variables, Elisp programming
10639 @section Available hooks of ECB
10641 The following hooks are available:
10645 @item @code{ecb-activate-before-new-frame-created-hook}
10646 @item @code{ecb-activate-before-layout-draw-hook}
10647 @item @code{ecb-activate-hook}
10648 @item @code{ecb-after-directory-change-hook}
10649 @item @code{ecb-before-activate-hook}
10650 @item @code{ecb-before-deactivate-hook}
10651 @item @code{ecb-common-tree-buffer-after-create-hook}
10652 @item @code{ecb-current-buffer-sync-hook}
10653 @item @code{ecb-deactivate-hook}
10654 @item @code{ecb-directories-buffer-after-create-hook}
10655 @item @code{ecb-hide-ecb-windows-after-hook}
10656 @item @code{ecb-hide-ecb-windows-before-hook}
10657 @item @code{ecb-history-buffer-after-create-hook}
10658 @item @code{ecb-methods-buffer-after-create-hook}
10659 @item @code{ecb-redraw-layout-after-hook}
10660 @item @code{ecb-redraw-layout-before-hook}
10661 @item @code{ecb-show-ecb-windows-after-hook}
10662 @item @code{ecb-show-ecb-windows-before-hook}
10663 @item @code{ecb-sources-buffer-after-create-hook}
10666 Look at the documentation of these hooks to get a detailed description.
10668 @node tree-buffer, Adviced functions, List of hooks, Elisp programming
10669 @section The library tree-buffer.el
10671 The library tree-buffer.el is ECB independent and can be used for
10672 other applications too. But such an application is not allowed to use
10673 any of the variables of tree-buffer.el especially not the variable
10674 @strong{tree-buffers}!
10676 @code{tree-buffers}: Only for internal use. It contains all
10677 tree-buffers of current Emacs-instance, means @strong{all}
10678 tree-buffers of @strong{all} applications which uses currently
10679 tree-buffers. Every application must store its own collection of
10680 tree-buffers in an own variable! For example: ECB stores its
10681 tree-buffer set in @code{ecb-tree-buffers}!
10683 An application may only use the methods tree-buffer.el provides but no
10684 internal variables!
10686 @node Adviced functions, The layout-engine, tree-buffer, Elisp programming
10687 @section How to deal with the adviced window-functions
10689 ECB offers for packages which work during activated ECB three macros
10690 for easy temporally@footnote{I.e. regardless of the settings in
10691 @code{ecb-advice-window-functions}!} using all original-functions, all
10692 adviced functions or only some adviced functions:
10695 @item @code{ecb-with-original-functions}
10696 @item @code{ecb-with-adviced-functions}
10697 @item @code{ecb-with-some-adviced-functions}
10700 For a detailed explanation of each macro read the documentation with
10701 @code{describe-function}!
10703 @node The layout-engine, , Adviced functions, Elisp programming
10704 @section How to program new layouts and new special windows
10706 There are two aspects concerning this topic:
10710 Programming a new layout which contains several special ECB-windows
10711 like directories, sources, methods, history or other special windows
10712 and arranging them in a new outline.
10715 Creating complete new special windows (e.g. a local-variable window
10716 for a graphical debugger like JDEbug of JDEE), adding them to a layout
10717 and synchronizing them with the current active edit-window.
10720 The former one covers merely the layout-programming aspect which is
10721 explained in the first subsection of this chapter whereas the latter
10722 one covers all aspects of creating new special windows and what is
10723 necessary to synchronize it with the current active edit-window of
10724 ECB. This is explained in the second subsection which will refers to
10725 the first subsection.
10728 * Programming a new layout:: How to program a new layout
10729 * Programming special windows:: Aspects of programming special windows
10730 * Possible layout-outlines:: The wide range of possible layouts
10731 * The layout-engine API:: The complete layout-engine API
10734 @node Programming a new layout, Programming special windows, The layout-engine, The layout-engine
10735 @subsection How to program a new layout
10737 If you just want creating a new layout with the standard ECB-windows
10738 like directories, sources, methods, history and speedbar it's is
10739 strongly recommended to define the new layout interactively with the
10740 command @code{ecb-create-new-layout} (@pxref{Creating a new
10743 If you want creating a new layout and if this layout should contain
10744 other special windows than the standard ECB-windows then it's still
10745 recommended to define this layout interactively with
10746 @code{ecb-create-new-layout} and using the option to give the created
10747 windows user-defined types. For every user defined type you have then
10748 just to program the necessary buffer-set function. For all the details
10749 see @ref{Creating a new ECB-layout}.
10751 But if you do not like the interactive way (because you are tough and
10752 brave) but you want programming the new layout with Elisp then use the
10753 macro @code{ecb-layout-define} (the following definition has stripped
10754 the prefix ``ecb-'' for better indexing this manual):
10756 @defmac layout-define name type &rest create-code
10757 Creates a new ECB-layout with name @var{NAME}. @var{TYPE} is the type
10758 of the new layout and is literal, i.e. not evaluated. It can be left,
10759 right, top or left-right. @var{DOC} is the docstring for the new
10760 layout-function ``ecb-layout-function-<name>''. @var{CREATE-CODE} is
10761 all the lisp code which is necessary to define the
10762 ECB-windows/buffers. This macro adds the layout with @var{NAME} and
10763 @var{TYPE}to the internal variable @code{ecb-available-layouts}.
10765 Preconditions for @var{CREATE-CODE}:
10768 Current frame is splitted at least in one edit-window and the
10769 ``column'' (for layout types left, right and left-right) rsp. ``row''
10770 (for a top layout) for the special ECB-windows/buffers. The width of
10771 the ``column'' rsp. the height of the ``row'' is always defined with
10772 the option @code{ecb-windows-width} rsp. @code{ecb-windows-height}.
10773 Depending on the value of the option @code{ecb-compile-window-height}
10774 there is also a compile window at the bottom of the frame which is
10775 stored in @code{ecb-compile-window}.
10778 All windows are not dedicated.
10781 Neither the edit-window nor the compile-window (if there is one) are
10782 selected for types left, right and top. For type left-right the left
10783 column-window is selected
10786 All ECB-advices for the functions in
10787 @code{ecb-advice-window-functions} are disabled!
10790 Things @var{CREATE-CODE} has to do:
10793 Splitting the ECB-tree-windows-column(s)/row (s.a.) in all the
10794 ECB-windows the layout should contain (directories, sources, methods
10795 and history). The split must not be done with other functions than
10796 @code{ecb-split-hor} and @code{ecb-split-ver}! It is recommended not to
10797 to use a ``hard'' number of split-lines or -rows but using fractions
10798 between -0.9 and +0.9! Tip: It is recommended to spilt from right to
10799 left and from bottom to top or with other words: First create the
10800 right-most and bottom-most special windows!
10803 Making each special ECB-window a dedicated window. This can be done with
10804 one of the following functions:
10806 @item @code{ecb-set-directories-buffer}
10807 @item @code{ecb-set-sources-buffer}
10808 @item @code{ecb-set-methods-buffer}
10809 @item @code{ecb-set-history-buffer}
10810 @item @code{ecb-set-speedbar-buffer}
10812 Each layout can only contain one of each tree-buffer-type!
10814 In addition to these functions there is a general macro
10815 @code{ecb-with-dedicated-window}. This macro performs any arbitrary
10816 code in current window and makes the window autom. dedicated at the
10817 end. This can be used by third party packages like JDEE to create
10818 arbitrary ECB-windows besides the standard tree-windows.
10820 To make a special ECB-window a dedicated window either one of the five
10821 functions above must be used or a function(!) which calls in turn the
10822 macro @code{ecb-with-dedicated-window}. See the documentation of this
10823 macro how to use it!
10825 Such a function is called a ``dedicated setter'' and must(!) use
10826 @code{ecb-with-dedicated-window} to make the window dedicated!
10829 Every(!) special ECB-window must be dedicated as described in 2.
10832 @var{CREATE-CODE} must work correctly regardless if there is already a
10833 compile-window (stored in @code{ecb-compile-window}) or not
10834 (@code{ecb-compile-window} is nil).
10837 Things @var{CREATE-CODE} can do or can use:
10840 The value of @code{ecb-compile-window} which contains the compile-window (if
10841 there is one). Using the values of @code{ecb-compile-window-height},
10842 @code{ecb-windows-width}, @code{ecb-windows-height}.
10845 Things @var{CREATE-CODE} must NOT do:
10847 @item Splitting the edit-window
10848 @item Creating a compile-window
10850 Deleting the edit-window, the compile-window (if there is any) or the
10851 ECB-windows-column(s)/row (see Precondition 1.)
10853 Referring to the value of @code{ecb-edit-window} because this is always nil
10854 during @var{CREATE-CODE}.
10857 Postconditions for @var{CREATE-CODE}:
10860 The edit-window must be the selected window and must not be dedicated
10861 and not be splitted.
10864 Every window besides the edit-window \(and the compile-window) must be
10865 a dedicated window \(e.g. a ECB-tree-window).
10869 Use this macro to program new layouts within your @file{.emacs} or any
10870 other file which is loaded into your Emacs. After loading the file(s)
10871 with all the new layout-definitions you can use it by customizing the
10872 option @code{ecb-layout-name} to the appropriate name or with the
10873 command @code{ecb-change-layout}.
10875 With the function @code{ecb-layout-undefine} you can remove a layout
10876 from the list of available layouts:
10878 @defun layout-undefine name
10879 Unbind ecb-layout-function-<NAME> and
10880 ecb-delete-window-ecb-windows-<NAME> and remove @code{NAME} from
10881 @code{ecb-available-layouts}.
10884 Here is an example for a new layout programmed with
10885 @code{ecb-layout-define}:
10889 (ecb-layout-define "my-own-layout" left nil
10890 ;; The frame is already splitted side-by-side and point stays in the
10891 ;; left window (= the ECB-tree-window-column)
10893 ;; Here is the creation code for the new layout
10895 ;; 1. Defining the current window/buffer as ECB-methods buffer
10896 (ecb-set-methods-buffer)
10897 ;; 2. Splitting the ECB-tree-windows-column in two windows
10898 (ecb-split-ver 0.75 t)
10899 ;; 3. Go to the second window
10901 ;; 4. Defining the current window/buffer as ECB-history buffer
10902 (ecb-set-history-buffer)
10903 ;; 5. Make the ECB-edit-window current (see Postcondition above)
10904 (select-window (next-window)))
10908 This layout definition defines a layout with name ``my-own-layout''
10913 -------------------------------------------------------
10927 -------------------------------------------------------
10931 -------------------------------------------------------
10935 @node Programming special windows, Possible layout-outlines, Programming a new layout, The layout-engine
10936 @subsection All aspects of programming special windows
10938 ECB offers a flexible programmable layout-engine for other packages to
10939 display their own contents and informations in special ECB-windows. An
10940 example could be a graphical debugger which offers a special window for
10941 displaying local variables and another special window for messages
10942 from the debugger-process (like JDEbug of JDEE@footnote{JDEE is
10945 @uref{http://jdee.sunsite.dk/}
10948 @url{http://jdee.sunsite.dk/}
10952 This section explains all aspects of programming new special windows,
10953 adding them to a new layout and synchronizing them with edit-window of
10954 ECB. This can be done best with an easy example which nevertheless
10955 covers all necessary aspects to be a good example and skeleton for
10956 complex tools (like a graphical debugger) which want to use the
10957 layout-engine of ECB do display their own information.
10959 Here comes the example:
10961 @subsubsection The outline of the example layout:
10965 -------------------------------------------------------
10966 |Bufferinfo for <filename>: |[prior] |
10967 |Type: file |[next] |
10969 |Modes: rw-rw-rw- | |
10970 |-----------------------------------------------------|
10980 -------------------------------------------------------
10982 | compilation-window |
10984 -------------------------------------------------------
10988 @subsubsection The description of the layout-contents
10990 The top-left window always displays informations about the current
10991 buffer in the selected edit-window. This window demonstrates how
10992 autom. synchronizing a special window/buffer of a layout with current
10995 The top-right window contains an read-only ``action-buffer'' and
10996 offers two buttons which can be used with the middle mouse-button to
10997 scroll the edit-window. This is not very senseful but it demonstrates
10998 how to control the edit-window with actions performed in a special
10999 window/buffer of a layout.
11001 (If you have not set a compilation-window in
11002 @code{ecb-compile-window-height} then the layout contains no durable
11003 compilation window and the other windows get a little more place).
11005 @subsubsection The example code
11007 Now let have us a look at the several parts of the Elisp-program
11008 needed to program this new example layout. ECB contains a library
11009 @file{ecb-examples.el} which contains the full working code of this
11010 example. To test this example and to play with it you can load this
11011 library into Emacs (with @code{load-library} for example) and then
11012 calling @code{ecb-change-layout} (bound to @kbd{C-c . lc}) and
11013 inserting ``example-layout1'' as layout-name. An alternative is
11014 calling @code{ecb-examples-activate} and
11015 @code{ecb-examples-deactivate}. For details see file
11016 @file{ecb-examples.el}.
11018 The following steps only contain code-skeletons to demonstrate the
11019 principle. The full working code is available in
11020 @file{ecb-examples.el}.
11022 @subsubsection The bufferinfo buffer of the example
11024 The name of the bufferinfo buffer:
11027 (defconst ecb-examples-bufferinfo-buffer-name " *ECB buffer info*")
11030 Two helper functions for displaying infos in a special buffer:
11035 (defun ecb-examples-print-file-attributes (buffer filename)
11036 (ecb-with-readonly-buffer buffer
11038 (insert (format "Bufferinfo for %s:\n\n" filename))
11039 ;; insert with the function `file-attributes' some
11040 ;; informations about FILENAME.
11043 (defun ecb-examples-print-non-filebuffer (buffer buffer-name)
11044 (ecb-with-readonly-buffer buffer
11046 ;; analogous to `ecb-examples-print-file-attributes'
11051 The main synchronizing function added to
11052 @code{ecb-current-buffer-sync-hook} for autom. evaluation by
11053 @code{ecb-current-buffer-sync} which runs dependent on the values of
11054 @code{ecb-window-sync} and @code{ecb-window-sync-delay}. This function
11055 synchronizes the bufferinfo buffer with the current buffer of the
11056 edit-window if that buffer has changed.
11060 (defun ecb-examples-bufferinfo-sync ()
11061 (ecb-do-if-buffer-visible-in-ecb-frame
11062 'ecb-examples-bufferinfo-buffer-name
11064 ;; here we can be sure that the buffer with name
11065 ;; `ecb-examples-bufferinfo-buffer-name' is displayed in a
11066 ;; window of `ecb-frame'
11068 ;; The macro `ecb-do-if-buffer-visible-in-ecb-frame' locally
11069 ;; binds the variables visible-buffer and visible-window!! See
11070 ;; documentation of this macro!
11072 (let ((filename (buffer-file-name (current-buffer))))
11074 (if (and filename (file-readable-p filename))
11076 ;; real filebuffers
11077 ;; here we could add a smarter mechanism;
11078 ;; see ecb-examples.el
11079 (ecb-examples-print-file-attributes visible-buffer
11082 ;; non file buffers like help-buffers etc...
11083 (setq ecb-examples-bufferinfo-last-file nil)
11084 (ecb-examples-print-non-filebuffer visible-buffer
11091 The function which makes the bufferinfo-buffer dedicated to a window.
11095 (defun ecb-examples-set-bufferinfo-buffer ()
11096 (ecb-with-dedicated-window
11097 ecb-examples-bufferinfo-buffer-name
11098 'ecb-examples-set-bufferinfo-buffer
11099 (switch-to-buffer (get-buffer-create
11100 ecb-examples-bufferinfo-buffer-name))
11101 (setq buffer-read-only t)))
11106 This is all what we need for the special bufferinfo buffer. We have
11107 demonstrated already three of the important functions/macros of the
11108 layout-engine API of ECB: @code{ecb-with-readonly-buffer},
11109 @code{ecb-do-if-buffer-visible-in-ecb-frame} and
11110 @code{ecb-with-dedicated-window} (@pxref{The layout-engine
11111 API}. Especially the second macro is strongly recommended for
11112 programming good synchronizing functions which do not waste CPU!
11114 @subsubsection The action buffer of the example
11116 The name of the action-buffer:
11119 (defconst ecb-examples-action-buffer-name " *ECB action buffer*")
11122 Two helper functions for creating a readonly action-buffer with a
11123 special local key-map for the middle-mouse-button and two buttons
11124 [prior] and [next]:
11128 (defun ecb-examples-insert-text-in-action-buffer (text)
11131 (put-text-property p (+ p (length text)) 'mouse-face
11134 (defun ecb-examples-action-buffer-create ()
11136 (if (get-buffer ecb-examples-action-buffer-name)
11137 (get-buffer ecb-examples-action-buffer-name)
11139 (set-buffer (get-buffer-create
11140 ecb-examples-action-buffer-name))
11142 ;; we setup a local key-map and bind middle-mouse-button
11143 ;; see ecb-examples.el for the full code
11145 ;; insert the action buttons [prior] and [next] and
11146 ;; make it read-only
11148 (ecb-with-readonly-buffer (current-buffer)
11150 (ecb-examples-insert-text-in-action-buffer "[prior]")
11151 ;; analogous for the [next] button
11154 (current-buffer))))
11158 The function which performs the actions in the action-buffer if
11159 clicked with the middle-mouse button onto a button [next] or [prior].
11163 (defun ecb-examples-action-buffer-clicked (e)
11165 (mouse-set-point e)
11166 (let ((line (buffer-substring (ecb-line-beginning-pos)
11167 (ecb-line-end-pos))))
11168 (cond ((string-match "prior" line)
11169 (ecb-select-edit-window)
11170 (call-interactively 'scroll-down))
11171 ((string-match "next" line)
11172 ;; analogous for [next]
11177 The function which makes the action-buffer dedicated to a window.
11181 (defun ecb-examples-set-action-buffer ()
11182 (let ((buf-name (buffer-name (ecb-examples-action-buffer-create))))
11183 (ecb-with-dedicated-window buf-name 'ecb-examples-set-action-buffer
11184 (switch-to-buffer (buffer-name
11185 (ecb-examples-action-buffer-create))))))
11189 We do not need more code for the action buffer. All of the code is
11190 standard emacs-lisp which would also needed if used without ECB.
11192 @subsubsection Adding the bufferinfo- and action-buffer to a new layout
11194 Now we add the bufferinfo- and the action-buffer to a new layout of
11195 type top with name ``example-layout1'':
11199 (ecb-layout-define "example-layout1" top
11201 ;; dedicating the bufferinfo window to the bufferinfo-buffer
11202 (ecb-examples-set-bufferinfo-buffer)
11204 ;; creating the action-window
11205 (ecb-split-hor 0.75)
11207 ;; dedicate the action window to the action-buffer
11208 (ecb-examples-set-action-buffer)
11210 ;; select the edit-window
11211 (select-window (next-window)))
11215 This all what we need to define the new layout. See @ref{Programming a
11216 new layout} for more details of the pure layout-programming task.
11218 @subsubsection Synchronizing the bufferinfo-buffer automatically
11220 The last thing we have to do is to synchronize the bufferinfo-buffer
11221 with current edit-window. We do this by adding
11222 @code{ecb-examples-bufferinfo-sync} to the hook
11223 @code{ecb-current-buffer-sync-hook'} (The file @file{ecb-examples.el}
11224 shows a smarter mechanism for (de)activating the new layout and the
11225 synchronization but this works also very well).
11228 (add-hook 'ecb-current-buffer-sync-hook 'ecb-examples-bufferinfo-sync)
11231 @subsubsection Activating and deactivating new layouts
11233 Because a set of new special windows integrated in a new layout is
11234 often just the GUI of a complete tool (like a graphical debugger) we
11235 demonstrate here the complete activation and deactivation of such a
11236 tool or at least of the tool-GUI. We decide that the GUI of our
11237 example ``tool'' needs a compile-window with height 5 lines and the
11238 height of the special windows ``row'' on top should be exactly 6 lines
11239 (normally width and height of the special windows should be a fraction
11240 of the frame, but here we use 6 lines@footnote{You can change the code
11241 in the file @file{ecb-examples.el} to use a frame-fraction of 0.2
11242 instead of 6 hard lines, just try it!}
11244 Here comes the (de)activation code.
11246 The code for saving and restoring the state before activation (the
11247 full code is available in @file{ecb-examples.el}:
11251 (defun ecb-examples-preactivation-state(action)
11252 (cond ((equal action 'save)
11253 ;; code for saving the state
11255 ((equal action 'restore)
11256 ;; code for restoring the state
11261 The following function activates the GUI of our example tool:
11265 (defun ecb-examples-activate ()
11268 ;; activating the synchronization of the bufferinfo-window
11269 (add-hook 'ecb-current-buffer-sync-hook
11270 'ecb-examples-bufferinfo-sync)
11272 ;; saving the state
11273 (ecb-examples-preactivation-state 'save)
11275 ;; switch to our preferred layout
11276 (setq ecb-windows-height 6)
11277 (setq ecb-compile-window-height 5)
11278 (ecb-layout-switch "example-layout1"))
11282 This function deactivates the GUI of our example-tool and restores the
11283 state as before activation:
11287 (defun ecb-examples-deactivate ()
11290 (remove-hook 'ecb-current-buffer-sync-hook
11291 'ecb-examples-bufferinfo-sync)
11292 (ecb-examples-preactivation-state 'restore)
11293 (ecb-layout-switch ecb-layout-name))
11298 Now we have all code for the new layout and the new layout-buffers.
11299 The example is ready for use; just load @file{ecb-examples.el} (s.a.).
11301 @node Possible layout-outlines, The layout-engine API, Programming special windows, The layout-engine
11302 @subsection The wide range of possible layout-outlines
11304 In the two previous sections @ref{Programming a new layout} and
11305 @ref{Programming special windows} we have explained in detail how to
11306 program new layouts and how to program new special windows/buffers and
11307 adding them to a new layout.
11309 The intention of this section is to be a summary what are the real
11310 restrictions for a new layout-outline programmed with
11311 @code{ecb-layout-define}. This is necessary because until now we just
11312 programmed ``obvious'' layouts, means layout which are in principle
11313 very similar to the standard ones which means one big edit-window and
11314 some special windows ``around'' this edit-window. This section will
11315 show you that a layout can have also very different outlines.
11317 OK, here are the real restrictions and conditions for a layout
11318 programmed with @code{ecb-layout-define}:
11321 It must have exactly one edit-window regardless of its size. The user
11322 of this layout can later split this edit-window in as many
11323 edit-windows as he like.
11326 All other windows created within the @var{CREATE-CODE} body of
11327 @code{ecb-layout-define} (@pxref{Programming a new layout}) must be
11328 dedicated to their buffers.
11331 All the dedicated windows must (exclusive!) either reside on the left,
11332 right, top or left-and-right side of the edit-window. This will be
11333 defined with the @var{TYPE}-argument of @code{ecb-layout-define}
11334 (@pxref{Programming a new layout}).
11337 You see, there are only three restrictions/conditions. These and only
11338 these must be fulfilled at layout-programming.
11340 Demonstrating what this really means and how flexible the
11341 layout-engine of ECB really is, can be done best with some
11342 ``pathological'' layout-outlines. All the following are correct
11343 layouts (working code is added below each layout):
11345 The following is a top layout with three vertical layered special
11350 ------------------------------------------------------------------
11352 | Upper special window |
11354 |----------------------------------------------------------------|
11356 | Middle special window |
11358 |----------------------------------------------------------------|
11360 | Lower special window |
11362 |================================================================|
11365 | (can be splitted by the user in several edit-windows) |
11366 ------------------------------------------------------------------
11368 | Compilation-window (optional) |
11370 ------------------------------------------------------------------
11374 Here is the code for that top layout (all buffers are dummy-buffers):
11379 ;; The "dedicated setter" functions:
11381 (defun ecb-set-usw-buffer ()
11382 (ecb-with-dedicated-window
11383 "Upper special window"
11384 'ecb-set-usw-buffer
11385 (switch-to-buffer (get-buffer-create "Upper special window"))))
11387 (defun ecb-set-msw-buffer ()
11388 (ecb-with-dedicated-window
11389 "Middle special window"
11390 'ecb-set-msw-buffer
11391 (switch-to-buffer (get-buffer-create "Middle special window"))))
11393 (defun ecb-set-lsw-buffer ()
11394 (ecb-with-dedicated-window
11395 "Lower special window"
11396 'ecb-set-lsw-buffer
11397 (switch-to-buffer (get-buffer-create "Lower special window"))))
11399 ;; The layout itself:
11401 (ecb-layout-define "example-layout3" top
11404 ;; here we have an edit-window and above one top window which we can
11405 ;; now split in several other windows. Dependent on the value of
11406 ;; `ecb-compile-window-height' we have also a compile-window at the
11409 (ecb-set-usw-buffer)
11410 (ecb-split-ver 0.33)
11411 (ecb-set-msw-buffer)
11412 (ecb-split-ver 0.5)
11413 (ecb-set-lsw-buffer)
11415 ;; select the edit-window.
11416 (select-window (next-window)))
11421 The following is a left-right layout which has six special windows in
11422 the left-''column'' and one big special window in the
11423 right-''column''. For left-right layouts the left-''column'' and the
11424 right-''column'' have always the same width.
11428 ------------------------------------------------------------------
11430 | Left1 | Left5 | | |
11432 |-------------| | | |
11436 | Left2| Left3|-------| Edit-area | Right1 |
11437 | | | | (can be splitted | |
11438 | | | | in several edit- | |
11439 | | | | windows) | |
11440 |-------------| | | |
11442 | Left4 | Left6 | | |
11444 ------------------------------------------------------------------
11446 | Compilation-window (optional) |
11448 ------------------------------------------------------------------
11452 Here is the code for that left-right layout, again with dummy-buffers
11453 (depending to your screen-resolution you will need a quite big value
11454 for @code{ecb-windows-width}, e.g. 0.4):
11456 Here is one of the ``dedicated setter'' functions@footnote{The
11457 ``dedicated setter functions'' for all these ecb-windows/buffers are
11458 not explicitly described - they look all like
11459 @code{ecb-set-left1-buffer}
11460 - of course with different buffer-names!}:
11464 (defun ecb-set-left1-buffer ()
11465 (ecb-with-dedicated-window
11467 'ecb-set-left1-buffer
11468 (switch-to-buffer (get-buffer-create "Left1"))))
11472 Here is the layout-definition itself:
11476 (ecb-layout-define "example-layout2" left-right
11479 ;; here we have an edit-window and left and right two windows each
11480 ;; with width `ecb-windows-width'. Dependent to the value of
11481 ;; `ecb-compile-window-height' we have also a compile-window at the
11484 (ecb-set-left1-buffer)
11485 (ecb-split-hor 0.66 t)
11486 (ecb-split-ver 0.75)
11487 (ecb-set-left4-buffer)
11488 (select-window (previous-window (selected-window) 0))
11489 (ecb-split-ver 0.25 nil t)
11490 (ecb-set-left2-buffer)
11491 (ecb-split-hor 0.5)
11492 (ecb-set-left3-buffer)
11493 (select-window (next-window (next-window)))
11494 (ecb-set-left5-buffer)
11495 (ecb-split-ver 0.5)
11496 (ecb-set-left6-buffer)
11497 (select-window (next-window (next-window)))
11498 (ecb-set-right1-buffer))
11500 ;; select the edit-window
11501 (select-window (previous-window (selected-window) 0)))
11505 Especially the last example should demonstrate that even very
11506 complicated layouts are easy to program with @code{ecb-layout-define}.
11507 If such layouts are senseful is another topic ;-)
11509 @node The layout-engine API, , Possible layout-outlines, The layout-engine
11510 @subsection The complete layout-engine API of ECB
11512 This section lists all functions, macros, variables and user-options
11513 the layout-engine API of ECB offers foreign packages. Call
11514 @code{describe-function} rsp. @code{describe-variable} to get a
11515 detailed description.
11517 Functions for programming with layouts and special ecb-windows:
11519 @item ecb-available-layouts-member-p
11520 @item ecb-canonical-ecb-windows-list
11521 @item ecb-canonical-edit-windows-list
11522 @item ecb-compile-window-live-p
11523 @item ecb-compile-window-state
11524 @item ecb-do-if-buffer-visible-in-ecb-frame
11525 @item ecb-get-current-visible-ecb-buffers
11526 @item ecb-layout-define
11527 @item ecb-layout-switch
11528 @item ecb-layout-undefine
11529 @item ecb-point-in-compile-window
11530 @item ecb-point-in-ecb-window
11531 @item ecb-point-in-edit-window
11532 @item ecb-select-edit-window
11533 @item ecb-split-hor
11534 @item ecb-split-ver
11535 @item ecb-where-is-point
11536 @item ecb-with-dedicated-window
11539 Utility functions/macros:
11541 @item ecb-enlarge-window
11542 @item ecb-fix-filename
11543 @item ecb-window-live-p
11544 @item ecb-with-readonly-buffer
11547 Some other maybe useful functions/macros:
11549 @item ecb-with-adviced-functions
11550 @item ecb-with-original-functions
11551 @item ecb-with-some-adviced-functions
11554 Some useful @strong{READONLY} variables:
11556 @item ecb-compile-window
11557 @item ecb-last-edit-window-with-point
11558 @item ecb-last-source-buffer
11561 @strong{Caution}: DO NOT USE THE VARIABLE @code{ecb-edit-window} IN
11564 User-options and hooks related to the layout-engine API:
11566 @item ecb-current-buffer-sync-hook
11567 @item ecb-hide-ecb-windows-after-hook
11568 @item ecb-hide-ecb-windows-before-hook
11569 @item ecb-redraw-layout-after-hook
11570 @item ecb-redraw-layout-before-hook
11571 @item ecb-show-ecb-windows-after-hook
11572 @item ecb-show-ecb-windows-before-hook
11573 @item ecb-windows-height
11574 @item ecb-windows-width
11575 @item ecb-compile-window-height
11578 @node Conflicts and bugs, FAQ, Elisp programming, Top
11579 @chapter Conflicts and bugs of ECB
11581 This chapter describes what to do when there are conflicts with other
11582 packages and also the known (and currently unfixed) bugs of ECB. If
11583 possible (and in most cases it is possible ;-) then a practicable
11584 solution or workaround is described.
11587 * Conflicts:: Conflicts with other packages
11588 * Bugs:: Known bugs
11591 @node Conflicts, Bugs, Conflicts and bugs, Conflicts and bugs
11592 @section Conflicts with other packages
11594 This chapter contains a list of already known conflict between ECB and
11595 other packages and how to solve them - in most cases ECB already
11596 contains a suitable workaround.
11598 That is followed by a general recipe what you can do when you have
11599 detected a conflict between ECB and a package is not listed in the
11600 know-conflicts-section.
11602 @subsection Proved workarounds or recommendations for other packages
11604 Here is a list of packages which are proved to work properly with ECB
11605 and if not (i.e. there are conflicts) then helpful
11606 solutions/hints/workarounds are offered:
11608 @subsubsection Package avoid.el
11610 @cindex avoid package
11611 With GNU Emacs 20.X ECB must deactivate @code{mouse-avoidance-mode} if the
11612 option @code{ecb-show-node-info-in-minibuffer} activates for at least one
11613 ECB tree-buffer 'if-too-long or 'always. This is done automatically
11614 but only as long ECB is activated.
11616 @subsubsection Package bs.el
11620 The package bs.el offers a nifty buffer-selection buffer. The main
11621 command of this package is @code{bs-show}. With ECB < 2.20 this
11622 command does not really working well within activated ECB. But as of
11623 version 2.20 of ECB there should be no problems using this package.
11625 If you add ``*buffer-selection*'' as buffer-name to the option
11626 @code{ecb-compilation-buffer-names} then ECB will always display the
11627 buffer-selection buffer of bs in the compile-window (if there is one).
11628 Otherwise bs will use the edit-area to do its job.
11630 @subsubsection Package BBDB
11633 As of ECB 2.21 there should be no conflicts between BBDB and ECB, so
11634 BBDB can be used even when the ECB-windows are visible.
11636 But if you encounter problems then it is recommened to use one of the
11637 window-managers escreen.el or winring.el (@pxref{Window-managers and
11638 ECB}). With such a window-manager ECB and BBDB should work together
11639 very well under all circumstances!
11641 @subsubsection Package calendar.el
11643 @cindex calendar package
11644 With activated ECB @code{calendar} does not shrink it´s window to the small
11645 size but splits the window equally. But if you add this to your
11646 @file{.emacs} it works:
11650 (add-hook 'initial-calendar-window-hook
11651 (function (lambda ()
11652 (when (and ecb-minor-mode
11653 (ecb-point-in-edit-window))
11654 ;; if no horizontal split then nothing
11656 (or (= (frame-width) (window-width))
11657 (shrink-window (- (window-height) 9))))
11662 @subsubsection Package cygwin-mount.el
11664 @cindex cygwin-mount package
11665 There can be a conflict between ECB and cygwin-mount.el if the
11666 following conditions are true:
11669 @item You are working with cygwin-mount.el (sounds clear :-)
11670 @item You have set @code{cygwin-mount-build-mount-table-asynch} to not
11672 @item ECB is automatically started after starting Emacs (e.g. with
11673 @code{ecb-auto-activate} or calling @code{ecb-activate} in
11674 @code{window-setup-hook})
11675 @item Your Emacs-setup contains a call of @code{cygwin-mount-activate}.
11678 Under these circumstances Emacs 21.X sometimes eats up the whole CPU (at
11679 least with Windows XP) and the cygwin-mount-table is never build.
11681 But there is an easy work-around: Call @code{cygwin-mount-activate}
11682 first *AFTER* ECB is activated. This can be done with the hook
11683 @code{ecb-activate-hook}:
11687 (add-hook 'ecb-activate-hook
11688 (function (lambda ()
11689 (require 'cygwin-mount)
11690 (setq cygwin-mount-build-mount-table-asynch t)
11691 (cygwin-mount-activate))))
11696 @subsubsection Package desktop.el
11699 ECB works perfectly with the desktop-saver desktop.el. But to ensure
11700 this the option @code{desktop-minor-mode-table} @strong{MUST} contain
11701 the following entry:
11704 (ecb-minor-mode nil)
11707 Without this entry desktop.el tries for each buffer it loads after
11708 Emacs-start to enable @code{ecb-minor-mode} and therefore to start
11709 ECB. This conflicts with ECB! Therefore you must add the entry above
11710 to @code{desktop-minor-mode-table}!
11712 Further it is strongly recommended to add entries for all the
11713 minor-mode of the semantic-package to @code{desktop-minor-mode-table},
11714 so for example add also:
11718 (semantic-show-unmatched-syntax-mode nil)
11719 (semantic-stickyfunc-mode nil)
11720 (senator-minor-mode nil)
11721 (semantic-idle-scheduler-mode nil)
11725 Which modes you have to add depends on which modes of semantic you
11726 use. But to get sure you should add all minor-modes of the
11727 semantic-package because these modes are normally activated by the
11728 related ``global'' command (e.g.
11729 @code{global-semantic-show-unmatched-syntax-mode}) or by adding the
11730 minor-mode to the related major-mode-hook.
11732 It has also been reported that just disabling the Tip-Of-The-Day
11733 (option: @code{ecb-tip-of-the-day}) fixes the compatibility-problems
11734 with desktop.el. Just try it out!
11736 @subsubsection Package edebug (Lisp Debugger)
11739 It is strongly recommended to run edebug only when the ECB-windows are
11740 hidden. With visible ECB-windows there will probably serious conflicts
11741 between the ECB-layout and the edebug-window-manager.
11743 @subsubsection Package ediff.el
11746 In most cases ECB works very well with ediff (see option
11747 @code{ecb-run-ediff-in-ecb-frame}). But currently suspending ediff
11748 with @code{ediff-suspend} and restoring the ediff-session (e.g. with
11749 command @code{eregistry}) does confuse the window-management of ECB.
11751 If you often use ediff in a scenario where you suspend ediff and
11752 reactivate it later then it is recommended to exit ECB first
11753 (@code{ecb-deactivate} or @code{ecb-minor-mode})!
11755 @subsubsection Package follow-mouse.el
11758 The following is only relevant for Emacs 20.X!
11760 @cindex follow-mouse package
11761 ECB works very well with follow-mouse if follow-mouse is turned on
11762 @strong{BEFORE} ECB is activated (e.g. within the
11763 @code{ecb-activate-hook}). But if you activate follow-mouse first
11764 after ECB is already activated, then the follow-mouse stuff prevents
11765 the complete node-name to be displayed in the echo-area if mouse moves
11766 over it. Because ECB has a much more intelligent mouse tracking
11767 mechanism than follow-mouse the follow-mouse stuff profit from ECB and
11768 works even better and saver as without activated ECB!
11770 @subsubsection Package func-menu.el
11772 @cindex func-menu package
11773 This package has been reported to produce some conflicts under some
11774 circumstances when ECB is activated. Some of them could be reproduced
11775 by the ECB-maintainer. So the recommendation is to disable
11776 func-menu-support when using ECB. Normally using func-menu makes no
11777 sense in combination with ECB because ECB provides the same and even
11778 more informations as func-menu - so func-menu is redundant ;-)
11780 @subsubsection Package Gnus (Newsreader)
11783 As of ECB 2.21 there should be no conflicts between Gnus and ECB, so
11784 Gnus can be used even when the ECB-windows are visible.
11786 But if you encounter problems then it is recommened to use one of the
11787 window-managers escreen.el or winring.el (@pxref{Window-managers and
11788 ECB}). With such a window-manager ECB and Gnus should work together
11789 very well under all circumstances!
11791 @subsubsection Package JDEE (Java Development Environment)
11794 JDEE has a lot of ``dialogs'' where the user can select among several
11795 choices. An example is importing classes via the command
11796 @code{jde-import-find-and-import}. These dialogs are strongly designed
11797 to work in an environment where a new temporary window is created, the
11798 contents of the dialog are displayed in the new window, the user
11799 select his choice and hits [OK]. After that the new window is deleted
11800 and the selection is performed (for example the chosen import
11801 statement are inserted in the source-buffer.
11803 @strong{Caution}: ECB can work very well with this dialogs but only if
11804 the buffer-name of these dialog-buffers (normally ``Dialog'') is not
11805 contained in the option @code{ecb-compilation-buffer-names}. So do not
11806 add the string ``Dialog'' to this option!
11808 @strong{Please Note}: Regardless if a durable compile-window is used
11809 (i.e. @code{ecb-compile-window-height} is not nil) or not, these
11810 JDEE-dialogs will always being displayed by splitting the edit-window
11811 of ECB and not within the compile-window.
11813 @subsubsection Package scroll-all.el (scroll-all-mode)
11815 @cindex scroll-all-mode
11817 ECB advices @code{scroll-all-mode} so it is working correct during
11818 running ECB. This means if point stays in an edit-window and the
11819 edit-window is splitted then all edit-windows are scrolled by
11820 @code{scroll-all-mode} and no other window! If point stays in any
11821 other window just this selected window is scrolled. This is the only
11822 senseful behavior of @code{scroll-all-mode} with ECB.
11824 @subsubsection Package VC (Version Control)
11827 @cindex Version control
11828 The variable @code{vc-delete-logbuf-window} must be set to nil during
11829 active ECB. This can be done with the hooks mentioned in @ref{Elisp
11832 @subsubsection Package VM (Emacs Mail-Client)
11835 As of ECB 2.21 there should be no conflicts between VM and ECB, so
11836 VM can be used even when the ECB-windows are visible.
11838 But if you encounter problems then it is recommened to use one of the
11839 window-managers escreen.el or winring.el (@pxref{Window-managers and
11840 ECB}). With such a window-manager ECB and VM should work together very
11841 well under all circumstances!
11844 @subsubsection Package winner.el (winner-mode)
11846 @cindex winner-mode
11848 @code{winner-mode} is autom. disabled as long as ECB is running. ECB
11849 has its own window-management which is completely incompatible with
11850 @code{winner-mode}! But @code{winner-mode} makes also not really sense
11853 @subsubsection Package wb-line-number.el
11854 @cindex wb-line-number
11856 Do not use the package wb-line-number.el in combination with ECB - it
11857 will not work and it will not work under any circumstances and there
11858 is no way to make it work together and there will be no way in the
11861 The reason behind that is: wb-line-number.el uses additional dedicated
11862 windows to display the line-numbers. And ECB can not work if there
11863 there are additional dedicated windows - additional to that ones
11866 @subsubsection Application xrefactory
11869 Xrefactory (also known as Xref, X-ref and Xref-Speller), the
11870 refactoring browser for (X)Emacs@footnote{Xrefactory is available at
11872 @uref{http://www.xref-tech.com}
11875 @url{http://www.xref-tech.com}
11877 }, can be used during running ECB regardless if the ECB-windows are
11878 visible or not. There should be no conflicts as of ECB versions >=
11881 If there are conflicts with the Xref-browser then the most recommended
11882 way is to use one of the window-manager escreen.el or winring.el (and
11883 then use different escreens or window-configurations for ECB and
11884 Xrefactory-browsing - @ref{Window-managers and ECB}).
11886 @subsection What to do for unknown conflicts with other packages
11888 As of version 2.20 the layout-engine of ECB is so flexible that
11889 normally there should be no conflicts with other packages unless these
11890 packages have their own complete window-layout-management (e.g. Gnus,
11891 BBDB, Xrefactory). But these packages can and should be handled very
11892 well with the window-manager-support of ECB (@pxref{Window-managers
11895 So if you detect an unknown (i.e. not listed in the conflicts-list in
11896 the next subsection) conflict with a small package and some of its
11897 commands and you have installed an ECB-version < 2.20 the first task
11898 you have to do is to upgrade to a version >= 2.20!
11900 If this doesn't solve the problem a very probable reason for the
11901 conflict is that the command fails if called from another window than
11902 an edit-window of the ecb-frame. So please check if the problem
11903 disappears if you call the failing command from an edit-window of ECB.
11904 If this is true then you you can add the following code to your
11905 .emacs (and of course replace the XXX with the failing command):
11909 (defadvice XXX (before ecb activate)
11910 "Ensures `XXX' works well when called from another window
11911 as an edit-window. Does nothing if called in another frame
11912 as the `ecb-frame'."
11913 (when (equal (selected-frame) ecb-frame)
11914 (unless (ecb-point-in-edit-window)
11915 (ecb-select-edit-window))))
11919 This before-advice runs before the command XXX and ensures that the
11920 XXX is called from within an edit-window if the current selected
11921 window is not an edit-window. It does nothing if called for another
11922 frame as the ecb-frame.
11924 If such an advice solves the problem then please send a not with the
11925 solution to the ECB-mailing-list or direct to the ECB-maintainer so
11926 the solution can be integrated in the next ECB-release
11928 If calling from an edit-window fails too then please file a complete
11929 bug-report to the ECB-mailing-list (@pxref{Submitting problem
11930 report}). This report should contain a detailed description which
11931 command of which package fails under which circumstances!
11934 @node Bugs, , Conflicts, Conflicts and bugs
11935 @section Known bugs
11937 This section describes all currently known bugs of ECB. The
11938 maintainers of ECB try to fix these bugs as soon as possible.
11940 @subsection Following the source-file link in a help-buffer
11942 The following bug occurs only in ECB-versions < 1.96 and is fixed
11945 This bug only occurs if a compile-window is used and visible!
11947 If you call functions like @code{describe-function} which displays a
11948 help-buffer in the compile-window, then you will often get an output
11949 like this in the compile-window:
11952 ecb-activate is an interactive compiled Lisp function in `ecb'.
11955 Activates the ECB...
11958 The link to `ecb' is normally a click-able link, means if you click
11959 with the middle-mouse button onto it the file is opened (in our
11960 example @file{ecb.el} would be opened.
11962 If you click onto it when the help-buffer is already the current
11963 buffer (i.e. the compile-window is already selected before the click!)
11964 then all is working fine (i.e. the file is opened in the edit-window),
11965 but if you click onto the link without selecting the compile-window
11966 before (i.e. the edit-window is the current selected window) then the
11967 file is opened in the compile-window which is probably not what you
11968 want. Not a big problem but annoying.
11970 The only available workaround is, first selecting the compile-window
11971 and then clicking onto the link!
11973 @subsection Extra history-entries for JDEE source-buffers
11975 ECB on occasions creates an extra edit buffer for entries in the
11976 history window. For example, let say there are three entries in the
11987 In the edit window Test1 file is edited. When clicked on Test2 entry
11988 in history, on occasion instead of switching to the existing buffer for
11989 Test2, a new edit buffer is opened for Test2 file. At this point, there
11990 are four entries in the history as follows:
12001 @node FAQ, Command Index, Conflicts and bugs, Top
12002 @chapter Frequently asked questions
12004 This is the Emacs Code Browser FAQ.
12006 @c To produce prettier output we make a small empty column between the
12007 @c question- and the answer-column. Therefore every Q/A-item must look
12010 @c @c an empty line between every Q/A-item
12015 @c <The text of the question?>
12017 @c <The text of the answer>
12019 @multitable @columnfractions 0.40 0.01 0.59
12036 @c an empty line between every Q/A-item
12041 What is the first step i should do if i have problems with ECB?
12043 Read carefully the related sections of the online-help of ECB.
12048 What should i do, if a have a problem which can not be solved even
12049 after reading the online-help?
12051 Send a problem-report to the ECB-mailing-list with the command
12052 @code{ecb-submit-problem-report}.
12056 See @ref{Submitting problem report}.
12061 What should i do, if another package seems not to work correct with
12064 Take a look into @ref{Conflicts}. If your package is not listed there
12065 then submit a problem-report.
12070 Can ECB parse and display source-contents not supported by semantic?
12072 Yes, in all version >= 1.94. ECB can now parse and display all
12073 source-contents supported by semantic, imenu or etags - same as
12074 speedbar. See @ref{Non-semantic sources}.
12079 Why are the lines in the ECB-, temp- and compilation-buffers not
12080 wrapped but truncated?
12082 Check the variable @code{truncate-partial-width-windows} and set it to
12088 Why doesn't ECB work correct with VC?
12090 The variable @code{vc-delete-logbuf-window} must be set to nil during
12091 active ECB. This can be done with the hooks of ECB.
12096 Does ECB support C++ as well as Java?
12098 This depends strongly on the used semantic-version, but all
12099 semantic-versions >= semantic-1.4.3 support C++ really well.
12104 Does ECB support Perl?
12106 If perl can be parsed either by imenu, etags or semantic then ECB
12107 supports perl. Of course ECB would support perl best if perl is
12108 supported by semantic.
12113 Does ECB support language XYZ?
12115 See question ``Does ECB support Perl?'' and replace ``Perl'' with
12116 ``XYZ'' in the answer.
12121 How to add new languages to ECB?
12123 Add the language XYZ to semantic (perform all necessary steps described in
12124 the semantic-manual) and ECB will automatically support language XYZ!
12125 There is nothing to do in ECB itself! Same when you write an imenu- or
12126 etags-support for language XYZ.
12131 Why does ECB not recognize my source-files for C++?
12133 Your C++-files have probably an extension which is not mapped to
12134 c++-mode in @code{auto-mode-alist} and/or your own Emacs-setup has
12135 ``destroyed'' the correct value of the hook-variable
12136 @code{c++-mode-hook}.
12140 See @ref{Setting up Emacs}.
12145 Why doesn't ECB display the node name in the echo area if mouse moves
12148 There can be several reasons: First the value of the option
12149 @code{ecb-show-node-name-in-minibuffer} must be either @code{always} or
12150 @code{if-too-long}. If this is OK, then maybe you have turned on
12151 follow-mouse AFTER activating ECB; follow-mouse must be turned on
12152 BEFORE ECB is activated, e.g. in the @code{ecb-activate-hook}! But with
12153 Emacs 21.X and XEmacs there are no problems with this feature, just
12159 What is the reason for poor scrolling performance with GNU Emacs 20.X
12160 in the edit-windows and what can i do?
12162 Set @code{scroll-conservatively} to 0 and @code{scroll-step} to a
12163 value > 1. For the exact reason look at
12167 @ref{Optimize scrolling}.
12172 Is it possible to make the history of ECB persistent?
12174 You can use the library ``desktop.el'' which works very well with ECB.
12175 Then all files of your recent Emacs-session will be opened
12176 automatically after next Emacs-start and will be added automatically
12177 to the ECB-history after ECB-start.
12182 Is there an ``Intellisense''-mechanism like with other IDEs?
12184 For Java the JDEE@footnote{
12186 @uref{http://jdee.sunsite.dk/}
12189 @url{http://jdee.sunsite.dk/}
12191 } has this feature and for all other languages
12192 semantic offer something similar, see
12194 @uref{http://cedet.sourceforge.net/intellisense.shtml}
12197 @url{http://cedet.sourceforge.net/intellisense.shtml}
12203 Can i use ECB in combination with Gnus within one frame?
12205 You can, but for ECB-versions < 1.96 it is not recommended because
12206 each of them has it's own window-management and probably there will be
12207 conflicts, so use different frames for ECB and Gnus! But beginning
12208 with ECB 1.96 you can use either escreen.el or winring.el as
12209 ``window-manager'' which allows you in consequence to use ECB and
12210 applications like Gnus in one frame!
12214 @xref{Window-managers and ECB}.
12219 Can i speed up displaying the contents of big-size directories?
12221 Yes, see the option @code{ecb-cache-directory-contents}. Read the
12226 @ref{Large directories}.
12231 Is it possible to create/use other layouts than the built-in ones?
12233 Yes. @ref{Creating a new ECB-layout} and
12237 @ref{The layout-engine} are the relevant sections. The former one
12238 describes how to create interactively new layouts where the latter
12239 one is for Elisp-programmers.
12244 Can i use speedbar as directory-browser within ECB?
12246 Yes, see @ref{Integrating speedbar}.
12251 Can i exclude subdirectories from the recursive grep in the directories buffer?
12253 Yes, see @ref{Grepping directories}.
12258 How can i prevent contaminating each directory with a file @file{semantic-cache}?
12260 Set @code{semanticdb-default-save-directory} to a directory.
12265 Why ECB displays large portions of current source-file with dark background?
12267 This comes from semantic;
12271 see @ref{Setting up Emacs}.
12276 Why ECB underlines some parts of current source-file?
12278 This comes from semantic;
12282 see @ref{Setting up Emacs}.
12287 Can i add my own commands to the popup-menus of tree-buffers?
12289 Yes, see @ref{Using the mouse}.
12294 Can ECB display the compile-window ``on demand''?
12296 Yes, see @ref{Tips and tricks}.
12301 Which buffers are treated as compilation-buffers by ECB?
12303 See the docstring of the function @code{ecb-compilation-buffer-p}.
12308 How can i change the modeline of an ECB-tree-buffer?
12310 You can change it with the options @code{ecb-mode-line-prefixes},
12311 @code{ecb-mode-line-data} and
12312 @code{ecb-mode-line-display-window-number}.
12317 Can the tree-buffers being selected faster than with the
12318 standard-keybindings of ECB?
12320 Yes, see option @code{ecb-mode-line-display-window-number}.
12325 Can ECB display the window-number in the modeline of the special windows?
12327 Yes, see option @code{ecb-mode-line-display-window-number}.
12332 How can i change the keybindings of ECB?
12334 You can do this with option @code{ecb-key-map} (@pxref{ecb-general}).
12339 What can i do if hiding/showing from the methods-buffer does not work?
12341 Either the current @code{major-modes} is not supported by hideshow or
12342 you have to add an entry to @code{hs-special-modes-alist}
12346 (@pxref{Hide-show}).
12351 Can i maximize one of the ECB-windows for better overlook?
12353 Yes, see @ref{Maximizing the ECB windows}.
12358 Can i hide the ECB-windows for getting more editing-space?
12360 Yes, see @ref{Hiding the ECB windows}.
12365 Can i define the actions ECB performs after visiting a tag?
12367 Yes, see @ref{Visiting tags}.
12372 Buffers are not displayed correctly in the compile-window?
12374 See @ref{Problems with the compile window}.
12379 Can ECB work together with window-managers like escreen.el?
12381 Yes, see @ref{Window-managers and ECB}.
12386 Can i remove these ``ugly'' vertical lines from a tree-buffer?
12388 Yes, see option @code{ecb-tree-buffer-style}.
12393 ECB does not display images in the tree-buffers - what can i do?
12395 Customize @code{ecb-tree-buffer-style} and restart ECB. But note: GNU
12396 Emacs <= 21.3.X for Windows does not support image-display so ECB uses
12397 always ascii-guide-lines even when here the image-style is set in
12398 @code{ecb-tree-buffer-style}.
12403 Do @code{special-display-function} et. al. work with ECB.
12409 @ref{Using special-display with ECB}.
12414 Can i activate the popup-menu of a tree-buffer from keyboard?
12416 Yes, see @ref{Using popup-menus}.
12421 Can i display the popup-menu of a tree-buffer with tmm?
12423 Yes, see @ref{Using popup-menus}.
12428 Does ECB disable all advices after deactivation?
12430 ``Nes''@footnote{Nes is a combination of No and Yes :-)}, see remarks
12431 in the documentation of the option
12432 @code{ecb-split-edit-window-after-start}.
12437 Can ECB preserve the full state of ECB between deactivation and next
12440 Yes, see the option @code{ecb-split-edit-window-after-start}.
12445 Can i change the behavior how ECB chooses another window for selecting
12446 it or scrolling it.
12448 Yes, see @ref{The other window}.
12453 Can i increase the allowed depth of nested submenus.
12455 Yes, see the docstring of the option
12456 @code{ecb-directories-menu-user-extension}.
12461 Can i apply some filters to the Tree-buffers.
12463 Yes, see @ref{Filtering the tree-buffers}
12468 With XEmacs i get sometimes an error ``Wrong number of arguments:
12469 widen (1)''. What can i do?
12471 Disable the func-menu support in your XEmacs-setup. See
12477 Can i use desktop.el in combination with ECB?
12479 Yes, see @ref{Conflicts}.
12484 Opening directories takes a long time - what can i do?
12486 Read @ref{Large directories}.
12491 ECB seems to be blocked sometimes - what is the reason?
12493 ECB performs some stealthy tasks when idle - this can cause sometimes
12494 a blocked Emacs but this tasks will be immetiatelly interrupted by any
12495 user-event so there should be normally no problems. But especially for
12496 mounted net-drives some of the stealthy tasks can take time up to some
12497 seconds for each file - and during one file-operation it can not be
12498 interrupted. See also @code{ecb-stealthy-tasks-delay}.
12503 Can i exclude certain directories from being checked for emptyness?
12505 Yes, see option @code{ecb-prescan-directories-exclude-regexps}.
12510 Can i exclude certain directories from checking the VC-state of the
12513 Yes, see option @code{ecb-vc-directory-exclude-regexps}.
12518 Can i exclude certain directories from checking the read-only-state of
12519 the contained sources?
12521 Yes, see option @code{ecb-read-only-check-exclude-regexps}.
12526 ECB ignores the remote-paths i have added to @code{ecb-source-path}.
12528 Maybe you have to check the option @code{ecb-ping-options}. Ensure
12529 that this option contains a value suitable for your ping-program (see
12530 @code{ecb-ping-program}).
12534 See also @ref{Remote directories}.
12539 ECB seems to be blocked a long time.
12541 Maybe you use cygwin-XEmacs. Then either the empty-dir-check (see
12542 option @code{ecb-prescan-directories-for-emptyness}) or the VC-support
12543 (see @code{ecb-vc-enable-support}) can block ECB.
12547 For the latter one see @ref{Known VC-problems}.
12552 ECB seems to be blocked during the VC-state update in the
12555 Maybe the root repository for the current directory is a
12556 remote-repository. This can result in a long lasting check-time per
12561 See also @ref{Version-control support} for hints what you can do.
12566 I have encountered some problems with the display of the VC-state in
12569 See also @ref{Version-control support} for hints what you can do.
12573 @node Command Index, Option Index, FAQ, Top
12574 @unnumbered Command Index
12577 This index contains all user commands of ECB.
12579 @strong{Please note}: The commands in this index are listed without
12580 the prefix ``ecb-'' (e.g. the command @code{ecb-activate} is listed
12581 with name ``activate'').
12585 @node Option Index, Concept Index, Command Index, Top
12586 @unnumbered Option Index
12589 This index contains all customizable options of ECB.
12591 @strong{Please note}: All options in this index are listed without the
12592 prefix ``ecb-'' (e.g. the option @code{ecb-layout-name} is listed with
12593 name ``layout-name'').
12597 @node Concept Index, , Option Index, Top
12598 @unnumbered Concept Index
12607 @c LocalWords: texinfo Berndl java ECB ecb texi berndl Exp setfilename vr cp
12608 @c LocalWords: settitle syncodeindex fn ifinfo paragraphindent exampleindent
12609 @c LocalWords: footnotestyle frobbed ecbver dircategory direntry titlepage sp
12610 @c LocalWords: titlefont vskip pt Jesper Nordenberg dir ifnottex Elisp imenu
12611 @c LocalWords: etags perl iftex ref tex url ifhtml uref detailmenu eshell API
12612 @c LocalWords: keybindings speedbar Grepping JDEE website eieio xref subdirs
12613 @c LocalWords: loadtime autoloads Bytecompiling bytecompile EMACSINFOPATH hxx
12614 @c LocalWords: pxref alist multitable columnfractions ifnotinfo hh HH cxx cpp
12615 @c LocalWords: CC jde setq RET kbd Alt minibuffer cindex dfn grep ascii popup
12616 @c LocalWords: screenshot splitted sourcecode noindent de itemx rsp CTRL hor
12617 @c LocalWords: senseful modeline subnode uml const gm Ctrl docstring autom lc
12618 @c LocalWords: subsubsection fontify defun asis Hist leftright lr nav dired
12619 @c LocalWords: deffn var CLEARALL cedet sourcepath classpath arg html regexp
12620 @c LocalWords: backtrace def incl defopt cdr keysequence SPC DEL LFD ESC NUL
12621 @c LocalWords: alt abc horiz filenumber rexexp bigdir iff cvsignore lib ini
12622 @c LocalWords: elc obj dll rexexps assoc taglist bovinate toplevel oo CLOS
12623 @c LocalWords: defclass colorized XYZ XYC structs colorizing struct enum adv
12624 @c LocalWords: func comint proc min subdir wget gzip cygwin ifnothtml env iso
12625 @c LocalWords: http defcustom upgradable defconst lw doc ls grepping tempor
12626 @c LocalWords: igrep CVS gen maxout FF hs hideshow JDEbug defmac ver undefine
12627 @c LocalWords: Bufferinfo rw bufferinfo readonly filebuffer filebuffers pos
12628 @c LocalWords: cond buf preactivation usw msw lsw asynch XP Newsreader BBDB
12629 @c LocalWords: VC vc logbuf BNF Intellisense IDEs semanticdb printindex