[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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:
ecb-primary-mouse-jump-destination
.
ecb-primary-mouse-jump-destination
.
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] | [ ? ] |
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] | [ ? ] |
In the ECB-buffers RETURN and TAB are the most important keys:
ecb-tree-RET-selects-edit-window
and the function
ecb-toggle-RET-selects-edit-window
which is bound to C-t
in each tree-buffer of ECB!
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] | [ ? ] |
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] | [ ? ] |
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:
other-window
delete-window
delete-other-windows
split-window-horizontally
split-window-vertically
switch-to-buffer
switch-to-buffer-other-window
other-window-for-scrolling
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] | [ ? ] |
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:
ecb-compile-window-height
you can define if the ECB
layout should contain per default a compilation-window at the bottom
(and if yes the height of it). If yes ECB displays all output of
compilation-mode (compile, grep etc.) in this special window. Same for
displaying help-buffers or similar stuff.
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 function ecb-toggle-enlarged-compilation-window
.
ecb-layout-switch-to-compilation-window
you can
modify the switch-to-buffer...-functions to work best if your layout
contains a compilation-window. See the docstring of this option.
ecb-cycle-through-compilation-buffers
(see section 4.10 Interactive ECB commands) you can cycle through all current
open compilation-buffers in the sense of
ecb-compilation-buffer-p
very fast.
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] | [ ? ] |
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] | [ ? ] |
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
ecb-font-lock-tokens
ecb-type-token-display
ecb-token-display-function
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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:
Now you will edit at the same place in the function.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 windows is synchronized to display the directory where the
source-file which is displayed in the edit-window is located. If the
source-path (i.e. an element of the option ecb-source-path
)
containing this directory is not expanded it will be auto. expanded
according to the value of the option
ecb-auto-expand-directory-tree
(see section 5.2.2 Group ecb-directories).
The ECB-sources-buffer contains after synchronizing all the sources of the directory of the "current" source-file displayed in the edit-window. The entry of the "current" source-file is highlighted.
Contains after synchronizing all the tokens of the buffer in the edit-window, i.e. all methods, variables etc... depending of the major-mode.
Highlights the entry of the buffer displayed in the edit-window if this buffer is a source-file.
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] | [ ? ] |
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):
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.
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
.
nil
then do this only if current-buffer
differs from the source displayed in the ECB tree-buffers.
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!
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
.
ecb-compile-window
.
nil
if the minor mode is
enabled.
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.
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!
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
!
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!
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.
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] | [ ? ] |