Next: ECB History-window, Previous: ECB Sources-window, Up: Basic ECB-windows
The ECB-Methods ECB-window 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-ECB-window is automatically synchronized and updated with current point of the current source-buffer in the edit-area (see ECB-window synchronizing).
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 (see Using the mouse)
or RETURN (see 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!
ecb-mouse-click-destination
.
Either use one of the predefined layouts which contain the methods
ECB-window (see 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 (see Creating a new ECB-layout).
First a preliminary remark: Do not confuse this chapter with that synchronizing described in ECB-window synchronizing. The latter one describes the mechanism for synchronizing the ECB-windows when the current-buffer in the edit-area has been changed. This chapter describes how to synchronize the ECB-methods-window with the contents of the current-buffer if the buffer has been modified!
Now lets start:
Generally ECB calls semantic to get the list of tags for current source-file
of current edit-window. Per default ECB does never automatically force a
reparse of the source-file after this has been changed - this is only done on
demand by calling the command ecb-rebuild-methods-buffer
. So per
default the idle-scheduler of semantic is responsible for reparsing the
source-file when this is necessary (see `semantic-idle-scheduler-mode' for
further details). So this scheduler is also repsonsible in turn for
updating/sychronizing the methods-window with current buffer-contents. This is
the most user-resonsible and therefore the recommended approach.
So it's strongly recommended to enable semantic-idle-scheduler-mode
or
global-semantic-idle-scheduler-mode
(see Setting up CEDET/semantic)
because then reparsing is always done during idle-time of Emacs and - maybe
even more important - it is also interruptable.
But if this idle-scheduler is switched off then ECB offers now two
possibilities (via ecb-force-reparse-when-semantic-idle-scheduler-off
):
ecb-rebuild-methods-buffer
(bound to <C-c . r>)!
This means also in consequence that the methods-buffer is not
automatically filled when a source-file is opened but first on demand
after calling the command ecb-rebuild-methods-buffer
!
The term “forcing a reparse by semantic” is a simplification: ECB uses then
the function semantic-fetch-tags
which can decide that the cached tags
are up-to-date so no real reparsing is necessary - but it can also run a full
reparse and this reparse is not being done when Emacs is idle but immediatelly
and not interruptable (as with the idle-scheduler of semantic), which can be
quite annoying with big source-files.
To make a long story short: It is strongly recommended to enable the
semantic-idle-scheduler-mode
or
global-semantic-idle-scheduler-mode
! See Setting up CEDET/semantic. This will give you in all cases the behavior you would expect
of en IDE like ECB/semantic.
ECB works out of the box with indirect buffers, especially with indirect
buffer clones created with the command clone-indirect-buffer
(only
available with GNU Emacs >= 21). They will be handled as all other buffers and
you can work with them with no difference to “normal” buffers. With one
exception:
Please note: Cause of a bug in Emacs 22 (and maybe also in Emacs 23) the propagation of parsing informations from one buffer to all others which are in an indirect-buffer relation to the same base-buffer does currently not work.
What does this mean: If you modify a buffer then Emacs propagates this change to all buffers with the same base-buffer. ECB/semantic recognize this change and do all necessary to automatically reparse the changed buffer (at least if you have customized semantic/ECB to do this). So far so good, but: If you switch to another buffer with the same base-buffer then you will notice that the methods-window of ECB still displays the contents before the change, ie. the need for a reparse has not been propagated to these other buffers. This is a bug in Emacs.
What can you do: As long as this bug is not fixed there is no chance that all
other affected “indirect-related” buffers will be reparsed automatically
after modifying one of them. So you have to do this reparse “by hand” after
switching to such an indirect-related buffer, but this is very simple: Just
call the command ecb-rebuild-methods-buffer
with prefix arg or hit
<C-u C-c . r> (key this command is bound to).
Lets make an example:
ecb-rebuild-methods-buffer
with prefix argument (ie. clear-cache is
true) or hitting <C-u C-c . r>. Note: Calling this command without prefix
argument is not enough!
There are two common types of “external” tags displayed in the method-window, mostly with object oriented programing-languages:
Tags which represent the type of a parent-class (which can be defined in the same file but which is more often defined in another file). All parents (regardless if defined internaly or externaly) of a type will be displayed under a bucket “[Parents]” in the methods-window of ECB.
In OO-languages like CLOS, eieio and C++ there can be nodes with type-tags in the method-buffer which are somehow virtual because there is no definition in the current source-file. But such a virtual type collects all its outside defined members like methods in C++ which are defined in the *.cc file whereas the class-definition is defined in the associated header-file.
In both cases the user wants to jump to the definition of the type if he clicks onto the related node in the methods-window of ECB.
Here is a C++-example for “virtual” types (2) and parent types (1) which explains this in detail:
Let's say this class is defined in a file ParentClass.h:
class ParentClass { protected: int p; };
Let's say this class is defined in a file ClassWithExternals.h
#include "ParentClass.h" class ClassWithExternals : public ParentClass { private: int i; public: ClassWithExternals(); ~ClassWithExternals(); };
Both the constructor and the destructor of the class “ClassWithExternals” are implemented in a file ClassWithExternals.cc:
#include "test.h" ClassWithExternals::ClassWithExternals(int i, boolean b, char c) { return; } void ClassWithExternals::~ClassWithExternals() { return; }
ECB displays the contents of ClassWithExternals.cc in its methods-buffer like follows:
[-] [Includes] `- test.h [-] ClassWithExternals | +ClassWithExternals (+i:int, +b:class boolean, +c:char):ClassWithExternals `- +~ClassWithExternals ():void
Both the constructor and the destructor of the class “ClassWithExternals” are grouped under their class-type. But this class-type “ClassWithExternals” is represented by a so called “virtual” or “faux” node-tag, i.e. there is no real tag in the current source-buffer for this tag.
If a user now clicks onto the node of “ClassWithExternals” then he wants to jump to the right location in the right file where “ClassWithExternals” is defined. ECB now uses now some smart mechanisms (see below) to do this. In case of success (means ECB has found the definition) it opens the right file and point will stay at beginning of the definition of the type “ClassWithExternals”.
The contents of ClassWithExternals.h are then displayed like follows:
[-] [Includes] `- ParentClass.h [-] ClassWithExternals:class | [-] [Parents] | `- ParentClass | [-] [Variables] | `- -i:int | +ClassWithExternals ():ClassWithExternals | +~ClassWithExternals ():void `- [+] [Misc]
Now let's play it again: Now we want to go to the definition of the parent-type “ParentClass” when we click onto the related node under the bucket “[Parents]”. Again ECB uses its smartness to jump to the definition of the class “ParentClass” when you click onto the node “ParentClass”.
Now lets explain the precondition which must be fulfilled so ECB can do its job:
ECB itself is quite stupid concerning finding external tags. But it can use the semantic-analyzer of the CEDET-suite (remember: The CEDET-suite is a must-requirement of ECB, see Requirements). But this in turn means that the semantic-analyzer must be customized in the right way for the needs of your programing projects. Mainly this means activating semanticdb and setting the correct include-path etc...
Please note: Read the related manuals of semantic and - strongly recommended - read in addition the article “Gentle introduction to Cedet”. It's worth to read it! The website of CEDET contains a link, you find it here: http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html
There is exactly one option you have to take into account:
ecb-find-external-tag-functions
. This defines the method ECB uses to
find these external tags.
Mostly there is nothing to do because the default values should do a good job. But if things are running bad then maybe this is the right screw for you.
Finding such external types can be very complex and there are several roads to success. ECB uses per default methods based on the semantic-analyzer. But this option allows to define own find-functions and tell ECB to uses them.
This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. ECB first performs all find-functions defined for current major-mode (if any) anf then all find-functions defined for the special symbol 'default (if any).
ECB offers some predefined senseful finding-functions. Currently there are:
ecb-search-tag-by-semantic-analyzer
: The most powerfil one, based
on the semantic-analyzer
ecb-search-tag-by-semanticdb
: A backup for the first one
ecb-jde-show-class-source
: For major-mode jde-mode
when
coding in java, uses java-mechanisms - maybe for java the best choice.
See the documentation of the option and also of these function for details how they work and how to write own finding-functions.
See ecb-methods for a list of all options currently available for customizing this ECB-window to your needs.