Jumping to external tags - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Previous: Updating for ind. buffers, Up: The Methods window

#### 6.6.6 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:

- Customizing the semantic analyzer for your needs

  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

- Customize the related options of ECB:

  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-type-tag-by-semantic-analyzer`: The most powerfil one, based on the semantic-analyzer
  - `ecb-search-type-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.