This is ecb.info, produced by makeinfo version 4.2 from ecb.texi. INFO-DIR-SECTION GNU Emacs Lisp START-INFO-DIR-ENTRY * ECB: (ecb). Emacs Code Browser END-INFO-DIR-ENTRY  File: ecb.info, Node: ECB Directories-buffer, Next: ECB Sources-buffer, Prev: Tree-buffer styles, Up: Basic interactors 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'. 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. 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::). 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 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. 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. 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::). 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 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::). 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. 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::). 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 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 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. 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. 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. 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::). 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 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 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 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 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 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 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. 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'. 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. 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'). 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. 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 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 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 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 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 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 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'! 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 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. 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: 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. 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" 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.