This is ecb.info, produced by makeinfo version 4.8 from ecb.texi. INFO-DIR-SECTION The Emacs editor and associated tools START-INFO-DIR-ENTRY * ECB: (ecb). Emacs Code Browser END-INFO-DIR-ENTRY  File: ecb.info, Node: Top, Next: Install and first steps, Prev: (dir), Up: (dir) This is the user manual for ECB version 2.32. ECB stands for "Emacs Code Browser". While (X)Emacs already has good *editing* support for many modes, its *browsing* support is somewhat lacking. That's where ECB comes in: it displays a number of informational windows that allow for easy source code navigation and overview. The informational windows can contain: * A directory tree, * a list of source files in the current directory, * a list of functions/classes/methods/... in the current file, (ECB uses the Semantic Bovinator, or Imenu, or etags, for getting this list so all languages supported by any of these tools are automatically supported by ECB too) * a history of recently visited files, * the Speedbar and * output from compilation (the "*compilation*" window) and other modes like help, grep etc. or whatever a user defines to be displayed in this window. As an added bonus, ECB makes sure to keep these informational windows visible, even when you use `C-x 1' and similar commands. It goes without saying that you can configure the layout, ie which informational windows should be displayed where. ECB comes with a number of ready-made window layouts to choose from. *Please note*: Experienced ECB users find a complete alphabetical list of all commands and user-options in *Note Interactive ECB commands:: and *Note Customizable options::. The latest version of ECB can always be found at the URL `http://ecb.sourceforge.net'. To send bug reports, or participate in discussions about ECB, use the mailing list via the URL `http://lists.sourceforge.net/lists/listinfo/ecb-list'. *IMPORTANT*: Cause of extra appearance of SPAM in the mailing-lists, SourceForge has changed its policy: Now it is only possible to post to the mailing-list for users who have subscribed this mailing-list. So please be aware you will not be able to send comments, bug reports and improvement suggestions before you have subscribed the ECB-mailing-list. See the section "Mailing-list" at the ECB-website at `http://ecb.sourceforge.net' how to do this. * Menu: * Install and first steps:: Installing ECB and first steps * Overview:: Compact introducing of basic concepts * Manual usage:: How to use this manual * ECB-interactors:: Description of all interactors of ECB * Activation and Deactivation:: How to start and end ECB * Usage of ECB:: How to use ECB * Customizing:: How to customize ECB * Submitting problem report:: What to do when problems occur * Upgrading:: Upgrading and downloading packages * Tips and tricks:: Useful hints and tips * Elisp programming:: Entry points for Elisp programmers * Conflicts and bugs:: Known Conflicts with other packages and bugs * FAQ:: Frequently asked questions * Command Index:: Index for interactive commands * Option Index:: Index for user options * Concept Index:: Index for concepts and terms --- The Detailed Node Listing --- Installation and first steps of ECB * Installation:: Installation of ECB * Setting up Emacs:: How to set up Emacs for file parsing with ECB * First steps:: First steps after activating ECB first time Installation of ECB * XEmacs Installation:: Installation of ECB for XEmacs users * GNU Emacs Installation:: Installation of ECB for GNU Emacs users How to set up Emacs for file parsing with ECB * General hints:: General hints for a correct setup * Setting up semantic:: How to setup semantic correctly * Non-semantic files:: Setup for file types not supported by semantic All interactors of ECB * Basic interactors:: Description of the basic interactors * Add-on interactors:: Description of additional interactors The basic interactors of ECB * Tree-buffer basics:: General introduction into tree-buffers * Tree-buffer styles:: Displaying the trees with different styles * ECB Directories-buffer:: Contents of the ECB Directories-buffer * ECB Sources-buffer:: Contents of the ECB Sources/history-buffer * ECB Methods-buffer:: Contents of the ECB Methods-buffer Displaying the trees with different styles * Style basics:: Basic knowledge about the styles * Ascii-based styles:: How to customize the ascii-styles * Tree-buffers with images:: Which images are used for the tree * Images for Methods-buffer:: Images for the tags in the Methods-buffer Add-on interactors of ECB * Semantic analyser:: Analyses and displays semantic context * Symboldefinition:: Displays definition of current symbol Activation and Deactivation * Standard activation:: How to manually (de)activate ECB * Automatic activation:: Automatically (de)activating ECB Usage of ECB * Using the mouse:: Working with the mouse * Using the keyboard:: Working with the keyboard * The edit-area:: How to use the edit-area * Temp- and compile-buffers:: Displaying temp- and compilation-buffers * The other window:: How the ``other window'' is determined * The Methods buffer:: Using and customizing the Methods-buffer * Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers * The ECB-layout:: Changing, customizing, redrawing, creating * Hiding the ECB windows:: Hiding/Showing the ECB-windows * Maximizing the ECB windows:: Maximizing the ECB-windows * Back/forward navigation:: Back- and forward navigation like a browser * ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows * Stealthy background tasks:: Stealthy background-tasks of ECB * Interactive ECB commands:: All interactive user-commands of ECB Working with the keyboard in the ECB-windows * Navigation/Selection:: Keyboard navigation/selection in a tree-buffer * Incremental search:: Find nodes as fast as possible * Personal tree-keybindings:: Adding personal keybindings to a tree-buffer * Using popup-menus:: Using the popup-menus from keyboard. Using and customizing the ECB-Methods buffer * Visiting tags:: Possible actions after visiting a tag * Expanding:: Explicit and automatic expanding * Customizing the display:: How to customize the Methods-buffer display * Rebuilding the Methods:: When to rebuild the Methods-buffer Applying filters to the special ECB-tree-buffers * Filtering Directories:: Applying filters to the Directories-buffer * Filtering Sources:: Applying filters to the Sources--buffer * Filtering History:: Applying filters to the History-buffer * Filtering Methods:: Applying filters to the Methods-buffer Changing, customizing, redrawing and creating layouts * Changing the ECB-layout:: How to change and customize the layout * Redrawing the ECB-layout:: How and when redrawing the layout * Changing window sizes:: Changing sizes of the ECB-windows * Fixing window sizes:: Fixing sizes of the ECB-windows * Creating a new ECB-layout:: Interactively creating new layouts Customizing ECB * General aspects:: General aspects for customizing ECB * Most important options:: Which option you must know * Customizable options:: All customizable options of ECB General aspects for customizing ECB * setq or customize:: Should i use setq or customize? * Site-wide customizing:: Site-wide customizing of ECB All customizable options of ECB * ecb-general:: General customizing ECB * ecb-tree-buffer:: Customizing the general tree layout * ecb-directories:: Customizing the ECB-directories-tree * ecb-sources:: Customizing the ECB-sources-tree * ecb-methods:: Customizing the ECB-methods-tree * ecb-history:: Customizing the ECB-history-tree * ecb-analyse:: Customizing the ECB-analyse-interactor * ecb-layout:: Customizing the ECB-layout * ecb-compilation:: Customizing the compile-window * ecb-create-layout:: Customizing options for creating layouts * ecb-face-options:: Customizing options for faces * ecb-faces:: Customizing the faces * ecb-download:: Customizing how to download ECB * ecb-help:: Customizing the online help of ECB * ecb-eshell:: Customizing the eshell-integration * ecb-speedbar:: Customizing the speedbar-integration * ecb-non-semantic:: Customizing parsing non-semantic sources * ecb-winman:: Customizing window-manager support * ecb-mode-line:: Customizing the tree-buffer-modelines * ecb-version-control:: Customizing the version-control-support Upgrading and downloading packages * Downloading new versions:: How to download newer versions of packages * Auto. option-upgrading:: ECB can auto. upgrade your options Automatic upgrading of options * User interface:: Options and commands you should know * Background information:: Maybe some interesting informations Tips and tricks * Changing faces:: Changing faces in the ECB tree-buffers * Small screens:: Working with small screens * Big screens:: Working with big screens * Simulating speedbar:: Simulating speedbar without an extra frame * Integrating speedbar:: Integrating speedbar in the ECB-frame * Large directories:: Working with large directories * Remote directories:: Working with remote directories * Version-control support:: Supporting Version control systems * Using eshell:: Optimal using of eshell in ECB * Grepping directories:: Grepping directories with ECB * Working with JDEE:: Working best with ECB and JDEE * Compile-window on demand:: Displaying the compile-window on demand * Non-semantic sources:: Parsing and displaying non-semantic sources * Hide-show:: Using hide-show from the methods-buffer-menu * Window-managers and ECB:: Support of several Emacs-window-managers * Using semanticdb:: Using semanticdb for going to external nodes Supporting Version control systems * Identifying backends:: How ECB identifies the VC-backend of a dir * Checking the state:: How ECB checks the VC-state of a file * Remote repositories:: What you should know about this * Refreshing the VC-state:: How to refresh when state changed outside * Adding new backends:: Necessary steps for adding new backends * Known VC-problems:: Currently known problems of the VC-support Entry points for Elisp programmers * List of variables:: Which variables an Elisp-program can use * List of hooks:: All available hooks * tree-buffer:: Some words to the tree-buffer-library * Adviced functions:: How to deal with the adviced functions * The layout-engine:: Programming new layouts and special windows The library tree-buffer.el * Introduction:: General description of tree-buffers * A new tree-buffer:: How to create a new tree-buffer * A new tree-node:: How to add new tree-nodes to a tree-buffer * Updating a tree-buffer:: How to update a tree-buffer after changes * Tree-buffer keybindings:: Default and customizable keybindings * The tree-buffer-API:: All functions available for tree-buffers * Do not with tree-buffer:: Things which are strictly forbidden * Tree-buffer How to:: Dealing with special situations How to program new layouts and new special windows * Programming a new layout:: How to program a new layout * Programming special windows:: Aspects of programming special windows * Possible layout-outlines:: The wide range of possible layouts * The layout-engine API:: The complete layout-engine API Conflicts and bugs of ECB * Conflicts:: Conflicts with other packages * Bugs:: Known bugs  File: ecb.info, Node: Install and first steps, Next: Overview, Prev: Top, Up: Top 1 Installation and first steps of ECB ************************************* This chapter describes how to install ECB and setup (X)Emacs correctly and what are the first steps after activation of ECB. * Menu: * Installation:: Installation of ECB * Setting up Emacs:: How to set up Emacs for file parsing with ECB * First steps:: First steps after activating ECB first time  File: ecb.info, Node: Installation, Next: Setting up Emacs, Prev: Install and first steps, Up: Install and first steps 1.1 Installation of ECB ======================= This section describes how to install ECB. * Menu: * XEmacs Installation:: Installation of ECB for XEmacs users * GNU Emacs Installation:: Installation of ECB for GNU Emacs users  File: ecb.info, Node: XEmacs Installation, Next: GNU Emacs Installation, Prev: Installation, Up: Installation 1.1.1 Installation of ECB for XEmacs users ------------------------------------------ Basic requirement: ECB requires a XEmacs-version >= 21! For XEmacs-users it is strongly recommended to use the package-management-system of XEmacs for first-time downloading/installing ECB or for upgrading to a newer version of ECB. Here is a short guide (for details about the package-manager of XEmacs see the related info-manual): *Caution*: If ECB is already installed and you just want upgrading to a newer version then it is recommended to deactivate ECB before proceeding with the steps below! 1. Choose a download-site This can be done via the menu "Tools -> Packages -> Add Download Site": Choose one of the listed sites. Or you can customize the option `package-get-remote' by hand and save it for future sessions. 2. Activate the packages list This can be done either by the menu "Tools -> Packages -> List and Install" or via the command `pui-list-packages'. After that a special packages-buffer is displayed where you can interactively install or upgrade packages. At the end of this buffer there is a short description how to use this buffer. 3. Install ECB and all required packages Mark the package named "ecb" for install. Do this also for the required packages "semantic", "eieio" and "speedbar". The package "mail-lib" is needed for easy submitting of problem-reports to the ECB-maintainers and the package "c-support" is needed for easy using hideshow within the Methods-buffer of ECB(1). After marking all needed packages for installation hit `x' to install them. If you have already installed ECB and you want just upgrading to the latest available version then proceed as described above - same if you want to upgrade one of the required packages. 4. Start ECB Now you can immediately start ECB via the command `ecb-activate'; there is no need to restart XEmacs! As an alternative you can first read the online-help via `ecb-show-help'. If you do not like the package-manager of XEmacs but you want installing ECB "by hand" direct from the ECB-website then you have to follow the instructions for GNU Emacs, see *Note GNU Emacs Installation::. ---------- Footnotes ---------- (1) All required packages can simply autom. marked by hitting `r' in the packages buffer. But this installs a lot of packages more (e.g. the Newsreader Gnus) which are really not essential for ECB. Therefore it is recommended to mark the required packages by hand.  File: ecb.info, Node: GNU Emacs Installation, Prev: XEmacs Installation, Up: Installation 1.1.2 Installation of ECB for GNU Emacs users --------------------------------------------- Basic requirement: ECB requires an Emacs-version >= 21! *IMPORTANT*: If you are a XEmacs-user please read *Note XEmacs Installation:: before proceeding with the following instructions! *Using the new cedet 1.0 suite*: From beginning with version 2.01 ECB supports the next generation of the cedet-tools. But before the cedet 1.0 suite becomes stable this means that ECB runs correctly with loaded cedet 1.0 but the ECB-upgrading feature (*note Downloading new versions::) does not support autom. upgrading to latest available cedet versions. This will be first available after first stable release of the new cedet-library 1.0. So, if the cedet 1.0 suite is loaded then the min- and max-version of semantic, eieio and speedbar (mentioned in the Requirements-section of the file `README') have no relevance! If the new cedet 1.0 suite should be used then just install and load cedet 1.0 like described in the cedet-installation-instructions and go one with step 3. But ensure you have loaded - as described in the cedet-`INSTALL'-file - the file `/path/to/cedet/common/cedet.el' because otherwise cedet is not properly installed and ECB can not savely recognize that the new cedet-suite is loaded and should be used. 1. Download and unpack the ECB archive (probably you have already done this :-) 2. Read the file `README' in the ECB-directory and install the required semantic-, eieio- and speedbar-version(1). *Please note*: ECB maybe requires a newer version of these libraries than shipped with (X)Emacs. You have to install exactly a version ECB requires and also to make sure that the correct version is loaded into (X)Emacs! But ECB performs two autom checks: - At load-time: It checks if the packages semantic, eieio and speedbar are at least installed so ECB can be loaded. If not it offers to download and install them. - At start-time: It checks if the correct versions of semantic, eieio and speedbar are installed and gives you proper feedback. *Note Download required packages::. So if you are not sure if you have installed the required packages at all or if you have installed the correct versions of these packages then do not worry about this, just go on with the following installation steps: If ECB is missing something it will give you proper feedback and support not later than at load-time or start-time! 3. Add the new ECB-directory to your `load-path' variable. You *MUST* add the ECB-install-directory to the `load-path' either by changing the `load-path' variable directly in your `.emacs' or `site-lisp/site-start.el' or by working with a file `subdirs.el'(2). So for example the needed entry for your `.emacs'-file could be: (add-to-list 'load-path "/path/to/your/ecb/installation/directory") *ATTENTION*: ECB is NOT properly installed if it's directory is not added to `load-path' and for example just loaded by (load-file "/path/to/ecb/ecb.el") Do not do this! 4. Load ECB by adding code to your `.emacs': If you want to load the complete ECB at (X)Emacs-loadtime (Advantage: All ECB-options available after loading ECB. Disadvantage: Increasing loadtime(3)): (require 'ecb) If you want to load the ECB first after starting it by `ecb-activate' (Advantage: Fast loading(4). Disadvantage: ECB- and semantic-options first available after starting ECB): (require 'ecb-autoloads) This loads all available autoloads of ECB, e.g. `ecb-activate', `ecb-minor-mode', `ecb-byte-compile' and `ecb-show-help'. Regardless which method you prefer: In both cases the used statement must be placed *after* the statement of step 3! 5. Restart (X)Emacs. ECB is now ready for use and can be activated by calling `M-x ecb-activate' or `ecb-minor-mode'. Now you can either starting using ECB or you can do these optional installation steps: 6. Reading the online help with `ecb-show-help' Maybe you are interested to read the online-help of ECB before first start. 7. Bytecompiling ECB with `ecb-byte-compile' This byte compiles ECB. You can safely ignore all messages if there are any. (You can also bytecompile ECB from the command-line either by using the `Makefile' or by using the batch-file `make.bat'; just read the comments in that file you choose.) 8. Installing the Info-help of ECB The ECB distribution contains a subdirectory `info-help' which contains the online-help of ECB in Info-format. You can install this online help so it's available in the Top-directory of Info. There are two ways to do this: - Use "install-info" (recommended): 1. Copy the files of the subdirectory `info-help' into the info-directory of Emacs 2. Install the file `info-help/ecb.info' with the command "install-info" (if available on your system) in the `dir'-file. The supplied `Makefile' offers a target `install-help' which does both of these steps. You have just to call `make install-help' with the correct EMACSINFOPATH set (see the comment in `Makefile'). Here is an example: make EMACSINFOPATH=/path/to/emacs/info install-help - Manual Installation: Copy the files of the subdirectory `info-help' into the info-directory of Emacs and modify the file `dir' manually. But it doesn't matter if you do not execute this step (8.) because the online help of ECB is always available though, see `ecb-show-help' (*note Interactive ECB commands::). ---------- Footnotes ---------- (1) The speedbar-version shipped with GNU Emacs <= 21.3 does not satisfy the requirements for this feature - download a newer one! (2) This works at least for Emacs but XEmacs may have slightly different mechanisms; see the XEmacs documentation (3) Cause of full loading of ECB itself and also the packages semantic, eieio and speedbar regardless if ECB is started. (4) ECB, semantic, eieio and speedbar are first loaded after starting ECB or with other words: ECB and semantic are not loaded if you do not use/need them  File: ecb.info, Node: Setting up Emacs, Next: First steps, Prev: Installation, Up: Install and first steps 1.2 How to set up Emacs for file parsing with ECB ================================================= *Please note*: Normally it should not necessary for you to bother with the following stuff unless you have problems getting ECB working correctly for you. * Menu: * General hints:: General hints for a correct setup * Setting up semantic:: How to setup semantic correctly * Non-semantic files:: Setup for file types not supported by semantic  File: ecb.info, Node: General hints, Next: Setting up semantic, Prev: Setting up Emacs, Up: Setting up Emacs 1.2.1 General hints for a correct setup --------------------------------------- ECB is for browsing files and therefore you have to setup your Emacs-configuration properly so the file-parsing engines like semantic, imenu or etags can be activated automatically for parsing your Emacs-Lisp, C, C++ or Java buffers(1). For this Emacs must activate the correct `major-mode' for the source-files and Emacs can only do this if the option `auto-mode-alist' is setup correctly. The correct major-modes and possible file-extensions(2) are: LANGUAGE MAJOR-MODE EXTENSION(S) Emacs Lisp `emacs-lisp-mode' .el C `c-mode' .h, .c C++ `c++-mode' .h, .hxx, .hh, .HH, .cxx, .cpp, .cc, .CC Java `java-mode' or `jde-mode' (if you .java use JDEE) Example: If you want files with extension ".cpp" being c++-parsed by semantic and ECB, your `auto-mode-alist' must contain an entry like: ("\\.cpp\\'" . c++-mode) After this ECB will correctly parse your ".cpp"-sources and display all the parsing information in the ECB-methods buffer. ---------- Footnotes ---------- (1) semantic supports some more "languages" like Makefiles etc. but these are the most important ones. (2) Especially for C++ and C you can use any extension you want but these are the most common ones!  File: ecb.info, Node: Setting up semantic, Next: Non-semantic files, Prev: General hints, Up: Setting up Emacs 1.2.2 Setting up semantic ------------------------- To ensure ECB and semantic are working correctly for all by semantic supported languages you have to pay attention to the following aspects concerning your Emacs-setup: 1. Setting up semantic itself For all semantic-supported file-types parsing files is done completely by semantic. ECB just displays the parsing results. For all needs of ECB semantic is completely setup by ECB itself, i.e. ECB sets up semantic for you! You have only to add the installation directory of semantic to your `load-path' (in an appropriate way)! *Please note*: If you setup semantic for yourself following the recommendations in the installation instructions of semantic then you have probably added code to your startup-file like: (setq semantic-load-turn-everything-on t) (require 'semantic-load) Be aware that this also enables the minor-modes `semantic-show-dirty-mode' and `semantic-show-unmatched-syntax-mode' where the former one highlights all code which has to be reparsed with dark background (which results in large portions of dark background ;-) and the latter one underlines all syntax which can not be parsed. Especially the former one can be really annoying. To switch off these modes you can add to your startup-file: (global-semantic-show-dirty-mode -1) (global-semantic-show-unmatched-syntax-mode -1) 2. Checking your hooks If you have already checked point (1.) and if you have still problems getting ECB/semantic working properly for your sources you should check the related major-mode hook. Every major-mode X has a hook with name "X-hook" which is evaluated after activating the major-mode (see above, 2.), e.g. the hook for the major-mode `c++-mode' is `c++-mode-hook'. Semantic adds automatically during load-time a special "semantic-setup" to these major-mode hooks(1) in form of a "setup-function". Example: For c and c++ modes semantic adds `semantic-default-c-setup' to `c-mode-hook' and `c++-mode-hook'. If your own Emacs-setup (e.g. in `.emacs' or `site-lisp/site-start.el') overwrites such a major-mode-hook then semantic can not be activated for this major-mode and in consequence ECB can not work properly too! Check if your Emacs-setup uses somewhere `setq' for adding code to a major-mode-hook. *IMPORTANT*: Use `add-hook' instead of `setq'(2)! If your source-files are "running" with correct `major-mode' and correct major-mode hooks ECB and semantic will do what you expect them doing! ---------- Footnotes ---------- (1) Of course only for major-modes supported by semantic! (2) `setq' replaces/overwrites the current value of a hook with the new value whereas `add-hook' *adds* the new value to the old-value of the hook!  File: ecb.info, Node: Non-semantic files, Prev: Setting up semantic, Up: Setting up Emacs 1.2.3 Setup for file types not supported by semantic ---------------------------------------------------- From version 1.94 on ECB supports also parsing and displaying file-contents for file-types not supported by semantic (i.e. there is no semantic-grammar available for such file-types). Such non-semantic file-types can often be parsed by imenu and/or etags. Both of these parsing methods are now supported: ECB can display the results of imenu and/or etags in its Method-buffer. ECB uses for this speedbar-logic. Therefore the following speedbar options takes effect for this feature: - `speedbar-dynamic-tags-function-list' - `speedbar-tag-split-minimum-length' - `speedbar-tag-regroup-maximum-length' - `speedbar-tag-hierarchy-method' Normally there should be no need for you to bother with these options, because the default values are suitable for most situations! But if you are not satisfied with the parsing/display results then you can change some of these options.  File: ecb.info, Node: First steps, Prev: Setting up Emacs, Up: Install and first steps 1.3 First steps after activating ECB first time =============================================== This section of the ECB online-help is displayed automatically by ECB after activating ECB first time and describes what are the first basic steps: 1. Configure where ECB can find your sources: Call `M-x customize-option RET ecb-source-path RET'(1). This lets you customize the option `ecb-source-path' with the customize-feature of Emacs. This opens a customize-buffer where you can insert all the directories where ECB can find your source-files. Save your changes with the button "Save for future sessions" and then throw away this customize-buffer either by killing it with `M-x kill-buffer' or clicking at the button "Finish". 2. Take a look at the most important options of ECB Call `M-x ecb-customize-most-important RET' and see a list of options which you should at least know that these options exist. 3. Read the online-help of ECB: The online-help of ECB is available via - calling `M-x ecb-show-help', - pressing `C-c . h' or - using the menu "ECB". (The section you are currently reading is part of the online-help of ECB) The chapter "Tips and tricks" is also very interesting! 4. Start working with ECB. ---------- Footnotes ---------- (1) This means first hitting the keys `M' (Meta- or Alt-key) and `x' simultaneously, inserting "customize-option" in the minibuffer, hitting RETURN, inserting "ecb-source-path" in the minibuffer and finally hitting RETURN again  File: ecb.info, Node: Overview, Next: Manual usage, Prev: Install and first steps, Up: Top 2 Overview ********** ECB is a global minor-mode which offers a couple of "ECB-windows" for browsing your sources comfortable with the mouse and the keyboard. These "special" windows are also called "interactors" in this manual. ECB offers some basic interactors to browse your sources: - ECB-Directories for browsing directories - ECB-Sources for browsing source-files and a file-history - ECB-Methods for browsing the contents of a source See *Note Basic interactors:: for a detailled description what these basic interactors offer. See *Note ECB-interactors:: for a general introduction in the interactor-concept of ECB. In addition to these "special" ECB-windows you have always an "edit-area" where you can edit your source-files. The edit-area can be divided into several "edit-windows" - as many as you need (*note The edit-area::). And at the bottom of the ECB-frame a persistent "compilation-window" (also called "compile-window") can be displayed (optional), where all the output of Emacs-compilation (compile, grep etc.) is shown (*note Temp- and compile-buffers::). The following "screenshot" illustrates the typical layout of the ECB-frame(1): ------------------------------------------------------------------ | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit-area | | | (can be splitted in several edit-windows) | | Methods | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------------------ | | | Persistent Compilation-window (optional) | | | ------------------------------------------------------------------ ---------- Footnotes ---------- (1) This is only one example of the layouts ECB offers, see *Note Changing the ECB-layout::  File: ecb.info, Node: Manual usage, Next: ECB-interactors, Prev: Overview, Up: Top 3 How to use this manual ************************ *IMPORTANT*: You should have read the chapter *Note Overview:: before going on reading the current chapter. This chapter describes shortly the contents of the following chapters of this manual so maybe you can find faster what you are searching for. All interactors of ECB (*note ECB-interactors::) Gives an introduction into the concept of interactors of ECB, what they are, which different types exist, how they look, how they can be used and last but not least what they do in detail, i.e. explains every interactor of ECB in detail. Activation and Deactivation (*note Activation and Deactivation::) Describes how to activate and deactivate ECB and which different types of activation are possible. Usage of ECB (*note Usage of ECB::) Describes in detail how to use ECB with mouse and keyboard, explains the concept of the edit-area and the persistent compile-window, describe how to change the window-layout and hide and show special windows, which stealthy background-tasks ECB performs and so on... Customizing ECB (*note Customizing::) Gives an overview of the most important options of ECB and tell you something about do's and don'ts concerning customization of ECB. Lists all options of ECB and describe exactly the purpose of them. Submitting a problem report (*note Submitting problem report::) Instructions what to do if you encounters problems with ECB. Upgrading and downloading ECB (*note Upgrading::) Gives an introduction into the automatic option-upgrading-feature of ECB and you can download and install a newer ECB-version from within ECB. Tips and tricks (*note Tips and tricks::) How to deal with special situations and circumstances, so e.g. working with big and small screens, working with large directories, using the builtin version-control-support of ECB, parsing non-semantic-supported sources like perl, using hide-show, working best with eshell and JDEE and some window-managers of Emacs (like escreen or winring) and many more... Entry points for Elisp programmers (*note Elisp programming::) All informations needed by programmers when using some ECB-concepts from within other elisp-libraries. This includes a full description how to use the ECB-independent library tree-buffer.el. Lists also all available hooks and describes with full working example how to program own layouts. Conflicts and bugs of ECB (*note Conflicts and bugs::) Lists all currently known bugs and problems and gives well working work-arounds. Frequently asked Questions (*note FAQ::) Take a look... Command Index (*note Command Index::) List of all interactive commands of ECB Option Index (*note Option Index::) List of all user-customizable options of ECB Concept Index (*note Concept Index::) List of all concepts introduced by ECB  File: ecb.info, Node: ECB-interactors, Next: Activation and Deactivation, Prev: Manual usage, Up: Top 4 All interactors of ECB ************************ ECB displays a number of informational windows that allow for easy source code navigation and overview. These informational windows are called "interactors". Each interactor is displayed in its own special window/buffer which is dedicated and read-only. There are some "basic" interactors (e.g. for browsing directories and sources) and some "add-on" interactors for special purposes like displaying the definition of the current symbol under point. This chapter describes all interactors of ECB in detail. * Menu: * Basic interactors:: Description of the basic interactors * Add-on interactors:: Description of additional interactors  File: ecb.info, Node: Basic interactors, Next: Add-on interactors, Prev: ECB-interactors, Up: ECB-interactors 4.1 The basic interactors of ECB ================================ ECB offers basic interactors for browsing directory-structures, files of a directory and contents of source-files (e.g. methods and variables). These basic interactors are build from a special class of interactors, called "tree-buffer". See *Note Tree-buffer basics:: for more details about the functionality of tree-buffers. See *Note Tree-buffer styles:: to get an impression about the look&feel of these tree-buffers. In the following subsections these basic interactors of ECB will be explained in detail. * Menu: * Tree-buffer basics:: General introduction into tree-buffers * Tree-buffer styles:: Displaying the trees with different styles * ECB Directories-buffer:: Contents of the ECB Directories-buffer * ECB Sources-buffer:: Contents of the ECB Sources/history-buffer * ECB Methods-buffer:: Contents of the ECB Methods-buffer  File: ecb.info, Node: Tree-buffer basics, Next: Tree-buffer styles, Prev: Basic interactors, Up: Basic interactors 4.1.1 General introduction into tree-buffers -------------------------------------------- ECB displays most of its informations (e.g. about directory-structures or file-contents) in so called "tree-buffers" which means the display of such a tree-buffer is structured in a tree consisting of "tree-nodes". Every line in a tree-buffer displays exactly one tree-node. Each node can have any arbitrary number of "children"-nodes. If a tree-node has no children then it is called a "leaf". Each tree-buffer of ECB is displayed in an own special ECB-window/buffer which is read-only ie. not editable. The difference between a natural tree like a fir and an ECB-tree is that the root(-node) of a tree-buffer is not visible but only its children. In the example below the nodes parent-node-1 and parent-node-2 are the children of the invisible root-node. If a tree-node contains at least one child it is displayed with a special expand/collapse-symbol (see the example below). This symbol allows expanding (rsp. collapsing) the tree-node wheras expanding means to display the children-nodes and collapsing means to hide the childrens of a tree-node. Here is an example of a tree-buffer: [+] parent-node-1 -------. [-] parent-node-2 -------| [-] expanded --------| leaf-node-1 -----| leaf-node-2 -----|-----[tree-nodes] leaf-node-3 -----| leaf-node-4 -----| [+] collapsed -------´ | `-----------------[expand/collapse-symbol] In most cases an action is triggered when clicking with the mouse onto a tree-node(1) (e.g. clicking onto "leaf-node-1" or "parent-node-1" in the example above). Which actions depends on the type of the tree-buffer. For example clicking on a tree-node in the ECB-sources-buffer (which is the name of a source-file) opens the relelated file in the edit-area of ECB (*note ECB Sources-buffer::) whereas clicking onto a node in the ECB-methods-buffer (which is the name of a tag in the current source-file displayed in the edit-area) "jumps" to the location of this tag in the source-buffer in the edit-area (*note ECB Methods-buffer::). Almost every interactor of ECB offers a special popup-menu when clicking with the right mouse-button (of course also possible via keyboard, see *Note Using the keyboard::) onto a tree-node (e.g. some senseful actions possible for directory-nodes like grepping this directory or performing version-control actions for this directory or something else). See *Note ECB Directories-buffer::, *Note ECB Sources-buffer::, *Note ECB Methods-buffer:: and *Note Add-on interactors:: for a detailed description which actions are triggered and which popup-menus are offered in all the interactors of ECB. ---------- Footnotes ---------- (1) Of course using the keyboard is also possible, see *Note Using the keyboard::.  File: ecb.info, Node: Tree-buffer styles, Next: ECB Directories-buffer, Prev: Tree-buffer basics, Up: Basic interactors 4.1.2 Displaying the trees with different styles ------------------------------------------------ ECB offers three different styles for the tree-buffers in the ECB-windows. Two of the styles are ascii-based and one style uses images for drawing the tree-structure. * Menu: * Style basics:: Basic knowledge about the styles * Ascii-based styles:: How to customize the ascii-styles * Tree-buffers with images:: Which images are used for the tree * Images for Methods-buffer:: Images for the tags in the Methods-buffer  File: ecb.info, Node: Style basics, Next: Ascii-based styles, Prev: Tree-buffer styles, Up: Tree-buffer styles 4.1.2.1 Basic knowledge about the styles ........................................ There are nine image-names which define the control- and guide-symbols to draw the tree. Here is the list of the allowed image-names and the related corresponding ascii-symbols: - open ("[-]"): The control-symbol displayed for an opened tree-node which has several subnodes. Clicking onto this control closes the node. - close ("[+]"): The control-symbol displayed for a closed tree-node, i.e. an expandable node with subnodes but all subnodes are hidden. Clicking onto this control opened the node and displays its subnodes - if there are any. If it has no subnodes the empty-symbol will be displayed. - empty ("[x]"): The symbol displayed for an empty node. An empty node is a node which could have subnodes but has currently none. - leaf ("*"): The symbol displayed for a node which can not have any subnodes so it is a "leaf" in the tree. - guide (" |"): The symbol used for drawing vertical "guide-lines" for opened nodes. See the example below. - no-guide (" "): Sometimes invisible guide-lines are needed to draw the tree. - end-guide (" `"): The symbol used for the guide-line of the last subnode of an opened node. - handle ("-"): The symbol displayed before every subnode. Each handle is connected to a guide-line - either a normal guide or an end-guide. - no-handle (" "): An invisible handle. A tree will be build-up with these elements like follows: [-] node-with-subnodes (open) |-[+] not-empty-subnode1 (guide+handle+close) |-[x] empty-subnode (guide+handle+empty) `-[-] not-empty-subnode2 (end-guide+handle+open) |-* leaf-1 (no-guide+no-handle+guide+handle+leaf) `-* leaf-2 (no-guide+no-handle+end-guide+handle+leaf)  File: ecb.info, Node: Ascii-based styles, Next: Tree-buffers with images, Prev: Style basics, Up: Tree-buffer styles 4.1.2.2 How to customize the ascii-styles ......................................... The ECB-option `ecb-tree-buffer-style' offers two different styles completely drawn with ascii-controls and -guides. Ascii-style with guide-lines (value `ascii-guides')(1): [-] ECB | [+] code-save `- [-] ecb-images | [-] directories | | [-] height-15 | | | * close.xpm | | | * empty.xpm | | | * leaf.xpm | | `- * open.xpm | | [+] height-17 | | [+] height-19 | `- [+] height-21 | [x] history | [x] methods `- [x] sources Ascii-style without guide-lines (value `ascii-no-guides') - this is the style used by ECB <= 1.96: [-] ECB [+] code-save [-] ecb-images [-] directories [-] height-15 * close.xpm * empty.xpm * leaf.xpm * open.xpm [+] height-17 [+] height-19 [+] height-21 [x] history [x] methods [x] sources The tree-layout of both ascii-styles can be affected with the options `ecb-tree-indent' and `ecb-tree-expand-symbol-before' (the examples above have set 4 for the former and true for the latter one). For the guide-style the face and color of the guide- and handle-symbols can be customized with the option `ecb-tree-guide-line-face' (default is the equal-named face). ---------- Footnotes ---------- (1) For a better look&feel of such a tree-buffer ECB displays only the last subnode of an opened node with a handle!  File: ecb.info, Node: Tree-buffers with images, Next: Images for Methods-buffer, Prev: Ascii-based styles, Up: Tree-buffer styles 4.1.2.3 Which images are used for the tree .......................................... Depending on the value of `ecb-tree-buffer-style' and the image-support of (X)Emacs, the tree-buffer try to use images instead of strings to draw a nice-looking tree. If images can and should be used then the option `ecb-tree-image-icons-directories' tells ECB where to search for suitable image-icons for each of the nine image-names (see above). An image is used for displaying a control with name "XXX" if one of the directories of `ecb-tree-image-icons-directories' contains an image-file with basename "ecb-XXX" and an extension which is supported by (X)Emacs. Currently supported extensions are ".xpm", ".png", ".gif", ".jpeg", ."jpg" and ".xbm". Example: To display the control with name "open" with a suitable image then one of the directories of `ecb-tree-image-icons-directories' must contain a file with name "ecb-open.xpm" or "ecb-open.png" etc. See the description of this option to get all important details how and in which sequence ECB searches the directories of `ecb-tree-image-icons-directories'. ECB comes with predefined default-images usable for every tree-buffer and special images for the Directories- and the Methods-tree-buffer. They are defined in several different heights - so for the most senseful font-heights of a tree-buffer a fitting image-size should be available. The shipped images reside either in the subdirectory "ecb-images" of the ECB-installation or - if ECB is installed as regular XEmacs-package - in the ECB-etc data-directory (the directory returned by evaluating (locate-data-directory "ecb"). If you do not want to change the images then you normally have nothing to do because the default value of `ecb-tree-image-icons-directories' points already to the correct image-directories. A special remark for XEmacs: At least XEmacs 21.14 (but probably previous versions too) has a bug in its display-engine which prevents adjacent images to be displayed correctly. The effect is, that in a row of two or more adjacent images (e.g. end-guide+handle+open - see the tree-example above) always all images are masked by the last one, means only the last one is visible. If at least one normal character (e.g. a space) is placed between two images then the images are displayed correctly. Therefore ECB has implemented the following work-around to get best possible results with XEmacs: open-, close-, empty-, leaf-, guide-, end-guide- and no-guide-images are displayed with images and the handle- and the no-handle-images are displayed with the corresponding ascii-symbols (which is "-" rsp. " "). The face (the color) of the handle-symbol is customizable via the option `ecb-tree-guide-line-face'. This bug is already reported to the XEmacs-team. If your XEmacs has fixed this bug then add the following to your `.emacs'-file (or whereever your emacs-setup is located): (setq tree-buffer-enable-xemacs-image-bug-hack nil) Then ECB uses images without any special work-around with XEmacs too. Just try it - if the tree-buffers look ugly then the XEmacs-bug is probably not fixed correctly.  File: ecb.info, Node: Images for Methods-buffer, Prev: Tree-buffers with images, Up: Tree-buffer styles 4.1.2.4 Special images for the Methods-buffer ............................................. ECB can display all the semantic-tags in the Method-buffer with special icons for methods, variables and classes - each of them with a different icon dependend of the protection of the tag. This feature can be disabled/enabled via the option `ecb-display-image-icons-for-semantic-tags'. All the special images are located in that directory where the option `ecb-tree-image-icons-directories' point to for methods.  File: ecb.info, Node: ECB Directories-buffer, Next: ECB Sources-buffer, Prev: Tree-buffer styles, Up: Basic interactors 4.1.3 ECB Directories-interactor -------------------------------- The ECB directories interactor is for browsing directories. The direct children of the invisible root-node are called "source-path" and can be defined with the option `ecb-source-path'. Each source-path is the starting-node of the complete directory-structure below this path and can be browsed with the directories-interactor. When a sources interactor is contained in the current layout then per default only directories and subdirectories are displayed in the directories tree-buffer (the source-files are displayed in the sources tree-buffer - see *Note ECB Sources-buffer::) but this can be changed with the option `ecb-show-sources-in-directories-buffer'. 4.1.3.1 Usage of the directories interactor ........................................... * Select directories (and - if enabled - source files) in the "ECB-Directories" buffer by clicking a mouse button on the directory name or by hitting RETURN when the cursor is placed on the item line, see *Note Usage of ECB::. IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while clicking with the primary mouse button (*note Using the mouse::) or RETURN (*note Using the keyboard::)) on a directory node in the this buffer then the directory-contents-cache for this directory will be refreshed and actualized. * Directory names with a "[+]" symbol after (or before) them can be expanded/collapsed by clicking on the symbol, pressing the TAB key (*note Using the keyboard::) when the cursor is placed on the package line or clicking a mouse button on the item, see *Note Using the mouse::. * Right clicking on an item will open a popup menu where different operations on the item under the mouse cursor can be performed. This popup-menu offers operations for version-control, dired, grep, some file-operations like creating a directory and commands to make a directory a source-path in the sense of `ecb-source-path'. * Pressing F2 will open the ECB customization group (*note Customizing::) in the edit window. F3 shows the online help in the edit-window. Pressing F4 in the ECB-directories buffer will offer adding a new source-path. When source-files-nodes are displayed in the directories-buffer (see `ecb-show-sources-in-directories-buffer') then for these nodes all descriptions of section *Note ECB Sources-buffer:: are valid. 4.1.3.2 Activating/Displaying the directories interactor ........................................................ Either use one of the predefined layouts which contain the directories interactor (*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new ecb-layout via the command `ecb-create-new-layout' and add a buffer of type "directories" into this new layout (*note Creating a new ECB-layout::). 4.1.3.3 Customizing the directories interactor .............................................. See *Note ecb-directories:: for a list of all options currently available for customizing this interactors to your needs.  File: ecb.info, Node: ECB Sources-buffer, Next: ECB Methods-buffer, Prev: ECB Directories-buffer, Up: Basic interactors 4.1.4 ECB Sources- and history-interactor ----------------------------------------- ECB offers two interactors for displaying source-file-names: The sources- and the history-interactor. The former one displays all source-file names of the currently selected directory of the directories-interactor (*note ECB Directories-buffer::) whereas the latter one displays the names of all currently loaded source-files regardless in which directory they reside so it works as a "history" of source-files. Both the sources- and the history-tree-buffer are "flat" tree-buffers means all nodes are direct children of the invisible root-node and can not be expanded. 4.1.4.1 Usage of the sources/history interactor ............................................... * Source files can be selected by clicking with the primary mouse button (*note Using the mouse::) or hitting RETURN (*note Using the keyboard::) on the source row in the "ECB-Sources" or "ECB-History" windows. The buffer of the selected source-file will be displayed in an edit-window - which one depends on the setting in `ecb-mouse-click-destination'. IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while clicking with the primary mouse button (*note Using the mouse::) or RETURN (*note Using the keyboard::)) on a source row in the ECB-Sources or ECB-History windows then the source will not be displayed in an edit-window but it will be scanned in the background and all its contents (e.g. methods and variables) are listed in the "ECB Methods" window (*note ECB Methods-buffer::. So you can get an overlook over the source without changing the buffer in the edit-window. * Clicking on the source file with the secondary mouse button or C-RETURN (*note Usage of ECB::) will open the source file in another edit window - which one depends on the setting in `ecb-mouse-click-destination'. * Right clicking on a source file (mouse-button 3) will open a popup menu where different operation on the item under the mouse cursor can be performed. This popup-menu offers operations for version-control, dired, grep, filtering the file-names and some file-operations like deleting the related file from disk. 4.1.4.2 Activating/Displaying the sources/history interactor ............................................................ Either use one of the predefined layouts which contain the sources (rsp. history) interactor (*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new ecb-layout via the command `ecb-create-new-layout' and add a buffer of type "sources" (rsp. "history") into this new layout (*note Creating a new ECB-layout::). 4.1.4.3 Customizing the sources/history interactor .................................................. See *Note ecb-sources:: and *Note ecb-history:: for a list of all options currently available for customizing these interactors to your needs.  File: ecb.info, Node: ECB Methods-buffer, Prev: ECB Sources-buffer, Up: Basic interactors 4.1.5 The ECB Methods interactor -------------------------------- The "ECB-Methods" interactor contains all parsed and recognized tags of the current source-buffer. It is called "Method-buffer" because ECB is mostly designed for browsing sourcecode files and for programming-languages these tags are often methods (and variables etc.) To simplify explanations we talk in the following only about methods and variables - but in general the method-buffer can contain any kind of tags (e.g. sections and subsections for texinfo buffers). Per default the content of the methods-interactor is automatically synchronized and updated with current point of the current source-buffer in the edit-area (see `ecb-window-sync' and *Note ECB-window synchronizing::). 4.1.5.1 Usage of the methods interactor ....................................... * When a method/variable is selected with the primary mouse button (*note Using the mouse::) or RETURN (*note Using the keyboard::) the buffer in the edit-window (which one depends on the setting in `ecb-mouse-click-destination') will jump to the method/variable. IMPORTANT: If you use the POWER-click (i.e. hold down the SHIFT-key while clicking with the primary mouse button (*note Using the mouse::) or RETURN (*note Using the keyboard::)) on a node in this buffer then the edit-buffer will be narrowed to the selected tag (see also option `ecb-tag-visit-post-actions'). But this works only for sources parsed by semantic, not by imenu or etags! * Clicking on a method/variable with the secondary mouse button or C-RETURN (*note Usage of ECB::) will jump to the method in another edit window - which one depends on the setting in `ecb-mouse-click-destination'. * Right clicking on a method/variable will open a popup menu where different operation on the item under the mouse cursor can be performed. The popup-menu offers commands for filtering the displayed tree-nodes, hiding/narrowing the related tags in the source-buffer and expanding/collapsing one/all tree-nodes according to a certain expansion-level. 4.1.5.2 Activating/Displaying the methods interactor .................................................... Either use one of the predefined layouts which contain the methods interactor (*note Changing the ECB-layout::) (e.g. via `C-c . l c') or create a new ecb-layout via the command `ecb-create-new-layout' and add a buffer of type "methods" into this new layout (*note Creating a new ECB-layout::). 4.1.5.3 Customizing the methods interactor .......................................... See *Note ecb-methods:: for a list of all options currently available for customizing this interactor to your needs.  File: ecb.info, Node: Add-on interactors, Prev: Basic interactors, Up: ECB-interactors 4.2 Add-on interactors of ECB ============================= This chapter gives detailled informations about available add-on interactors. This includes basic desciptions what they do as well as how to use them. * Menu: * Semantic analyser:: Analyses and displays semantic context * Symboldefinition:: Displays definition of current symbol  File: ecb.info, Node: Semantic analyser, Next: Symboldefinition, Prev: Add-on interactors, Up: Add-on interactors 4.2.1 Displaying the current semantic context --------------------------------------------- The cedet-suite contains the "semantic analyzer" which is a library tool that performs context analysis and can derive useful information. See the related node in the info-manual of cedet/semantic for more detailed informations about this tool. The analyzer output can be used through a special ECB-interactor. This interface lists details about the analysis, such as the current function, local arguments and variables, details on the prefix (the symbol the cursor is on), and a list of all possible completions (see `semantic-analyze-possible-completions' for more details about completions available via the semantic-analyser). Per default the content of the analyser-interactor is automatically synchronized and updated with current point of the current source-buffer in the edit-area (see `ecb-window-sync' and *Note ECB-window synchronizing::). The analyser-interactor is of type tree-buffer. See *Note Tree-buffer basics:: for basic informations how to use such a tree-buffer. 4.2.1.1 Usage of the analyser-interactor ........................................ * When a node-name in the "Context"-bucket is selected with the primary mouse button (*note Using the mouse::) or RETURN (*note Using the keyboard::) the buffer in the edit-window (which one depends on the setting in `ecb-mouse-click-destination') will jump to the related entry. For strongly typed languages, this means you will jump to the definition of the variable, slot, or type definition. * Clicking on a node-name in the "Context"-bucket with the secondary mouse button or C-RETURN (*note Usage of ECB::) will jump to the related entry in another edit window - which one depends on the setting in `ecb-mouse-click-destination'. * If you click on a node-name in the "Completions"-bucket, then the text that was recently analyzed will be replaced with the name of the tag that was clicked on in the analyser-interactor. * Right clicking with the mouse (or with the keyboard, see *Note Using popup-menus::) onto a tree-node opens a popup-menu which allows to display additional (if available) informations to the current node. 4.2.1.2 Interactive commands of the analyser-interactor ....................................................... ECB offers the following commands for the analyser-interactor: - `ecb-analyse-buffer-sync' - `ecb-goto-window-analyse' - `ecb-maximize-window-analyse' See *Note Interactive ECB commands:: for details about these commands. But you should not have any need to call `ecb-analyse-buffer-sync' directly because ECB automatically syncronizes the analyser-interactor with current active edit-buffer. 4.2.1.3 Activating/Displaying the analyser-interactor ..................................................... Either use one of the predefined layouts "left-analyse" or "leftright-analyse" (e.g. via `C-c . l c') or create a new ecb-layout via the command `ecb-create-new-layout' and add a buffer of type "other" and name "analyse" into this new layout (*note Creating a new ECB-layout::). 4.2.1.4 Customizing the analyser interactor ........................................... See *Note ecb-analyse:: for a list of all options currently available for customizing this interactor to your needs.  File: ecb.info, Node: Symboldefinition, Prev: Semantic analyser, Up: Add-on interactors 4.2.2 Displaying the definition of the current symbol under point -----------------------------------------------------------------  File: ecb.info, Node: Activation and Deactivation, Next: Usage of ECB, Prev: ECB-interactors, Up: Top 5 Activation and Deactivation ***************************** This chapter describes all aspects of activating and deactivating ECB. * Menu: * Standard activation:: How to manually (de)activate ECB * Automatic activation:: Automatically (de)activating ECB *IMPORTANT*: Regardless of the activation-type (standard or automatic) the activation-process of ECB is always completely failure-save. This means any error during any step of the activation-process forces a complete cleanup (e.g. removing hooks, disabling advices etc.) of all settings ECB did (e.g. adding hooks, activating advices etc.) until the failure. Therefore if ECB-activation stops cause of a failure then you can be sure that your Emacs has the same state as before the ECB-activation-start!  File: ecb.info, Node: Standard activation, Next: Automatic activation, Prev: Activation and Deactivation, Up: Activation and Deactivation 5.1 Standard activation and deactivation ======================================== Call `M-x ecb-activate' and `M-x ecb-deactivate' to activate or deactivate ECB(1). If you want ECB started in a new frame see the option `ecb-new-ecb-frame' (default is nil). `ecb-activate' always raises and selects the ECB-frame even if ECB is already started. Because ECB is a global minor-mode it can also be (de)activated/toggled by `M-x ecb-minor-mode'. The following sequence of hooks is evaluated during activation of ECB: 1. `ecb-before-activate-hook' 2. 3. `ecb-activate-before-layout-draw-hook' 4. `ecb-redraw-layout-before-hook' 5. 6. `ecb-redraw-layout-after-hook' 7. `ecb-activate-hook' The following sequence of hooks is evaluated during deactivation of ECB: 1. `ecb-before-deactivate-hook' 2. 3. `ecb-deactivate-hook' ---------- Footnotes ---------- (1) Activation is also possible via the menu "Tools -> Start Code Browser (ECB)".  File: ecb.info, Node: Automatic activation, Prev: Standard activation, Up: Activation and Deactivation 5.2 Automatic activation and deactivation ========================================= There are two ways for auto. (de)activation ECB after Emacs-start and for different window-configurations. `ecb-auto-activate' This option is for auto. activating ECB after Emacs-startup. Set this to not nil and ECB will automatically be started after Emacs comes up. `window-manager support' The window-manager support of ECB deactivates ECB when going to another window-configuration and reactivates ECB when coming back to the ECB-window-configuration. For all details about this see *Note Window-managers and ECB::.  File: ecb.info, Node: Usage of ECB, Next: Customizing, Prev: Activation and Deactivation, Up: Top 6 Usage of ECB ************** This chapter describes in a detailed manner all aspects of using the Emacs Code Browser. * Menu: * Using the mouse:: Working with the mouse * Using the keyboard:: Working with the keyboard * The edit-area:: How to use the edit-area * Temp- and compile-buffers:: Displaying temp- and compilation-buffers * The other window:: How the ``other window'' is determined * The Methods buffer:: Using and customizing the Methods-buffer * Filtering the tree-buffers:: Applying filters to the ECB-tree-buffers * The ECB-layout:: Changing, customizing, redrawing, creating * Hiding the ECB windows:: Hiding/Showing the ECB-windows * Maximizing the ECB windows:: Maximizing the ECB-windows * Back/forward navigation:: Back- and forward navigation like a browser * ECB-window synchronizing:: Auto./manual synchronizing the ECB-windows * Stealthy background tasks:: Stealthy background-tasks of ECB * Interactive ECB commands:: All interactive user-commands of ECB  File: ecb.info, Node: Using the mouse, Next: Using the keyboard, Prev: Usage of ECB, Up: Usage of ECB 6.1 Working with the mouse in the ECB-windows ============================================= Normally you get best usage if you use ECB with a mouse. ECB distinguishes between a "primary" and a "secondary" mouse-button. With the option `ecb-primary-secondary-mouse-buttons' the following combinations of primary and secondary mouse-buttons are possible: - primary: mouse-2, secondary: C-mouse-2(1). This is the default. - primary: mouse-1, secondary: C-mouse-1 - primary: mouse-1, secondary: mouse-2 If you change this during ECB is activated you must deactivate and activate ECB again to take effect. 6.1.1 The primary mouse-button ------------------------------ A click with the primary button causes the main effect in each ECB-buffer: - ECB Directories: Expanding/collapsing nodes and displaying files in the ECB-Sources buffer. - ECB sources/history: Opening the file in that edit-window specified by the option `ecb-mouse-click-destination'. - ECB Methods: Jumping to the method in that edit-window specified by the option `ecb-mouse-click-destination'. 6.1.2 The POWER- or SHIFT-click ------------------------------- A click with the primary mouse-button while the SHIFT-key is pressed is called the POWER-click and does the following (depending on the ECB-buffer where the POWER-click occurs): - ECB Directory: Refreshing the directory-contents-cache (see `ecb-cache-directory-contents'). - ECB sources/history: Only displaying the source-contents in the method-buffer but not displaying the source-file in an edit-window. This means it opens the clicked source only in the background and shows all its methods/variables in ECB-Methods; the buffer of the edit-window is not changed! This is very useful to get only an overlook for a certain source. - ECB Methods: Narrowing to the clicked method/variable/ect... (see `ecb-tag-visit-post-actions'). But this works only for sources parsed by semantic, not by imenu or etags! Per default the complete node-name of an item in a tree-buffer is displayed in the echo-area if the mouse moves over it, regardless if the related window is the active one or not. You get the same effect always after a POWER-click. In general: Via `ecb-show-node-info-in-minibuffer' you can specify in a detailed manner for every ECB tree-buffer when and which node-info should be displayed in the minibuffer. 6.1.3 The secondary mouse-button -------------------------------- The secondary mouse-button is for opening (jumping to) the file in another edit-window (see the documentation of the option `ecb-mouse-click-destination'). 6.1.4 The right mouse-button ---------------------------- In each ECB-buffer mouse-3 (= right button) opens a special context popup-menu for the clicked item where you can choose several senseful actions. With the options `ecb-directories-menu-user-extension', `ecb-sources-menu-user-extension', `ecb-methods-menu-user-extension' and `ecb-history-menu-user-extension' you can add statically new commands to the popup-menus. See the docstring of `ecb-directories-menu-user-extension' for more details. With the options `ecb-directories-menu-user-extension-function', `ecb-sources-menu-user-extension-function', `ecb-methods-menu-user-extension-function' and `ecb-history-menu-user-extension-function' you can add new commands to the popup-menus in a dynamic manner. See the docstring of `ecb-directories-menu-user-extension-function' for more details. With the options `ecb-directories-menu-sorter', `ecb-sources-menu-sorter', `ecb-methods-menu-sorter' and `ecb-history-menu-sorter' you can even re-arrange all the entries of the popup-menus. 6.1.5 Horizontal scrolling with the mouse ----------------------------------------- In each tree-buffer of ECB you can easily scroll left and right with the mouse if the option `ecb-tree-easy-hor-scroll' is not `nil'. The reason for this is: XEmacs has horizontal scroll-bars so invisible parts beyond the right window-border of a tree-buffer can always made visible very easy. GNU Emacs does not have hor. scroll-bars so especially with the mouse it is quite impossible to scroll smoothly right and left. The functions `scroll-left' and `scroll-right' can be annoying and are also not bound to mouse-buttons. ECB offers three ways for smoothly hor. scrolling with GNU Emacs if `ecb-tree-easy-hor-scroll' is a positive integer-value S: * In all ECB-tree-buffers the keys `M-mouse-1' and `M-mouse-3' are bound to scrolling left rsp. right with scroll-step S. * Clicking with mouse-1 or mouse-2 onto the edge of the modeline has the same effect, i.e. if you click with mouse-1 onto the left \(resp right) edge of the modeline you will scroll left \(resp. right) with scroll-step S. * Additionally `C-M-mouse-1' and `C-M-mouse-3' are bound to scrolling left rsp. right with scroll-step `window-width' - 2. This is NOT done for XEmacs cause of its horizontal scrollbars. If you want scrolling left and right with the mouse in XEmacs then activate the horizontal scrollbars. ---------- Footnotes ---------- (1) means mouse-2 while CTRL-key is pressed.  File: ecb.info, Node: Using the keyboard, Next: The edit-area, Prev: Using the mouse, Up: Usage of ECB 6.2 Working with the keyboard in the ECB-windows ================================================ ECB offers the `ecb-mode-map' which binds the most important functions of ECB to keys so you can easily use ECB in every window(1) without a mouse. IMPORTANT: Do not modify `ecb-mode-map' directly! The option `ecb-key-map' defines all ECB keybindings, including a common prefix-key (This is by default `C-c .'). If there are conflicts with other minor-modes or packages you can define very easy another prefix. Please read carefully the description of `ecb-key-map' (*note ecb-general::).! The following sections describe special topics about using the keyboard in the ECB-tree-buffers: * Menu: * Navigation/Selection:: Keyboard navigation/selection in a tree-buffer * Incremental search:: Find nodes as fast as possible * Personal tree-keybindings:: Adding personal keybindings to a tree-buffer * Using popup-menus:: Using the popup-menus from keyboard. ---------- Footnotes ---------- (1) Regardless if a tree-window or an edit-window  File: ecb.info, Node: Navigation/Selection, Next: Incremental search, Prev: Using the keyboard, Up: Using the keyboard 6.2.1 Navigation and Selection in a tree-buffer ----------------------------------------------- In the ECB-buffers RETURN and TAB are the most important keys: * RETURN does the same as the primary button and C-RETURN does the same as the secondary button. S-RETURN is the same as the SHIFT-click or POWER-click. The terms "primary", "secondary", "SHIFT-" and "POWER-click" are explained in *Note Using the mouse::. See also the option `ecb-tree-do-not-leave-window-after-select' and the function `ecb-toggle-do-not-leave-window-after-select' which is bound to `C-t' in each tree-buffer of ECB! For all RETURN (and S-RETURN and C-RETURN) hits the position of the point within the current node-line is irrelevant! This is for conveniance. * TAB always expands or collapses expandable nodes. The RETURN and TAB keys can not be (re)defined with `ecb-key-map'! If you set `ecb-tree-navigation-by-arrow' to not nil then the arrow keys work in the ECB tree-window in the following smart way: * Left-arrow: If node is expanded then it will be collapsed otherwise (i.e. current node is either not expandable or not expanded) point jumps to the next "higher" node in the hierarchical tree (higher means the next higher level or - if no higher level available - the next higher node on the same level). * Right-arrow: If node is expandable but not expanded then it will be expanded. Otherwise (i.e. current node is either not expandable or already expanded) point jumps to the next following node (which is the first subnode in case of an already expanded node or simply the next node in the following line). * Up- and down-arrow: Point jumps to the first character of the previous (up) rsp. next node (down). "First" character means either the first character of the expand-symbol (in case `ecb-tree-expand-symbol-before' is not nil) or of the displayed node-name. Or with other words: The first non-indentation and non-guide-line (see `ecb-tree-buffer-style') character of a node (*note Tree-buffer styles::).  File: ecb.info, Node: Incremental search, Next: Personal tree-keybindings, Prev: Navigation/Selection, Up: Using the keyboard 6.2.2 Incremental search for a node in current tree-buffer ---------------------------------------------------------- Each display-able key (e.g. all keys normally bound to `self-insert-command') is appended to the current search-pattern. The tree-buffer tries to jump to the first node which matching the current search-pattern either as substring or as prefix (see below). If no match is found then nothing is done. There are some special keys: * `backspace' and `delete': Delete the last character from the search-pattern. * `home': Delete the complete search-pattern * `end': Expand either to a complete node if current search-pattern is already unique or expands to the greatest common substring or prefix of the nodes. If there are at least two nodes with the same greatest common-prefix than every hit of `end' jumps to the next node with this common prefix. For better overlooking the current search-pattern is shown in the echo area. After selecting a node with RET the search-pattern is cleared out. With `ecb-tree-incremental-search' you can specify if the current search-pattern must be a real prefix of the node (default) or if any substring is matched. For faster and easier finding the right node in a ecb-window the incremental search ignores the following non interesting stuff: - any leading spaces - expand/collapse-buttons: [+] rsp. [-] - protection-signs (+, -, #) in the method-window if uml-notation is used - variables types or return-types in front of variable- or method-names. - const specifier for variables This means: Just type in the prefix (rsp. a substring) of a class-, variable-, method-, directory- or filename and ECB will bring you as fast as possible to the node you want. Incremental node-search uses the value of `case-fold-search'. Tip: The `ecb-minor-mode' offers you in the `ecb-mode-map' (customizable via `ecb-key-map') some keys for selecting every window of the ecb-frame. This makes window-selection a child´s play. For example you can jump into the method-window by hitting `C-c . gm'.  File: ecb.info, Node: Personal tree-keybindings, Next: Using popup-menus, Prev: Incremental search, Up: Using the keyboard 6.2.3 Adding personal keybindings for the tree-buffers ------------------------------------------------------ There are five hooks which can be used for adding personal keybindings to the ECB tree-buffers: - `ecb-common-tree-buffer-after-create-hook' - `ecb-directories-buffer-after-create-hook' - `ecb-sources-buffer-after-create-hook' - `ecb-methods-buffer-after-create-hook' - `ecb-history-buffer-after-create-hook' These hooks are called directly after tree-buffer creation so they can be used to add personal local keybindings(1) either to all tree-buffers (`ecb-common-tree-buffer-after-create-hook') or just to a certain tree-buffer. Here is a list which keys MUST NOT be rebound: * `RET' and all combinations with `Shift' and `Ctrl': Used for selecting nodes in all tree-buffers. * `TAB': Used for expanding/collapsing nodes in all tree-buffers. * `C-t': Used for toggling "do not leave window after selection" in all tree-buffers, see command `ecb-toggle-do-not-leave-window-after-select'. * All self-inserting characters: Used for easy and fast navigation in all tree-buffers, *Note Incremental search::. * `F2', `F3', `F4': Used for customizing ECB, adding source-path in the directories buffer. The following example binds `C-a' to some useful code in ALL tree-buffers and `C-d' to even more useful code ONLY in the directories buffer: (add-hook 'ecb-common-tree-buffer-after-create-hook (lambda () (local-set-key (kbd "C-a") (lambda () (interactive) (message "ECB is great!"))))) (add-hook 'ecb-directories-buffer-after-create-hook (lambda () (local-set-key (kbd "C-d") (lambda () (interactive) (message "ECB is wonderful!"))))) ---------- Footnotes ---------- (1) To be more general: They can be used to run any arbitrary lisp code after a tree-buffer creation!  File: ecb.info, Node: Using popup-menus, Prev: Personal tree-keybindings, Up: Using the keyboard 6.2.4 Using the popup-menu of a tree-buffer from keyboard. ---------------------------------------------------------- A popup-menu of a tree-buffer can be activated from keyboard with the command `tree-buffer-show-menu-keyboard' which is bound to `M-m' in every tree-buffer. How the popup-menu is displayed depends if this command is called with a prefix-argument or not: If called without a prefix-arg then the popup-menu is displayed graphically as if it would be activated via mouse (for GNU Emacs this works perfectly but for XEmacs there is a bug which results in a wrong menu-position - but the menu itself works also with XEmacs). If called with a prefix-arg (`C-u M-m') then the popup-menu is displayed with the tmm-mechanism (like the Emacs-[menu-bar] is displayed when `tmm-menubar' is called). This tmm-display is only available for GNU Emacs.  File: ecb.info, Node: The edit-area, Next: Temp- and compile-buffers, Prev: Using the keyboard, Up: Usage of ECB 6.3 Working with the edit-window(s) of the edit-area ==================================================== ECB offers you all what you need to work with the edit-area as if the edit-windows of the edit-area would be the only windows of the ECB-frame. ECB offers you to advice the following functions so they work best with ECB: - `other-window' - `delete-window' - `delete-other-windows' - `delete-windows-on' - `split-window-horizontally' - `split-window-vertically' - `split-window' - `display-buffer' - `switch-to-buffer' - `switch-to-buffer-other-window' - `other-window-for-scrolling' - `balance-windows' The behavior of the adviced functions is (slightly simplified): * All these adviced functions behaves exactly like their corresponding original functions but they always act as if the edit-window(s) of ECB would be the only window(s) of the ECB-frame. So the edit-window(s) of ECB seems to be a normal Emacs-frame to the user. This means that you can split and delete edit-windows without any restriction - ECB ensures that neither the special ECB-windows nor the compile-window will be damaged. * If there is a persistent compile-window (*note Temp- and compile-buffers::) then all compilation-buffers in the sense of `ecb-compilation-buffer-p' will be displayed in the compile-window. * If called in another frame than the ECB-frame these functions behave exactly like the not adviced original versions! ATTENTION: If you want to work within the edit-area with splitting and unsplitting (i.e. deleting) the edit-window(s) it is highly recommended to use the adviced-functions of ECB instead of the original Emacs-functions (see above). Per default ECB advices all of the functions mentioned above but with the option `ecb-advice-window-functions' you can customizes which functions should be adviced by ECB. Please read carefully the documentation of this option! Another interesting option in the context of the edit-window and these adviced functions is `ecb-layout-always-operate-in-edit-window'! 6.3.1 Documentation of the adviced window functions --------------------------------------------------- This section describes for every adviced window function (s.a.) how it differs from the original version. Only the differences are mentioned, so if you want the full documentation of such a function call `describe-function' or `C-h f'. -- Command: other-window ARG &optional ALL-FRAMES Around-advice `ecb': The ECB-version of `other-window'. Works exactly like the original function with the following ECB-adjustment: The behavior depends on `ecb-other-window-behavior'. -- Command: delete-window &optional WINDOW Around-advice `ecb': The ECB-version of `delete-window'. Works exactly like the original function with the following ECB-adjustment: If optional argument WINDOW is nil (i.e. probably called interactively): If called in a splitted edit-window then it works like as if all the edit-windows would be the only windows in the frame. This means the current edit-window which contains the point will be destroyed and its place will be occupied from another one. If called in an unsplitted edit-window then nothing is done. If called in the compile-window of ECB then the compile-window will be hidden (like with `ecb-toggle-compile-window'). If called in an ecb-window of the current ECB-layout there are two alternatives: * If the function is contained in `ecb-layout-always-operate-in-edit-window' the right edit-window is selected (depends on the value of the option `ecb-mouse-click-destination') and does then it´s job. * Otherwise the behavior depends on the value of the option `ecb-advice-window-functions-signal-error'. If optional argument WINDOW is a living window (i.e. called from program): If WINDOW is an edit-window then this window is deleted, if WINDOW is the compile-window then it will be hidden and otherwise the behavior depends on `ecb-advice-window-functions-signal-error'. -- Command: delete-other-windows &optional WINDOW Around-advice `ecb': The ECB-version of `delete-other-windows'. Works exactly like the original function with the following ECB-adjustment: If optional argument WINDOW is nil (i.e. probably called interactively): If called in a splitted edit-window then it works like as if all the edit-windows would be the only windows in the frame. This means all other edit-windows besides the current edit-window which contains the point will be destroyed and the current edit-window fills the whole edit-area. Neither the special ecb-windows nor the compile-window will be destroyed! * If called in an unsplitted edit-window then either the compile-window will be hidden (if there is one) otherwise nothing is done. * If called in one of the ecb-windows then the current one is maximized, i.e. the other ecb-windows (not the edit-windows!) are deleted. * If called in the compile window there are two alternatives: - If the function is contained in `ecb-layout-always-operate-in-edit-window' the right edit-window is selected (depends on the value of the option `ecb-mouse-click-destination') and then it does it´s job. - Otherwise the behavior depends on the value of the option `ecb-advice-window-functions-signal-error'. If optional argument WINDOW is a living window (i.e. called from program): If WINDOW is an edit-window then this window is maximized (i.e. the other edit-window is deleted) if there are more at least 2 edit-windows otherwise the compile-window is deleted (if there is one). If WINDOW is an ecb-window then only the other ecb-windows are deleted and in all other cases the behavior depends on `ecb-advice-window-functions-signal-error'. -- Command: delete-windows-on BUFFER &optional FRAME Around-advice `ecb': The ECB-version of `delete-windows-on'. Works exactly like the original function with the following ECB-adjustment: An error is reported if BUFFER is an ECB-tree-buffer. These windows are not allowed to be deleted. -- Command: split-window &optional WINDOW SIZE HORFLAG Around-advice `ecb': The ECB-version of `split-window'. Works exactly like the original function with the following ECB-adjustment: If called for a not-edit-window in the `ecb-frame' it stops with an error if `split-window' is not contained in the option `ecb-layout-always-operate-in-edit-window'! Besides this (e.g. called for a window in another frame than the `ecb-frame') it behaves like the original version. -- Command: split-window-horizontally Around-advice `ecb': The ECB-version of `split-window-horizontally'. Works exactly like the original function with the following ECB-adjustment: If called in any other window of the current ECB-layout it stops with an error if this `split-window-horizontally' is not contained in the option `ecb-layout-always-operate-in-edit-window'! -- Command: split-window-vertically Around-advice `ecb': The ECB-version of `split-window-vertically'. Works exactly like the original function with the following ECB-adjustment: If called in any other window of the current ECB-layout it stops with an error if this `split-window-vertically' is not contained in the option `ecb-layout-always-operate-in-edit-window'! -- Command: display-buffer BUFFER &optional NOT-THIS-WINDOW FRAME Around-advice `ecb': Makes this function compatible with ECB if called in or for the ecb-frame. It displays all buffers which are "compilation-buffers" in the sense of `ecb-compilation-buffer-p' in the compile-window of ECB. If the compile-window is temporally hidden then it will be displayed first. If there is no compile-window (`ecb-compile-window-height' is nil) then it splits the edit-window if unsplitted and displays BUFFER in another edit-window but only if `pop-up-windows' is not nil (otherwise the edit-window will not be splitted). All buffers which are not "compilation-buffers" in the sense of `ecb-compilation-buffer-p' will be displayed in one of the edit-area and `display-buffer' behaves as if the edit-windows would be the only windows in the frame. If BUFFER is contained in `special-display-buffer-names' or matches `special-display-regexps' then `special-display-function' will be called (if not nil). But this behavior depends on the value of the option `ecb-ignore-special-display'. The values of `same-window-buffer-names' and `same-window-regexps' are supported as well. See the option `ecb-ignore-display-buffer-function'! If called for other frames it works like the original version. -- Command: switch-to-buffer BUFFER &optional NORECORD Around-advice `ecb': The ECB-version of `switch-to-buffer'. Works exactly like the original but with the following enhancements for ECB: "compilation-buffers" in the sense of `ecb-compilation-buffer-p' will be displayed always in the compile-window of ECB (if `ecb-compile-window-height' is not nil) - if the compile-window is temporally hidden then it will be displayed first. If you do not want this you have to modify the options `ecb-compilation-buffer-names', `ecb-compilation-major-modes' or `ecb-compilation-predicates'. If called for non "compilation-buffers" (s.a.) from outside the edit-area of ECB it behaves as if called from an edit-window if `switch-to-buffer' is contained in the option `ecb-layout-always-operate-in-edit-window'. Otherwise an error is reported. -- Command: switch-to-buffer-other-window BUFFER &optional FRAME Around-advice `ecb': The ECB-version of `switch-to-buffer-other-window'. Works exactly like the original but with some adaptions for ECB so this function works in a "natural" way: If called in any special ecb-window of the current ECB-layout then it goes always to an edit-window (which one depends on the setting in `ecb-mouse-click-destination') and then goes on as if called from this edit-window. If a compile-window is used (i.e. `ecb-compile-window-height' is not nil) then "compilation-buffers" in the sense of `ecb-compilation-buffer-p' are always displayed in the compile-window. If the compile-window is temporally hidden then it will be displayed first. If no compile-window is used it behaves like the original. If called from within the compile-window then "compilation-buffers" will be displayed still there and all other buffers are displayed in one of the edit-windows - if the destination-buffer is already displayed in one of the edit-windows then this one is used otherwise it behaves like the original. If called within an edit-window it behaves like the original function except for compilation-buffers (if a compile-window is used, see above). -- Function: other-window-for-scrolling Around-advice `ecb': This function determines the window which is scrolled if any of the "other-window-scrolling-functions" is called (e.g. `scroll-other-window'): If the option `ecb-scroll-other-window-scrolls-compile-window' is not nil (maybe set by `ecb-toggle-scroll-other-window-scrolls-compile') and a compile-window is visible then always the current buffer in the compile-window is scrolled! Otherwise it depends completely on the setting in `ecb-other-window-behavior'. -- Command: balance-windows Around-advice `ecb': When called in the `ecb-frame' then only the edit-windows are balanced.  File: ecb.info, Node: Temp- and compile-buffers, Next: The other window, Prev: The edit-area, Up: Usage of ECB 6.4 Temp- and compile-buffers display in ECB ============================================ If you call any help in Emacs, e.g. by calling `describe-function', or if you do a completion in the minibuffer, then Emacs displays the result-buffer in another window. This behavior you have also in ECB. 6.4.1 Standard Emacs behavior ----------------------------- If the edit-area is already splitted into at least two edit-windows then the temp-buffer is displayed in another edit-window otherwise the edit-area will be splitted first into two edit-windows, one above the other. The variables `temp-buffer-max-height' and `temp-buffer-resize-mode' (for GNU Emacs) and `temp-buffer-shrink-to-fit' (for XEmacs) work also correctly with ECB. Same for all compilation output-buffers (e.g. after a `compile' or `grep') and the variable `compilation-window-height'. This is default behavior of ECB. But there is also another way to display such buffers: Using a persistent extra window at the bottom of the ECB-frame: 6.4.2 Using a persistent compile window --------------------------------------- With the option `ecb-compile-window-height' you can define if the ECB layout should contain per default a compile-window at the bottom (just specify the number of lines which should be used for the compile-window at the bottom of the frame). If "yes" ECB displays all buffers for which the function `ecb-compilation-buffer-p' returns not nil (e.g. all output of compilation-mode (compile, grep etc.) or all temp-buffers like *Help*-buffers) in this special window. In general: With the options `ecb-compilation-buffer-names', `ecb-compilation-major-modes' and `ecb-compilation-predicates' you can define which buffers should be displayed in the compile-window of ECB (for example if you call `switch-to-buffer' or `display-buffer' or if you run `compile' or if you display *Help*-buffers). Per default these are all temp-buffers like *Help*-buffers, all compile- and grep buffers, *Occur*-buffers etc. See the default values of these options. With the command `ecb-toggle-compile-window' (bound to `C-c . \') you can toggle the visibility of the compile-window (*note Interactive ECB commands::). There are some more useful options and commands related to the compile-window of ECB (to see all options for the compile-window see the customization group *Note ecb-compilation::): * With the option `ecb-compile-window-temporally-enlarge' you can allow Emacs to enlarge temporally the ECB-compile-window in some situations. Please read the comment of this option. See also the description of the command `ecb-toggle-compile-window-height'. * With the option `ecb-enlarged-compilation-window-max-height' you specify how `ecb-toggle-compile-window-height' should enlarge the compile-window. * With the command `ecb-cycle-through-compilation-buffers' (*note Interactive ECB commands::) you can cycle through all current open compilation-buffers (in the sense of `ecb-compilation-buffer-p') very fast. ECB offers the same compile-window functionality regardless if the ECB-window are hidden or not. The state of the compile-window will be preserved when toggling the ecb-windows or when maximizing one ecb-windows! So you have the advantage of one special window for all help-, grep or compile-output (see above) also when the ecb-windows are hidden - a window which will not be deleted if you call `delete-other-windows' (bound to `C-x 1') for one of the edit-windows. In general: All features of the compile-window work with hidden ecb-windows exactly as when the ecb-windows are visible. 6.4.3 What to do if there are problems with the compile-window -------------------------------------------------------------- Normally displaying temp- and compilation-buffers (or more general: displaying buffer for which `ecb-compilation-buffer-p' is not nil) should work reliable. But if there are problems which you can not handle with the options `ecb-compilation-buffer-names', `ecb-compilation-major-modes' or `ecb-compilation-predicates' then please go on like follows: 1. Set the option `ecb-layout-debug-mode' to not nil. 2. Reproduce the wrong behavior exactly by repeating all the operations which lead to the problem. If possible then restart Emacs before reproducing the problem so you can begin from the beginning! 3. Now send immediately a bug report with `ecb-submit-problem-report'. 4. Set `ecb-layout-debug-mode' back to nil if you do not want further debugging output in the *Messages* buffer" 6.4.4 Handling special-display-buffers -------------------------------------- Emacs offers three options for a special-display-handling of certain buffers: `special-display-function', `special-display-buffer-names' and `special-display-regexps' (see the Emacs manual for a description of these options). ECB offers an option `ecb-ignore-special-display' for specification in which situations ECB should take account for the values of these special-display-options. Default-behavior of ECB is to ignore these special-display-options when a persistent compile-window is active (i.e. `ecb-compile-window-height' is not nil). But with `ecb-ignore-special-display' you can tell ECB, that either always the special-display-options should be ignored as long as ECB is active or that they should be never igored regardless if a persistent compile-window is set or not. In the latter case using `display-buffer' or `pop-to-buffer' takes always account for the values of these options - like the original behavior of Emacs.  File: ecb.info, Node: The other window, Next: The Methods buffer, Prev: Temp- and compile-buffers, Up: Usage of ECB 6.5 How the "other window" is determined by ECB =============================================== Normally all windows in an Emacs-frame are arranged in a cyclic order and window-selecting-commands like `other-window' or window-scrolling-commands like `scroll-other-window' choose simply the next(1) window after the current window as "other window". 6.5.1 "Other window"-basics in ECB ---------------------------------- With a typical window-layout of ECB such a cyclic order of *all* windows in the ECB-frame does not make sense because it would be not very intuitive and against that what the user wants to "say" when calling `other-window' or `scroll-other-window'. Therefore ECB divides the whole set of windows of the ECB-frame in several subsets: * The edit-windows of the edit-area * The special tree-windows for browsing-tasks * The compile-window at the bottom (if there is one) * The minibuffer-window of the ECB-frame (if active) Each of these subsets will be treated as a cyclic ordered subset, i.e. all windows in each of these subsets are ordered as the function `walk-windows' would visit the windows when the windows of a subset would be the only windows of a frame(2). 6.5.2 Builtin "other window" behaviors of ECB --------------------------------------------- ECB now offers to specify the behavior of commands like `other-window' or `scroll-other-window' within the ECB-frame. This can be done with the option `ecb-other-window-behavior'. This option offers several builtin behaviors: * All windows of the ECB-frame are considered ECB will cycle through all windows of the ECB-frame or scroll simply the next window in the ECB-frame, means it behaves like the original `other-window' rsp. the original `other-window-for-scrolling'. * Only the windows of the edit-area are considered ECB will only cycle through the edit-windows of ECB or only scroll another edit-window. If the selected window is not an edit-window then all windows are taken into account. * The edit-windows and the compile-window are considered Like above but the compile-window will be added to the subset of the edit-windows. * Behave as smart and intuitive as possible This is the default behavior of ECB. ECB tries to choose the `other-window'-destination or the "other window" to scroll in a smart and intuitive way: If point is in one of the edit-windows and if the edit-area is splitted then always the "next" edit-window is choosen (whereas the next edit-window of the last edit-window is the first edit-window)- if the edit-area is unsplitted then the compile-window is used if there is one. In the context of an `other-window'-call the ARG of `other-window' will be taken into account. If one of the special ecb-windows is selected then always the "next" ecb-window is choosen (whereas the next ecb-window of the last ecb-window is the first ecb-window). In the context of an `other-window'-call the ARG of `other-window' will be taken into account. If there is only one ecb-window then ECB considers also the edit-windows. If the compile-window is selected then always the last edit-window which had the point will be used unless `other-window' has been called with a prefix-argument unequal 1. Regardless of the different behaviors above ECB handles the situation of an active minibuffer during a call to `other-window' or `scroll-other-window' like follows: If the minibuffer-window is selected then ECB always chooses the window `minibuffer-scroll-window' points to (when this variable is set, otherwise the compile-window or the last selected edit-window is choosen) when the called command is called to choose the 1. next window (always true for scrolling another window or true when `other-window' called without prefix-arg or with prefix-arg equal 1). Otherwise the window ARG steps away is choosen (in case of `other-window'). If there is an active minibuffer but the minibuffer-window is not selected then `other-window' and `scroll-other-window' behave like the original version. 6.5.3 User-defined "other window" behavior ------------------------------------------ In addition to the builtin "other window" behaviors ECB offers a user to completely define for himself how ECB should choose another window for scrolling it or selecting it. This can be done with the option `ecb-other-window-behavior' too because this option can also have a function-symbol as value: Such a function gets seven arguments: 1. A canonical list of all currently visible windows of the `ecb-frame' 2. A canonical list of all currently visible edit-windows 3. A canonical list of all currently visible ecb-windows 4. The window-object of the compile-window if there is any. 5. The minibuffer-window of the ECB-frame if there is an active minibuffer. 6. The result of the function `ecb-where-is-point' - see the documentation of this function for details. 7. An integer which indicates how many steps away from the current selected window the "other-window" is. Is nil when this function is called in another context than for `other-window'. The function has to return a window-object which is then used as "other window" for the command `other-window' or for scrolling another window (e.g. with `scroll-other-window'). Such a function has to handle properly all situation for itself. Here is an example for such a function: (defun ecb-get-other-window-smart (win-list edit-win-list ecb-win-list comp-win minibuf-win point-loc nth-window) "Implements the smart-setting of `ecb-other-window-behavior'." (if minibuf-win ;; if we have an active mini-buffer we delegate this to ;; `ecb-get-other-window-minibuf-active' (ecb-get-other-window-minibuf-active win-list edit-win-list ecb-win-list comp-win minibuf-win point-loc nth-window) ;; here we have no active minibuffer! (let ((nth-win (or nth-window 1))) (cond ((equal point-loc 'ecb) (ecb-next-listelem ecb-win-list (selected-window) nth-win)) ((equal point-loc 'compile) (if (= nth-win 1) (or (and ecb-last-edit-window-with-point (window-live-p ecb-last-edit-window-with-point) ecb-last-edit-window-with-point) (car edit-win-list)) (ecb-next-listelem (append edit-win-list (list (selected-window))) (selected-window) nth-win))) (t ;; must be an edit-window (ecb-next-listelem (append edit-win-list (if (and comp-win (= (length edit-win-list) 1)) (list comp-win))) (selected-window) nth-win)))))) This example implements the builtin smart behavior described above. ---------- Footnotes ---------- (1) `other-window' allows to select ARG'th different window, i.e. the window ARG steps away from current window in the cyclic order of the windows (2) `other-window' uses the same window-ordering as `walk-windows'  File: ecb.info, Node: The Methods buffer, Next: Filtering the tree-buffers, Prev: The other window, Up: Usage of ECB 6.6 Using and customizing the ECB-Methods buffer ================================================ ECB is mostly designed to display parsing information for files supported by semantic. But beginning with version 1.94 it also supports other parsing engines like imenu and etags, so also files not supported by semantic but by imenu/etags can be displayed in the Method-buffer of ECB. Therefore we have to introduce some terminology: - "semantic-sources": These are file-types for which a semantic grammar is available, so the files are parse-able by semantic. These sources are supported best by ECB and most of the following options and descriptions are related to these file-types. Examples are programming-sources like C++, C, Java, Emacs-Lisp and Texinfo-file and some more. - "non-semantic-sources": For these files there is no semantic-grammar available so they can not be parsed by semantic. Examples are Perl-, LaTeX- and TeX-files. But for many of these files imenu and/or etags parsers exist. ECB supports now parsing and displaying these file-types too and it uses for this some speedbar-logic. This chapter describes how to use and customize the Methods-buffer of ECB. * Menu: * Visiting tags:: Possible actions after visiting a tag * Expanding:: Explicit and automatic expanding * Customizing the display:: How to customize the Methods-buffer display * Rebuilding the Methods:: When to rebuild the Methods-buffer  File: ecb.info, Node: Visiting tags, Next: Expanding, Prev: The Methods buffer, Up: The Methods buffer 6.6.1 Possible actions after visiting a tag ------------------------------------------- You visit a tag by clicking with either the primary oder secondary mouse-button (or by hitting `RET' or `C-RET' if using the keyboard) onto a node in the Methods-tree-buffer of ECB. This simply selects the "right" edit-window (depends if clicked with the primary or secondary button, in how many windows the edit-area is splitted and the value of `ecb-mouse-click-destination') and puts the point onto the first line of the clicked tag. But you can define if after this "basic" tag-visit-action more additional actions should be performed by ECB. You can either use some of the predefined actions (e.g. highlighting the header-line of the tag) or define own actions. You can set different actions for different major-modes. All this is done via the option `ecb-tag-visit-post-actions'. The following actions are currently predefined: - `ecb-tag-visit-highlight-tag-header' - `ecb-tag-visit-smart-tag-start' - `ecb-tag-visit-recenter' - `ecb-tag-visit-recenter-top' - `ecb-tag-visit-goto-doc-start' - `ecb-tag-visit-narrow-tag' See the documentation of these function for details what they do. Per default ECB performs the actions `ecb-tag-visit-smart-tag-start' and `ecb-tag-visit-highlight-tag-header' for all major-modes.  File: ecb.info, Node: Expanding, Next: Customizing the display, Prev: Visiting tags, Up: The Methods buffer 6.6.2 Explicit and automatic expanding of the ECB-methods-buffer ---------------------------------------------------------------- 6.6.2.1 Explicit expanding all nodes to a certain expansion level ................................................................. With the command `ecb-expand-methods-nodes' (bound to `C-c . x') you can get a fast overlook of the contents of the source-buffer, because this command allows precisely expanding all tags with a certain indentation-level. So you can either expand no tags (or with other words collapse all tags) or expand all tags so see the contents of a buffer at one glance. Or you can expand exactly that tags of a certain indentation level. Which node-types are expanded (rsp. collapsed) by this command depends for semantic-sources on the options `ecb-methods-nodes-expand-spec' and `ecb-methods-nodes-collapse-spec'! For non-semantic-sources always all node-types are expanded/collapsed, i.e. the two options above takes no effect for these files. 6.6.2.2 Explicit expanding of the current node to a certain level ................................................................. With the popup-menu of the methods-buffer an even more precise expansion is possible because it allows not only expanding all tags (see above) but offers in addition expanding only the current-node (for which the menu was activated) to an exact level of expansion: All menu-entries are label with an expansion-"level" whereas level specifies precisely which level of nodes should be expanded. level means the indentation-level of the NODE itself and its (recursive) subnodes relative to the NODE itself. So a level value X means that all (sub)nodes with an indentation-level <= X relative to NODE are expanded and all other are collapsed. Examples: - Expand this node to level 0: Expand only the NODE itself because it is the only node which has indentation 0 to itself. All deeper indented nodes will be collapsed. This is also the important difference between using this menu compared to clicking onto the expand-symbol of the node: The latter one expands the NODE to that expansion-state it has before the last collapsing (so when deeper nodes has been expanded they will be expanded now to). The former one expands exactly(!) to level 0, means expand only the node itself and collapse all(!) its subnodes recursively(!). - Expand this node to level 1: Expand the NODE itself and all of its direct subnodes - because only the direct subnodes of NODE have indentation-level 1 relativ to NODE. All deeper nodes will be collapsed. - Collapse this node completely: Collapses the current node recursively, means collapse not only the node itself but also its subnodes, the subnodes of the subnodes and so on! This is very differnt from clicking onto the collapse symbol because this action only collapses the node itself but preserves the expansion-state of all its subnodes! Expanding the current node with the popup-menu ignores the settings in the options `ecb-methods-nodes-expand-spec' and `ecb-methods-nodes-collapse-spec'! 6.6.2.3 Automatic expansion ot tags after buffer-parsing ........................................................ With the option `ecb-show-tags' you tell ECB how to display tags of a certain tag-class (*note Customizing the display::). Among other things you can tell ECB that a certain tag-class should be combined under an expanded or collapsed bucket-node. But such a setting defines the expansion-state of such a bucket-node only direct afterwards the buffer has been (re)parsed, which can occur after opening a file, after autom. reparsing the buffer via semantic or after manually rebuilding the methods-buffer of ECB. The tag-class `type' (classes, interfaces, enumerations etc.) is divided into several subtypes by semantic. The subtypes are strings which names exactly if the tag with tag-class `type' is a class, an interface, an enumeration, a typedef etc. With the option `ecb-type-tag-expansion' you can tell ECB if these type-tags should be autom. expanded after (reparsing) a buffer (see above) or if they should be displayed collapsed - so all its members (methods, variables etc.) are hidden. 6.6.2.4 Automatic expanding the ECB-methods-buffer for current tag .................................................................. If the option `ecb-highlight-tag-with-point' is switched on, then always that node in the method-buffer is highlighted which belongs to the current semantic-tag under point in the current active edit-window. But if this node is invisible (probably because its parent node is collapsed) then no node is highlighted if the auto. expanding feature is switched off. You can either switch on this feature with the option `ecb-auto-expand-tag-tree' or even easier with the command `ecb-toggle-auto-expand-tag-tree'. There is another option `ecb-expand-methods-switch-off-auto-expand' which makes both explicit and auto. expanding best working together. See the documentation of this option to get the details. The autom. expanding feature is only available for semantic-sources! Previous versions of ECB have always fully expanded the whole tree in the Methods-buffer if the current tag in the source-buffer was not visible in the current tree - e.g. because the variables-bucket was collapsed or the containing type of a tag (e.g. the class of a method) was collapsed. So in most cases much more was expanded as needed to make the current tag visible. The mechanism of ECB 2.22 and higher only expands the needed parts of the tree-buffer to make the related node visible: First we try to highlight the current tag with current expansion-state of the Methods-buffer. If the node is not visible so the tag can not be highlighted then we go upstairs the ladder of type-tags the current tag belongs to (e.g. we expand successive the nodes of the whole class-hierachy of the current method-tag until the related node becomes visible). If there is no containing type for the current tag then the node of the tag is probably contained in a toplevel-bucket which is currently collapsed; in this case we expand only this bucket-node and try highlighting again. Only if this has still no success then we expand the full tree-buffer and try to highlight the current tag. There is another option `ecb-auto-expand-tag-tree-collapse-other': If this option is set then auto. expanding the tag-tree collapses all not related nodes. This means that all nodes which have no relevance for the currently highlighted node will be collapsed, because they are not necessary to make the highlighted node visible. This feature is switched off by default because if always collapses the complete Methods-tree before the following highlighting of the node for the current tag expands the needed parts of the tree-buffer.  File: ecb.info, Node: Customizing the display, Next: Rebuilding the Methods, Prev: Expanding, Up: The Methods buffer 6.6.3 Customizing the display of the Methods-buffer --------------------------------------------------- The ECB-Methods buffer is probably the most important browsing window offered by ECB. It displays all parsing informations of the current source-buffer (the buffer displayed in the current active edit-window). Normally ECB gets all informations displayed in this Methods-buffer from the semantic-library - at least for semantic-sources. This library parses auto. the current source-buffer in the edit-window of ECB and returns all information in form of "tags" to ECB which displays them in a browse-able form in its Method-buffer. See *Note ECB Methods-buffer:: for information how to use the Methods-buffer. There are several options to customize which tags ECB should display in general, if the tags should be collapsed or expanded, how to fontify them (i.e. syntax-highlighting) and something more. `ecb-show-tags' With the option `ecb-show-tags' you specify how ECB should display the tags returned by the semantic parser. Semantic divides its tags in several so called "tag classes". A tag-class is always a symbol and can be for example `type' (tags which represent a class(1), a interface, an enumeration etc.), `function' (tags which represent function or methods), `variable' (variables and attributes), `include' (import-statements) etc. There is no predefined superset of allowed tag-class-symbols because each language-parser can define its own tag-classes. But to get an overview of the most common tag-classes see the default value of the option `ecb-show-tags'. With the option `ecb-show-tags' you can now specify how ECB should display tags of a certain tag-class in a certain major-mode. You can tell ECB that all tags of a tag-class `X' should be displayed in an expanded bucket and all tags of a tag-class `Y' should be displayed in a collapsed bucket and all tags of a tag-class `Z' should be displayed flattened (means not contained in a expandable/collapsable bucket-node). These settings can be made separately for each major-mode but you can also define a default-display which takes effect when for a major-mode no special setting can be found in `ecb-show-tags'. For every tag-class you can tell ECB how the tags should be sorted. `ecb-font-lock-tags' `ecb-type-tag-display' How to fontify the tags in the Method-buffer `ecb-tag-display-function' ECB and semantic offer several predefined functions for displaying the tags. Here you can customize, what informations tags should contain (only the method-name or the whole signature or something else) and what notation should be used, e.g. UML or not. These are the most important options for this topic but it is recommended to have a look into the customize-group `ecb-methods' (*note ecb-methods::) and check all the options offered there! All these options are only relevant for semantic-sources and take no effect for non-semantic-sources! ---------- Footnotes ---------- (1) Do not confuse the term "class" in the context of a tag, which means the class of the tag and which is a semantic-term and a "class" in the context of an object oriented language like Java or C++! Normally the surrounding context sould be sufficient to understand which type of "class" is meant whenever the term "class" is used in this manual.  File: ecb.info, Node: Rebuilding the Methods, Prev: Customizing the display, Up: The Methods buffer 6.6.4 Rebuilding the Methods-buffer ----------------------------------- In almost all cases there is *NO* need to manually rebuild the method-buffer, because it is always done automatically if necessary; the mechanism depends on the sources: - semantic-sources: The command `global-semantic-auto-parse-mode' switches on autom. reparsing of semantic-sources. - non-semantic-sources (imenu supported): You can switch on autom. rescanning/reparsing with the option `imenu-auto-rescan'. But nevertheless you have to manually rebuild the Method-buffer (with the autom. updated imenu-tags) via the command `ecb-rebuild-methods-buffer' (bound to `C-c . r'). - non-semantic-sources (etags supported): For these sources there is no built-in auto-rescan mechanism, because etags is an external tool it can only operate on the saved file-contents. So rescanning the buffer contents would need to save the buffer before. Therefore there is no built-in auto-rescan mechanism because this would always result in saving the buffer and running an external tool. But of course you can program such a an etags-auto-rescan mechanism for yourself! Besides for etags-supported non-semantic-sources there exist a few rare scenarios also for the other sources where a complete manual rebuild can be necessary. Here is one example: Depending on the semantic-version: If an Elisp-file is parsed which contains a defun X in the middle where the closing ) is missing, then semantic parses only until this defun X is reached and you will get an incomplete ECB-method buffer. In such a case you must complete the defun X and then completely reparse the Elisp-file and rebuild the ECB method buffer! A complete manually rebuild is done by `ecb-rebuild-methods-buffer'. For etags-parsed non-semantic-sources this causes an automatic saving of the source-buffer because otherwise etags would not operate with the latest contents!  File: ecb.info, Node: Filtering the tree-buffers, Next: The ECB-layout, Prev: The Methods buffer, Up: Usage of ECB 6.7 Applying filters to the special ECB-tree-buffers ==================================================== To get a fast and good overlook of the contents of a tree-buffer ECB offers a filter-mechanism for the Directories-, Sources-, the History- and the Methods-buffer. * Menu: * Filtering Directories:: Applying filters to the Directories-buffer * Filtering Sources:: Applying filters to the Sources--buffer * Filtering History:: Applying filters to the History-buffer * Filtering Methods:: Applying filters to the Methods-buffer  File: ecb.info, Node: Filtering Directories, Next: Filtering Sources, Prev: Filtering the tree-buffers, Up: Filtering the tree-buffers 6.7.1 Applying filters to the Directories-buffer ------------------------------------------------ With the option `ecb-excluded-directories-regexps' certain directories can be excluded from being displayed in the directories-browser of ECB. This can be done by defining regular expressions. If the name of a directory matches at least one of the regexps of this option the directory is not displayed in the directories-tree-buffer. The option `ecb-sources-exclude-cvsignore' allows to exclude source-files from the sources-tree-buffer if their name is listed in a so called `.cvsignore'-file. This option is a list of regular expressions and if a directory-name matches at least one of these regexps then all files listed in the `.cvsignore'-file of this directory are not displayed in the sources-tree-buffer.  File: ecb.info, Node: Filtering Sources, Next: Filtering History, Prev: Filtering Directories, Up: Filtering the tree-buffers 6.7.2 Applying filters to the Sources-buffer -------------------------------------------- 6.7.2.1 Interactive Sources-filters ................................... The command `ecb-sources-filter' allows to filter these tree-buffer either by a regular expression or by an extension (e.g. java, cc, el for java-, c++- rsp elisp-sources). This functionality is also available via the popup-menu of the Sources-tree-buffer. The currently applied filter is indicated in the modeline of the related tree-buffer. Applying a new filter replaces an eventually already applied filter. 6.7.2.2 Default Sources-filters ............................... The option `ecb-source-file-regexps' allow to specify which source-files should be displayed and which not. This is done on a directory-basis, ie. for each directory-regexp the files to display can be specified. See the documentation of this option for all details. In addition to this option you should also know the option `ecb-sources-exclude-cvsignore' (*note Filtering Directories::).  File: ecb.info, Node: Filtering History, Next: Filtering Methods, Prev: Filtering Sources, Up: Filtering the tree-buffers 6.7.3 Applying filters to the History-buffer -------------------------------------------- 6.7.3.1 Interactive History-filters ................................... The command `ecb-history-filter' allows to filter these tree-buffer either by a regular expression or by an extension (e.g. java, cc, el for java-, c++- rsp elisp-sources). This functionality is also available via the popup-menu of the History-tree-buffer. The currently applied filter is indicated in the modeline of the related tree-buffer. Applying a new filter replaces an eventually already applied filter. 6.7.3.2 Default History-filters ............................... The option `ecb-history-exclude-file-regexps' allows to exclude source-files from being historized (ie. displayed in the History-buffer). Despite the fact that the History-buffer already excludes all non-file-buffers there can be still buffers which name you do not wat to be displayed in the history. These are file-buffer like `TAGS' or `semantic.cache' which store meta-informations used by Emacs and its tools (etags, semantic etc.). These files can be excluded via `ecb-history-exclude-file-regexps'.  File: ecb.info, Node: Filtering Methods, Prev: Filtering History, Up: Filtering the tree-buffers 6.7.4 Applying filters to the Methods-buffer -------------------------------------------- The commands `ecb-methods-filter', `ecb-methods-filter-regexp', `ecb-methods-filter-protection', `ecb-methods-filter-tagclass', `ecb-methods-filter-function', `ecb-methods-filter-delete-last', `ecb-methods-filter-nofilter' allows to filter the tags/nodes of the Methods-buffer by several criterias. As for the Sources- and the History-buffer the same functionality is also available via the popup-menu of the Methods-buffer. 6.7.4.1 Possible filter-criterias ................................. * Filter by protection: Just insert the protection you want the Methods-buffer being filtered: private, protected or public! For sources not supported by semantic the protection filter will not be offered because these informations are not available for such sources. * Filter by regexp: Insert the filter as regular expression. * Filter by tag-class: You can filter by tag-classes. The popup-menu contains mode-dependend tag-filter entries and the command `ecb-methods-filter' offers only the tag-classes of the current mode. This means for sources not supported by semantic the tag-class filter will not be offered. And for semantic-supported sources exactly these tag-classes are offered the semantic-parser for the current major-mode offers. For example texi-sources can only be filtered by the tag-classes "Definitions" and "Sections" and java-sources can be filtered by "Methods", "Variables", "Classes" etc. In general the semantic-variable `semantic-symbol->name-assoc-list' is used to get the right tag-classes. * Filter by a filter-function: Such a function gets two arguments: a tag and the source-buffer of this tag. If the tag should be displayed (i.e. not being filtered out) then the function has to return not nil otherwise nil. * No special filter: This means to display all tags specified with the option `ecb-show-tokens'. If currently some of the above filters are applied they will be all removed. * Delete the last added: This removes only the topmost filter-layer, means that filter added last. Be aware that the tag-list specified by the option `ecb-show-tags' is the basis of all filters, i.e. tags which are excluded by that option will never be shown regardless of the filter type here! All tags which match the applied filter(s) will be displayed in the Methods-buffer. Such a filter is only applied to the current source-buffer, i.e. each source-buffer can have its own tag-filters. These tag-filters can also applied to sources which are not supported by the semantic-parser but "only" by imenu or etags. But because for these sources not all information are avaiable the protection- and tag-class filter are not offered with such "non-semantic"-sources. See *Note Non-semantic sources:: for further details about working with source-files not supported by the semantic-parser. 6.7.4.2 Inverse Filters ....................... But if `ecb-methods-filter' is called with a prefix-argument then an inverse filter is applied to the Methods-buffer, i.e. all tags which do *NOT* match the choosen filter will be displayed in the Methods-buffer! 6.7.4.3 Layered filters ....................... Per default the choosen filter will be applied on top of already existing filters. This means that filters applied before are combined with the new filter. This behavior can changed via the option `ecb-methods-filter-replace-existing'. 6.7.4.4 Display of currently applied filters ............................................ The current active filter will be displayed in the modeline of the Methods-buffer [regexp, prot (= protection), tag-class, function (= filter-function)]. If an inverse filter has been applied then this is signalized by a preceding caret ^. If currently more than 1 filter is applied then always the top-most filter is displayed in the modeline but the fact of more than 1 filter is visualized by the number of the filters - included in parens. You can see all currently applied filters by moving the mouse over the filter-string in modeline of the Methods-buffer: They will displayed as help-echo. 6.7.4.5 Default filters for certain files. .......................................... The new option `ecb-default-tag-filter' allow to define default tag-filters for certain files which are applied automatically after loading such a file into a buffer. The possible filters are the same as offered by the command `ecb-methods-filter' and they are applied in the same manner - the only difference is they are applied automatically. The files can be specified on a combined major-mode- and filename-regexp-basis. Usage-example: This can be used to display in outline-mode files (e.g. `NEWS') only the level-1-headings by defining a filter regexp "^\* .*".  File: ecb.info, Node: The ECB-layout, Next: Hiding the ECB windows, Prev: Filtering the tree-buffers, Up: Usage of ECB 6.8 Changing, customizing, redrawing and creating layouts ========================================================= The term "ECB-layout" means in which windows the ECB-frame is divided. This chapter describes all aspects concerning this layout, especially changing, customizing, redrawing and also creating new layouts. * Menu: * Changing the ECB-layout:: How to change and customize the layout * Redrawing the ECB-layout:: How and when redrawing the layout * Changing window sizes:: Changing sizes of the ECB-windows * Fixing window sizes:: Fixing sizes of the ECB-windows * Creating a new ECB-layout:: Interactively creating new layouts  File: ecb.info, Node: Changing the ECB-layout, Next: Redrawing the ECB-layout, Prev: The ECB-layout, Up: The ECB-layout 6.8.1 Changing and customizing the ECB-layout --------------------------------------------- ECB offers several predefined layouts with different sets and also different locations of ECB-windows. See below the "ascii-screenshot" of all currently built-in layouts(1). In addition to these predefined layouts you can either interactively create new layouts "by example" (*note Creating a new ECB-layout::) or program new layouts with the macro `ecb-layout-define' (*note The layout-engine::). The former method is the recommended one! There are two ways to interactively change the layout: * Changing permanently: Customize the option `ecb-layout-name' and store it for future Emacs sessions. * Switching between several layouts at runtime: If you want to switch fast between a certain sequence of layouts see the option `ecb-toggle-layout-sequence' and the command `ecb-toggle-layout' (*note Simulating speedbar::). For just selecting another layout during current Emacs-session use the command `ecb-change-layout'. With the option `ecb-show-sources-in-directories-buffer' you can define if sources are displayed in the directory-window of a layout (*note ECB Directories-buffer::). In addition to the general layout you can specify if the layout should contain a persistent compilation-window at the bottom of the frame, see `ecb-compile-window-height' (*note Temp- and compile-buffers::). Maybe you want also change the look&feel of the tree-buffers. Then you can change the general style of the tree-buffers with the option `ecb-tree-buffer-style' and the location of the collapse- and expand-symbols and the indentation of sub-nodes in a tree. See `ecb-tree-indent' and `ecb-tree-expand-symbol-before'. More details about the different tree-buffer-styles are described in *Note Tree-buffer styles::. Here are all currently available layouts (for creating own new layouts see *Note Creating a new ECB-layout::); just customize the option `ecb-layout-name' to the related name: Layout "left1" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | | Sour | Hist | Edit | | | | | | | | | |--------------| | | | | | Methods | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left2" ------------------------------------------------------- | | | | | | | | | | Directories | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | Sources | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left3" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | Sources | Edit | | | | | | | |--------------| | | | | | Methods | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left4" ------------------------------------------------------- | | | | | | | | | | Directories | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | | | | Sour | Hist | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left5" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | |--------------| | | | | | Sources | Edit | | | | | | | |--------------| | | | | | History | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "right1" ------------------------------------------------------- | | | | | Directories | | | | | | | | |--------------| | | | | | | | Edit | Sources | | | | | | | | |--------------| | | | | | Methods | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left6" ------------------------------------------------------- | Sources | | |--------------| | | | | | | | | | | | Methods | Edit | | | | | | | | | | |--------------| | | History | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "top1" ------------------------------------------------------- | | | | | | | | | Directories | Sources | Methods | | | | | | | | | |-----------------------------------------------------| | | | | | | | | | Edit | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left7" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |--------------| Edit | | | | | History | | | | | |--------------| | | | | | Methods | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left8" ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | | | | |--------------| | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "top2" ------------------------------------------------------- | | | | | Methods | | | | | |-----------------------------------------------------| | | | | | | | | | Edit | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left9" ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left10" ------------------------------------------------------- | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | | Sou | Hist | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left11" ------------------------------------------------------- | | | | | | | | | | Methods | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left12" ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | History | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left13" ------------------------------------------------------- | | | | | | | | | | | | | | | | | | | | | | Directories | Edit | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left14" ------------------------------------------------------- | | | | | | | | | | Directories | Edit | | | | | | | | | | | | | | | | |--------------| | | | | | History | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left15" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |--------------| Edit | | | | | | | | | | | Methods | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "leftright1" ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | |-------------| Edit | | | | | | | Sources | | | | | | | |-------------| | | | | | | | History | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "leftright2" ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | | | Edit | | |-------------| |-------------| | | | | | Sources | | History | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "leftright3" ------------------------------------------------------- | | | | | Directories | | Methods | | | | | | | | | | | | | | | | | | | | | | | Edit | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left-dir-plus-speedbar" ------------------------------------------------------- | | | | Directories | | | | | | | | | | | | | | | | | |-------------| | | | | | | | | | | | Speedbar | | | | | | | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left-analyse" ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | |--------------| | | | | | Analyse | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- Layout "left-symboldef" ------------------------------------------------------- | | | | Directories | | | | | |--------------| | | | | | Sources | | | | | |--------------| Edit | | | | | Methods | | | | | |--------------| | | | | | Symbol-defs | | | | | ------------------------------------------------------- | | | Compilation | | | ------------------------------------------------------- ---------- Footnotes ---------- (1) The command `ecb-show-layout-help'' shows the outline-picture for all built-in layouts.  File: ecb.info, Node: Redrawing the ECB-layout, Next: Changing window sizes, Prev: Changing the ECB-layout, Up: The ECB-layout 6.8.2 Redrawing the ECB-layout ------------------------------ If you have unintentionally destroyed the ECB-layout, you can always restore the layout with calling `ecb-redraw-layout'. This is even true, if you get messages like "wrong-type-argument window-live-p #". If the variable `ecb-redraw-layout-quickly' is not nil then the redraw is done by the `ecb-redraw-layout-quickly' function, otherwise by `ecb-redraw-layout-full'. But it's strongly recommended to use the quick redraw only if you have really slow machines where a full redraw takes several seconds because the quick redraw is not really safe and may have some drawbacks! On normal machines the full redraw should be done in << 1s! Please read the documentation of the command `ecb-redraw-layout'! See also the hooks `ecb-redraw-layout-after-hook' and `ecb-redraw-layout-before-hook'!  File: ecb.info, Node: Changing window sizes, Next: Fixing window sizes, Prev: Redrawing the ECB-layout, Up: The ECB-layout 6.8.3 Changing the sizes of the special ECB-windows --------------------------------------------------- The standard width and height of the special ECB-windows is defined with the options `ecb-windows-width' and `ecb-windows-height'. But changing these options always influences all layouts which is not always desired. ECB offers to re-adjust the width and height of the ECB-windows (e.g. by dragging the windows-borders via the mouse) and then saving exactly these current window-sizes for the current layout so after activating this layout all windows have autom. the stored sizes. This is done via the option `ecb-layout-window-sizes' and the commands `ecb-store-window-sizes', `ecb-restore-window-sizes' and `ecb-restore-default-window-sizes'. Here is an example how to resize and store the sizes of the ECB-windows of layout "left1": 1. Switch to layout "left1" via `ecb-change-layout' (`C-c . lc') 2. Resize the ECB-windows by dragging the window-borders with the mouse 3. Call `ecb-store-window-sizes' After this layout "left1" will be always drawn with the new sizes until you call `ecb-restore-default-window-sizes' during layout "left1" is active. *Please note*: `ecb-store-window-sizes' stores the width and height of the windows per default as fractions of the width (rsp. height) of the ECB-frame, so the stored sizes are always correct regardless of the current frame-size! But if called with a prefix argument then fixed sizes are stored.  File: ecb.info, Node: Fixing window sizes, Next: Creating a new ECB-layout, Prev: Changing window sizes, Up: The ECB-layout 6.8.4 Fixing the sizes of the special ECB-windows ------------------------------------------------- GNU Emacs 21 introduced a new feature which can fix the sizes of a window displaying a certain buffer even after resizing the frame. This new feature is driven by the new buffer-local variable `window-size-fixed'. ECB offers an option `ecb-fix-window-size' for fixing the sizes of the special ECB-windows/buffers even after frame-resizing. The fix type (valid values are `nil', `t', `width' and `height') can either be set on a layout-basis (means a different value for each layout) or one value can be set for all layouts. In the latter case there is an additional value `auto' which choose autom. the senseful fix-type depending on the current layout-type: For top-layouts the fix-type `height' and for all other layout-types the fix-type `width'. Probably the most senseful value is `auto' for all layouts because it makes less sense to fix the height of the ecb-windows in a left-, right- or leftright-layout. Same for fixing the width in a top-layout. Note: With current Emacs 21.2.X there seems to be no distinction between `width', `height' and `t'. Therefore this option takes no effect (means all ecb-windows have always unfixed sizes) if `ecb-compile-window-height' is not `nil'.  File: ecb.info, Node: Creating a new ECB-layout, Prev: Fixing window sizes, Up: The ECB-layout 6.8.5 Interactively creating new layouts ---------------------------------------- If you want to create your own ECB-layout then you can do this very easy "by example" with the command `ecb-create-new-layout'. This command creates a new empty frame and offers a small set of keys to create the new layout by splitting windows. `ecb-create-new-layout' and this couple of keys are your guide during the layout-creation-process(1). After calling `ecb-create-new-layout' you will be asked which type of layout you want to create: "left", "right", "top" or "left-right". Here you specify where the ECB-tree-windows/buffers should be located in the ECB-frame: - left: All ECB-tree-windows are located on the left side - right: All ECB-tree-windows are located on the right side - top: All ECB-tree-windows are located on the top side - left-right: All ECB-tree-windows are located on the left and right side Depending on the type you choose the window is splitted by the values of the options `ecb-windows-width' (types "left", "right" and "left-right") or `ecb-windows-height' (type "top"). Afterwards you will see a frame like follows (here the layout-type is "left-right"): ----------------------------------------------------------------- | | | | | | ECB-layout creation mode | | | | ======================== | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ----------------------------------------------------------------- | | ,--- `---| Splitted by the value of `ecb-windows-width'. `--- The big window (here the middle window) will be the edit-area of the new layout and can not be selected, deleted or splitted during the creation process. It displays the help-screen for the layout-creation mode. Here all the available commands are displayed. The small window(s) (here the left and right windows) can be splitted by you wherever you want (`C-s'). The left one contains the point. You must give every ECB-tree-window you create a type (`C-t') which can be either * One of the built-in types This can be either "directories", "sources", "methods", "history" or "speedbar". * Any user-defined type: In this case you insert "other" after hitting `C-t' and you will then be asked for the name of the user-defined type. You can insert any arbitrary type name X. But to get this layout working you have to define a function with name `ecb-set-X-buffer' whereas X is the name of the user-defined type you have specified during layout-creation. This function `ecb-set-X-buffer' must be defined with the macro `defecb-window-dedicator' and has to switch to the buffer you want to display in this window. This macro automatically ensures that this window is dedicated to that buffer. Here is an example: Suppose you have inserted as type name "example" then you have to define and load a function `ecb-set-example-buffer' which could be defined like follows: (defecb-window-dedicator ecb-set-example-buffer " *ECB example-buf*" (switch-to-buffer (get-buffer-create " *ECB example-buf*"))) If you forget to define such a function for the user-defined type then nevertheless ECB will draw this layout but it will use the default-function `ecb-set-default-ecb-buffer' instead. If you are satisfied with your new layout just hit `C-q'. You will be asked for a new layout-name (TAB-completion is offered to get a list of all names already in use) and after inserting a new(!) name the new layout is saved in the file defined by the option `ecb-create-layout-file'. The new layout is now available via the option `ecb-layout-name'. There is no need for you to load the file `ecb-create-layout-file' manually into your Emacs because it's automatically loaded by ECB! *Please note*: During the layout-creation process only the commands displayed in the help-screen are available. ALL other commands are temporally disabled (even the mouse-commands). For programming new layouts with emacs-lisp see *Note The layout-engine::. With the command `ecb-delete-new-layout' you can delete previously created layouts (TAB-completion is offered for all names of user created layouts). ---------- Footnotes ---------- (1) During the creation process you will be asked in the minibuffer for several options; here you can use TAB-completion and an "empty" RET chooses always the first option!  File: ecb.info, Node: Hiding the ECB windows, Next: Maximizing the ECB windows, Prev: The ECB-layout, Up: Usage of ECB 6.9 Hiding/Showing the ECB windows ================================== With `ecb-toggle-ecb-windows', `ecb-hide-ecb-windows' and `ecb-show-ecb-windows' you can hide/show all the ECB windows without changing the activation state of ECB and also without deactivating the advices for `delete-other-windows' and/or `delete-window'. This is most useful if you use a layout like "top2" (*note Tips and tricks::) or if you want to have maximum space for editing and you don't need the browsing windows all the time. The following sequence of hooks is evaluated during showing again the hidden ECB-windows: 1. `ecb-show-ecb-windows-before-hook' 2. `ecb-redraw-layout-before-hook' 3.