Next: , Previous: ECB Sources-window, Up: Basic ECB-windows


4.1.5 The ECB Methods-window

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).

4.1.5.1 Usage of the methods ECB-window
4.1.5.2 Activating/Displaying the methods ECB-window

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).

4.1.5.3 Synchronizing the Methods-window with current source-buffer

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):

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.

4.1.5.4 Synchronizing with indirect buffers

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:

  1. Suppose we have a sourcefile test.java loaded as a buffer into Emacs and suppose further we have created two indirect-buffer clones test-clone1.java and test-clone2.java - all of these buffers point to the same file: test.java.
  2. Now lets be the buffer test-clone1.java the current buffer and let us modify it (e.g. adding a new method). If you have enabled the idle-reparse mechanism of semantic (see Setting up CEDET/semantic) then this buffer will be reparsed automatically and ECBs methods-window will be updated in turn too.
  3. So far so good. But if you now switch to one of the two other buffers, lets say to test.java, then you will notice that the change done in test-clone1.java is also visible in the buffer test.java but the ECB-methods-window for test.java will display the contents before the change. This is cause of the Emacs-bug described above.
  4. To update the methods-window for test.java to the new contents you have to call 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!
4.1.5.5 Jumping to the definition of external types

There are two common types of “external” tags displayed in the method-window, mostly with object oriented programing-languages:

  1. parent-types

    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.

  2. “virtual” types

    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:

4.1.5.6 Customizing the methods ECB-window

See ecb-methods for a list of all options currently available for customizing this ECB-window to your needs.