[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Usage of ECB

This chapter describes in a detailed manner all aspects of using the Emacs Code Browser.

4.1 Working with the mouse in the ECB-windows  Working with the mouse
4.2 Working with the keyboard in the ECB-windows  Working with the keyboard
4.3 Working with the edit-window  How to use the edit-window(s)
4.4 Temp- and compile-buffers display in ECB  Displaying temp- and compilation-buffers
4.5 Using and customizing the ECB-Methods buffer  Using and customizing he Methods-buffer
4.6 Changing, customizing and redrawing the ECB-layout  Changing, customizing, redrawing the layout
4.7 Hiding/Showing the ECB windows  
4.8 Back- and forward navigation like a browser  
4.9 Synchronization of the ECB-windows  Auto./manual synchronizing the ECB-windows
4.10 Interactive ECB commands  All interactive user-commands of ECB


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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:

A click with the primary button causes the main effect in each ECB-buffer:

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 can get the same effect if you click with the primary mouse-button onto a node while SHIFT is held. In general: Via ecb-show-node-info-in-minibuffer you can specify in a detailled manner for every ECB tree-buffer when and which node-info should be displayed in the minibuffer.

IMPORTANT: Doing this SHIFT-click in the ECB-Sources or ECB-History windows does not only show the node in the echo-area but it also 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.

The secondary mouse-button is for opening (jumping to) the file in the other window (see the documentation ecb-primary-mouse-jump-destination).

With the option ecb-primary-secondary-mouse-buttons the following combinations of primary and secondary mouse-buttons are possible:

If you change this during ECB is activated you must deactivate and activate ECB again to take effect

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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 without a mouse.

IMPORTANT: Do not modify ecb-mode-map directly! The option ecb-key-map defines all ECB keybindings, including a common prefixkey (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 (see section 5.2.1 Group ecb-general).!

4.2.1 Navigation  Keyboard navigation in a tree-buffer
4.2.2 Incremental search for a node in current tree-buffer  Find nodes as fast as possible


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 Navigation

In the ECB-buffers RETURN and TAB are the most important keys:

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 left- and right-arrow keys work in the ECB tree-window in the following smart way if onto an expandable node:

Onto a not expandable node the horizontal arrow-keys go one character in the senseful correct direction.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 Incremental search for a node in current tree-buffer

Each displayable key (e.g. all keys normally bound to self-insert-command) is appended to the current seach-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:

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 thi incremental search ignores the following non interesting stuff:

This means: Just type in the prefix (resp. 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 . m.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Working with the edit-window

ECB offers you all what you need to work with the edit-window as if the edit-window would be the only window of the ECB-frame.

ECB offers you to advice the following functions so they work best with ECB:

The behavior of the adviced functions is:

ATTENTION: If you want to work within the edit-window with splitting and unsplitting 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 does advice 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!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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. If the edit-window is already splitted then the temp-buffer is displayed in the "other" edit-window otherwise the edit-window will be splitted first. The variables temp-buffer-max-height and temp-buffer-resize-mode 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:

But because ECB works best without such a durable compilation-window you should read the documentation of these two options carefully!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 Using and customizing the ECB-Methods buffer

This chapter describes how to use and customize the Methods-buffer of ECB.

4.5.1 Customizing the display of the Methods-buffer  How to customize the Methods-buffer display
4.5.2 Rebuilding the Methods-buffer  When to rebuild the Methods-buffer


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5.1 Customizing the display of the Methods-buffer

The ECB-Methods buffer is probably the most important browsing window offered by ECB. It displays all semantic informations of the current buffer in the edit-window.

ECB gets all informations displayed in this Methods-buffer from the semantic-library. This library parses auto. the current source-buffer in the edit-window of ECB and returns all information in form of tokens to ECB which displays them in a browsable form in its Method-buffer. See 2.3 ECB Methods for information how to use the Methods-buffer.

There are several options to customize which tokens ECB should display in general, if the tokens should be collapsed or expanded, how to fontify them (i.e. syntax-highlighting) and something more.

ecb-show-tokens
Which semantic-tokens (e.g. types, methods, variables etc.) should be displayed and should they be collapsed, flattened or expanded. Sorting is also possible.

ecb-font-lock-tokens
ecb-type-token-display
How to fontify the tokens in the Method-buffer

ecb-token-display-function
ECB and semantic offer several predefined functions for displaying the tokens. Here you can customize, what informations tokens 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 (see section 5.2.4 Group ecb-methods) and check all the options offered there!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5.2 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. But nevertheless there exist a few rare scenarios 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Changing, customizing and redrawing the ECB-layout

The term ECB-layout means in which windows the ECB-frame is divided. This chapter describes all aspects concerning this layout, especially changing, customizing and redrawing it.

4.6.1 Changing and customizing the ECB-layout  How to change and customize the layout
4.6.2 Redrawing the ECB-layout  How and when redrawing the layout


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6.1 Changing and customizing the ECB-layout

ECB offers several predefined layouts with different sets and also different locations of ECB-windows. To see which layouts are available and choose an appropriate one just customize the option ecb-layout-nr. The docstring of this option explains how to see the different available layouts.

If you want to switch fast between some layouts see the option ecb-toggle-layout-sequence and the command ecb-toggle-layout (see section 8.3 Simulating speedbar without an extra frame)

In addition to the general layout you can specify if the layout should contain a durable compilation-window at the bottom of the frame, see ecb-compile-window-height (see section 4.4 Temp- and compile-buffers display in ECB).

Maybe you want also change the look&feel of the tree-buffers. Then you can change the location of the collapse- and expand-symbols and the indendation of sub-nodes in a tree. See ecb-tree-indent and ecb-tree-expand-symbol-before.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6.2 Redrawing the ECB-layout

If you have unintenionally 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 #<window 222>".

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!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7 Hiding/Showing the ECB windows

With ecb-toggle-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 nr.10 (see section 8. Tips and tricks) or if you want to have maximum space for editing and you don't need the browsing windows all the time.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8 Back- and forward navigation like a browser

With ECB you can "browse" in your source-files like with a web-browser. This means ECB stores the current buffer- and window-position relative to the current token(4) in the edit-window after

ECB offers two commands ecb-nav-goto-next (C-c . n) and ecb-nav-goto-previous (C-c . p) to go forward and backward within this navigation historylist. These commands are also available via the menu "ECB --> Navigate".

Aside normal "location-browsing" this is usefull for example in a scenario where ecb-token-jump-narrow is activated:

  1. You edit a function
  2. Goto another function above the current in the same file
  3. Add a few lines
  4. Call ecb-nav-goto-previous

    Now you will edit at the same place in the function.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.9 Synchronization of the ECB-windows

Per default ECB synchronizes automatically the contents of the ECB-windows/tree-buffers with the current active edit-window (rsp. the current buffer of the edit window):

This feature can be customized with the option ecb-window-sync:

If active then the synchronization takes place always a buffer changes in the edit window, if deactivated then never. But you can also set this option to a list of major-modes and then the sync. will only be done if the major-mode of the current buffer belongs NOT to this list.

But in every case the synchronization takes only place if the major-mode of the current-buffer in the edit-window has a relation to files or directories. Examples for the former one are all programming-language-modes like c++-mode or java-mode, Info-mode too, an example for the latter one is dired-mode. For all major-modes related to non-file/directory-buffers like help-mode, customize-mode and others never a synchronization will be done!

It's recommended to exclude at least Info-mode because it makes no sense to synchronize the ECB-windows after calling the Info help. Per default also dired-mode is excluded but it can also making sense to synchronize the ECB-directories/sources windows with the current directory of the dired-buffer in the edit-window.

NOTE: With the command ecb-current-buffer-sync you can do a manually synchronization if the automatic one is switched off or if you just want to do this!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.10 Interactive ECB commands

ECB offers the a lot of interactive commands. Some of these commands prompt the user in the minibuffer if called with a prefix argument.

Example: If ecb-clear-history is called with a prefix argument then you will be prompted in the minibuffer with:

 
Clear from history: [all, not-existing-buffers, existing-buffers]

You can choose one of the options enclosed in brackets with TAB-completion; hitting RET direct after the prompt chooses auto. the first offered option (in the example above "all").

These are the interactive commands of ECB (listed in alphabetical order):

Command: ecb-activate
Activates the ECB and creates all the buffers and draws the ECB-screen with the actually choosen layout (see ecb-layout-nr). This function raises always the ECB-frame if called from another frame. This is the same as calling ecb-minor-mode with a positive argument.

Command: ecb-add-all-buffers-to-history
Add all current file-buffers to the history-buffer of ECB.

Command: ecb-clear-history &optional clearall
Clears the ECB history-buffer. If CLEARALL is nil then the behavior is defined in the option ecb-clear-history-behavior otherwise the user is prompted what buffers should be cleared from the history-buffer. For further explanation see ecb-clear-history-behavior.

Command: ecb-current-buffer-sync &optional force
Synchronizes the ECB buffers with the current buffer. Unless FORCE is non-nil then do this only if current-buffer differs from the source displayed in the ECB tree-buffers.

Command: ecb-cycle-through-compilation-buffers &optional choose-buffer
Cycle through all compilation buffers currently open and display them within the compilation window ecb-compile-window. If the currently opened buffer within the compilation window is not a compilation buffer, we jump to the first compilation buffer. If not we try to loop through all compilation buffers. If we hit the end we go back to the beginning.

If CHOOSE-BUFFER is not nil then the user will be prompted for the compilation-buffer to swtich to.

See also the option ecb-layout-switch-to-compilation-window! The difference is that this cycling-function offers only compilation-buffers in the sense of ecb-compilation-buffer-p whereas the adviced version of switch-to-buffer offers any buffer but switches to ecb-compile-window if a compilation-buffer!

Command: ecb-deactivate
Deactivates the ECB and kills all ECB buffers and windows.

Command: ecb-display-upgraded-options
Display a message-buffer which options have been upgraded or reset.

Command: ecb-download-ecb
Download ECB from the ECB-website and install it. For this the options ecb-download-url and ecb-download-version must be set correct, whereas the default value of the former one should always be correct.

For details about downloading and what requirements must be satisfied see 7.1 Downloading new versions of ECB and/or required packages!

After sucessfull downloading the new ECB will be installed in a directory parallel to current ECB-directory. After adding this new directory tp load-path and restarting Emacs the new ECB version can be activated by ecb-activate.

Command: ecb-goto-window-compilation
Goto the ecb compilation window ecb-compile-window.

Command: ecb-goto-window-directories
Make the ECB-directories window the current window.

Command: ecb-goto-window-edit1
Make the (first) edit-window window the current window.

Command: ecb-goto-window-edit2
Make the second edit-window (if available) window the current window.

Command: ecb-goto-window-history
Make the ECB-history window the current window.

Command: ecb-goto-window-methods
Make the ECB-methods window the current window.

Command: ecb-goto-window-sources
Make the ECB-sources window the current window.

Command: ecb-minor-mode &optional arg
Toggle ECB minor mode. With prefix argument ARG, turn on if positive, otherwise off. Return non-nil if the minor mode is enabled.

Command: ecb-nav-goto-previous
Go backward in the navigation historylist, See section 4.8 Back- and forward navigation like a browser.

Command: ecb-nav-goto-next
Go forward in the navigation historylist, See section 4.8 Back- and forward navigation like a browser.

Command: ecb-rebuild-methods-buffer
Updates the methods buffer with the current buffer after deleting the complete previous parser-information, means no semantic-cache is used! Point must stay in an edit-window otherwise nothing is done. This method is merely needed if semantic parses not the whole buffer because it reaches a not parsable code. Examples when a call to this function is necessary:

If an elisp-file is parsed which contains in the middle a defun X where the closing ) is missing then semantic parses only until this defun X is reached and you will get an incomplete ECB-method buffer. In such a case you must complete the defun X and then call this function to completely reparse the elisp-file and rebuild the ECB method buffer!

If you change only the name of a method or a variable and you want the new name be shown immediately in the ECB-method buffer then you must call this function.

Command: ecb-redraw-layout
Redraw the ECB screen. 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 drawback should be done in << 1s!

Command: ecb-show-help &optional format
Shows the online help of ECB either in Info or in HTML format depending of the value of ecb-show-help-format. If called with prefix argument, i.e. if FORMAT is not nil then the user is prompted to choose the format of the help (Info or HTML). If an error about not finding the needed help-file occurs please take a look at the options ecb-help-info-start-file and ecb-help-html-start-file!

Command: ecb-submit-problem-report
Submit a problem report for the ECB to the ECB mailing-list. This command generates in the edit-window a problem-report which contains already the current values of all ECB options, the current backtrace-buffer if there is any and the current message-buffer. You will be asked for a problem-report subject and then you must insert a description of the problem. Please describe the problem as detailed as possible!

Command: ecb-toggle-ecb-windows &optional arg
Toggle visibilty of the ECB-windows. With prefix argument ARG, make visible if positive, otherwise invisible. This has nothing to do with (de)activating ECB but only affects the visibility of the ECB windows. ECB minor mode remains active!

Command: ecb-toggle-enlarged-compilation-window &optional arg
Toggle whether the ecb-compile-window is enlarged or not. If ARG > 0 then enlarge to a sensefull value (see below), if ARG <= 0 then shrink ecb-compile-window to ecb-compile-window-height and if ARG is nil then toggle the enlarge-state.

The ecb-compile-window is enlarged to the following value: At least to the value of ecb-compile-window-height and max. to half of the frame-height of the ECB-frame, best depending on the values of compilation-window-height (before ECB was started!) and the number of lines of current buffer in ecb-compile-window. If compilation-window-height is set before ECB was started then ECB never enlarges the ecb-compile-window over the value of compilation-window-height! Changing this option during activated ECB takes first effect after restarting ECB!

Command: ecb-toggle-layout
Toggles between the layouts defined in ecb-toggle-layout-sequence. Note: This function works by changing the options ecb-layout-nr and ecb-show-sources-in-directories-buffer but only for current Emacs-session.

Command: ecb-update-directories-buffer
Updates the ECB directories buffer.

Command: ecb-upgrade-options
Check for all ECB-options if their current value is compatible to the defined type. If not upgrade it to the new type or reset it to the default-value of current ECB. Try also to upgrade renamed options. Displays all upgraded or reset options with their old (before the upgrade/reset) and new values.

Most of these functions are also available via the menu "ECB" and also via the ECB keymap with prefix C-c . (see ecb-minor-mode for a complete list of the keybindings).


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on December, 6 2002 using texi2html