ecb-methods - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Next: ecb-history, Previous: ecb-sources, Up: Customizable options

#### 7.3.5 Group ecb-methods

This group contains settings for the methods-buffer in the ECB:

— User Option: auto-expand-tag-tree

> Expand the methods-tag-tree automatically if node invisible.

> This option has only an effect if option `ecb-highlight-tag-with-point` is switched on too. There are three possible choices:

> - `nil`: No auto. expanding of the method buffer.
> - `expand-spec`: Auto expand the method-buffer nodes if the node belonging to current tag under point is invisible because its parent-node is collapsed. But expanding is only done if the type of the tag under point in the edit-buffer is contained in `ecb-methods-nodes-expand-spec`.
> - `all`: Like expand-spec but expands all tags regardless of the setting in `ecb-methods-nodes-expand-spec`.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: auto-expand-tag-tree-collapse-other

> Auto. expanding the tag-tree collapses all not related nodes. There are several choices:

> - Only if on tag: This means collapsing all nodes which have no relevance for the currently highlighted node will be collapsed, because they are not necessary to make the highlighted node visible. But do this only if point stays onto a tag in the selected edit-window.
> - Always: Same as before but collapse also when point doesn't stays on a tag (e.g. between two defuns in elisp) in the selected edit-window. This means in such a situation a full collapsing of the methods-buffer.
> - Never: Do not automatically collapse the methods-buffer.

— User Option: auto-update-methods-after-save

> Automatically updating the ECB method buffer after saving a source.

— User Option: default-tag-filter

> Default tag-filters for certain files. This option allow to define default tag-filters for certain files which are applied automatically after loading such a file into a buffer. The possible filters are the same as offered by the command `ecb-methods-filter` and they are applied in the same manner - the only difference is they are applied automatically. Please be aware that symbol-filters (e.g. protection-symbols like public or private) must not be inserted with quotes whereas a filter-regexp has to be inserted with surrounding double-quotes! In addition backslashes in a regexp have to be doubled!

> For each file-spec (a major-mode plus a file-regexp which both specify a file for which filters should be applied) there can be as much filters as needed - they are layered like with `ecb-methods-filter` too.

> Tag-classes which are completely hidden or excluded by the option `ecb-show-tags` will never being displayed in the Methods-buffer regardless of the filters of this option!

— User Option: disable-semantic-threshold-alist

> Threshold for disabling semantic-parsing Define a threshold fpr buffer-size. Exceeding this threshold disables parsing current buffer by semantic.

> This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

> - The car is either a major-mode symbol or the special symbol 'default which means if no setting for a certain major-mode is defined then the cdr of the 'default cons-cell is used.
> - The cdr is an integer which defines the threshold for the buffer-size for this major-mode.

> Example:

>               ((default . 1000000)
>                 (c-mode . 200000))

> This example whould not parse c-mode buffers exceeding a buffer-size of 200000. And buffers of all other modes would be only parsed if smaller than 1000000.

> A setting of `((c-mode . 200000))` would only restrict c-mode buffers to a size of 200000 but would parse all other buffer regardless their size.

— User Option: display-image-icons-for-semantic-tags

> Display nice and pretty icons for semantic-tags in the Methods-buffer. A non nil value takes only effect if Emacs can display images and if `ecb-tree-buffer-style` is set to `image`.

— User Option: exclude-parents-regexp

> Regexps which parent classes should not be shown in the methods buffer (see also `ecb-show-parents`). If nil then all parents will be shown if `ecb-show-parents` is not nil.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: expand-methods-switch-off-auto-expand

> Switch off auto expanding in the ECB-method buffer. If on then auto expanding is switched off after explicit expanding or collapsing by `ecb-expand-methods-nodes`.

> This is done with `ecb-toggle-auto-expand-tag-tree` so after the switch off the auto expanding feature can again switched on quickly.

> But after explicitly expanding/collapsing the methods-buffer to a certain level the auto. expanding could undo this when the node belonging to current tag under point in the current active edit-window is invisible after `ecb-expand-methods-nodes` - then the auto. expand feature would make this node immediately visible and destroys the explicitly set expand-level.

— User Option: find-external-tag-functions

> Functions used for searching external tags clicked in the methods buffer.

> The methods buffer displays for oo-languages the parents of a type under a special bucket “Parents”. Languages like C++, CLOS and Eieio allow to define the implementation of a method outside of the class definition and even in another file. In the methods-buffer of ECB such externaly defined methods are collected and displayed under a `virtual` faux type-tag named as the class-qualifier of the methods. This faux-tag is virtual because it does not extist in the parsed buffer.

> If a user clicks either onto such a faux-type-tag or onto a parent-tag then ECB tries to find the definition of the underlying type on a name-basis, displaying the containing file as buffer in the current edit-window and jumping to the start of the type-definition in this buffer.

> 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. The value of this option is a list of cons-cells: The car is either a `major-mode` symbol or the special symbol 'default. The cdr is a list of find-functions or nil.

> 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` (most powerful)
> - `ecb-search-type-tag-by-semanticdb`
> - `ecb-jde-show-class-source` (for major-mode `jde-mode` when coding in java)

> This function does not only the searching but displays the founded tag. See the documentation of these function for details how they work.

> But you can add any arbitrary function if the following conditions are fulfilled:

> - The function gets a semantic tag representing the external type which should be found. This is a positionless-tag (otherwise it would not be hard to go to it) and it's either a faux-tag (for which `ecb--semantic-faux-tag-p` is not nil; the function can use this check if necessary) or a simple tag containing only a name an a tag-class. The tag-class for both is 'type.
> - The return value of the function must be one of:
>   - `nil`: No tag is found
>   - `t`: A tag has been found and also be displayed in the edit-window (this prevents ECB from running further function of this option because the searched tag is already displayed. So a function should only return `t` if all is fine and no further actions are needed.
>   - A positioned semantic tag (for which `ecb--semantic-tag-with-position-p` returns not `nil`) which represents the found external type-tag.

> It's strongly recommended for the function not to display the found location for itself but to return a positioned semantic tag! But sometimes the displaying is integrated in a third-party find-function like `jde-show-class-source` which is used by `ecb-jde-show-class-source`. In these cases the function has to return t if the searched tag has been successfully displayed.

> Precondition for a find-function: Current buffer is the buffer the clicked faux- or parent tag belongs to Current point depends on the clicked tag:

> - In case of a faux-tag it's the start of the first child of the faux-tag. There must be at least one adopted child-tag because otherwise we would not have the faux-tag
> - In case of an external parent-tag its the the start of the external tag itself.

— User Option: font-lock-tags

> Adds font-locking (means highlighting) to the ECB-method buffer.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: highlight-tag-with-point

> How to highlight the method or variable under the cursor.

> - `highlight-scroll`: Always scroll the method buffer, so the current method of the edit-window is highlighted in the method-window.
> - `highlight`: Only highlight the current method of the edit window in the method window if the method is visible in the method-window.
> - `nil`: No highlighting is done.

> See also `ecb-highlight-tag-with-point-delay`.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: highlight-tag-with-point-delay

> Time Emacs must be idle before current tag is highlighted. If nil then there is no delay, means current tag is highlighted immediately. A small value of about 0.25 seconds saves CPU resources and you get even though almost the same effect as if you set no delay. But such a delay prevents also “jumping backward/forward” during scrolling within java-classes if point goes out of method-definition into class-definition. Therefore the default value is a delay of 0.25 seconds.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: methods-buffer-after-create-hook

> Local hook running after the creation of the methods-buffer. Every function of this hook is called once without arguments direct after creating the methods-buffer of ECB and it's local key-map. So for example a function could be added which performs calls of `local-set-key` to define new keybindings only for the methods-buffer of ECB.

— User Option: methods-buffer-name

> Name of the ECB methods buffer. Because it is not a normal buffer for editing you should enclose the name with stars, e.g. “ *ECB Methods*”.

> If it is necessary for you you can get emacs-lisp access to the buffer-object of the ECB-methods-buffer by this name, e.g. by a call of `set-buffer`.

> Changes for this option at runtime will take affect only after deactivating and then activating ECB again!

— User Option: methods-filter-replace-existing

> How the methods-filter should be applied to existing filters. There are three different choices:

> - `never`: This is the default and means that calling `ecb-methods-filter` always adds the new filter on top of already existing filters. So you can combine several filter to one combined like this example: 'Display only all public methods having the string “test” in its name.' With this setting the filters can only be cleared by calling `ecb-methods-filter` and then choosing “nothing”.
> - `always`: This means that `ecb-methods-filter` always clears a previous filter before applying the new one.
> - `ask`: ECB asks if the new filter should replace the existing ones.

— User Option: methods-menu-sorter

> Function which re-sorts the menu-entries of the directories buffer.

> If a function then this function is called to sort the menu-entries of the combined menu-entries of the user-menu-extensions of `ecb-methods-menu-user-extension` and the built-in-menu `ecb-methods-menu`. If nil then no special sorting will be done and the user-extensions are placed in front of the built-in-entries.

> For the guidelines for such a sorter-function see `ecb-directories-menu-sorter`.

— User Option: methods-menu-user-extension

> Static user extensions for the popup-menu of the methods buffer. For further explanations see `ecb-directories-menu-user-extension`.

> The node-argument of a menu-function contains as data the semantic-tag of the method/variable/tag for which the popup-menu has been opened.

> Per default the static user-extensions are added at the beginning of the built-in menu-entries of `ecb-methods-menu` but the whole menu can be re-arranged with `ecb-methods-menu-sorter`.

— User Option: methods-menu-user-extension-function

> Dynamic user extensions for the popup-menu of the methods buffer. A function which has to return a list in the same format like the option `ecb-methods-menu-user-extension`. This function is called when the user opens the popup-menu for the methods buffer. For an example how such a function can be programmed see `ecb-methods-menu-editwin-entries`.

> If no dynamically evaluated menu-extensions should be added to the methods-buffer the function has to return nil. Therefore the default-value of this option is `ignore`.

> Per default the dynamic user-extensions are added in front of the static extensions of `ecb-methods-menu-user-extension` but the whole menu can be re-arranged with `ecb-methods-menu-sorter`.

— User Option: methods-nodes-collapse-spec

> Semantic tag-types collapsed by `ecb-expand-methods-nodes`. For valid values of this option see `ecb-methods-nodes-expand-spec`!

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: methods-nodes-expand-spec

> Semantic tag-types expanded by `ecb-expand-methods-nodes`.

> The value of this option is either the symbol `all` (all tags are expanded regardless of their type) or a list of symbols where each symbol is a valid semantic tag-type. For a description of semantic tag types see option `ecb-show-tags`.

> But this option also defines if bucket-nodes in the ECB-method-buffer (e.g. “[Variables]”) should be expanded. Therefore valid symbols for this list are also all cars of the variable returned by `ecb--semantic-symbol->name-assoc-list`.

> If there is a bucket-name (the node-name stripped of the settings in `ecb-bucket-node-display`) which is not contained as cdr in the value returned by `ecb--semantic-symbol->name-assoc-list` then the symbol with this bucket-name as name is also a valid symbol for this list. Example: In ECB there are buckets “[Parents]”. The bucket-name is “Parents” and the valid symbol-name is then `Parents`.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: methods-separate-prototypes

> Separate function-prototypes from the real functions. This is for example useful for C++ and C because these languages distinct between a method-prototype (rsp. function-prototype for C) and the method (rsp. function for C) itself. If this option is not nil then ECB separates the prototypes from the real function/methods. Then with `ecb-show-tags` the user can define different display-settings for each of them. If this option is nil then the prototypes and the real functions are filled in the same bucket and displayed plain and there is no sorting between prototypes and functions possible. If this option is switched on then it is senseful that `ecb-show-tags` contains for all modes which distinct between prototypes and real functions/methods two entries for the tag-type 'function - see the documentation of this option.

— User Option: methods-show-node-info

> When to display which node-info in the methods-buffer. Define which node info should displayed after moving the mouse over a node (or after a shift click onto the node) in the methods-buffer.

> You can define “when” a node-info should be displayed: See `ecb-directories-show-node-info` for the possible choices.

> You can define what info should be displayed:

> - name: Only the full node name is displayed.
> - name+type: The full name + the type of the node (function, class, variable) is displayed.

> Do NOT set this option directly via setq but use always customize!

— User Option: post-process-semantic-taglist

> Define mode-dependent post-processing for the semantic-taglist. This is an alist where the car is a major-mode symbol and the cdr is a list of function-symbols of functions which should be used for post-processing the taglist (returned by `ecb--semantic-bovinate-toplevel`) for a buffer in this major-mode. The first function in the list is called with current semantic taglist of current buffer and must return a valid taglist again. All other functions are called with the result-taglist of its preceding function and have to return a new taglist again.

> For oo-programming languages where the methods of a class can be defined outside the class-definition (e.g. C++, Eieio) the function `ecb-group-function-tags-with-parents` can be used to get a much better method-display in the methods-window of ECB, because all method implementations of a class are grouped together.

> Another senseful usage is to filter out certain tags, e.g. prototype tags in `c-mode`. For this you can set `ecb-filter-c-prototyp-tags`.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: show-only-positioned-tags

> Show only nodes in the method-buffer which are “jump-able”. If not nil then ECB displays in the method-buffer only nodes which are “jump-able”, i.e. after selecting it by clicking or with RET then ECB jumps to the corresponding location in the edit-window. Example: With CLOS or Eieio source-code there can exist some position-less nodes like variable-attributes in a `defclass` form which are only displayed if this option is nil. Displaying such nodes can be senseful even if they can not be jumped.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: show-tags

> How to show tags in the methods buffer first time after find-file. This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

> The car is either a major-mode symbol or the special symbol 'default which means if no setting for a certain major-mode is defined then the cdr of the 'default cons-cell is used. This option should always contain a default-setting!

> The cdr is a list where each element represents a type of tags:

>             (<tag type> <display type> <sort method>)

> There can be more than 1 element for a certain <tag type>. This is for example useful for C++ and C because these languages distinct between a method-prototype (rsp. function-prototype for C) and the method (rsp. function for C) itself. The default value of these option contains two entries for <tag type> is `function` whereas the first one is responsible for the “real” methods (rsp. functions) and the second one for the prototypes. So if the methods should be flattened and the prototypes collapsed the show-tags-list for C++ and C must contain two entries for <tag type> `function`, the first one defined as `flattened` and the second one defined as `collapsed`.

> The tags in the methods buffer are displayed in the order as they appear in this list.

> `<tag type>`
>   A Semantic tag type symbol (function, variable, rule, include etc.) or one of the following:
>   - `t`: All tag types not specified anywhere else in the list.
>   - `parent`: The parents of a type.
> `<display type>`
>   A symbol which describes how the tags of this type shall be shown:
>   - `expanded`: The tags are shown in an expanded node.
>   - `collapsed`: The tags are shown in a collapsed node.
>   - `flattened`: The tags are added to the parent node.
>   - `hidden`: The tags are not shown.
> `<sort method>`
>   A symbol describing how to sort the tags of this type:
>   - `name`: Sort by the tag name.
>   - `access`: Sort by tag access (public, protected, private) and then by name.
>   - `nil`: Don't sort tags. They appear in the same order as in the source buffer.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: tag-display-function

> Function to use for displaying tags in the methods buffer. This functionality is set on major-mode base, i.e. for every major-mode a different function can be used. The value of this option is a list of cons-cells:

> - The car is either a major-mode symbol or the special symbol 'default which means if no function for a certain major-mode is defined then the cdr of the 'default cons-cell is used.
> - The cdr is the function used for displaying a tag in the related major-mode.

> Every function is called with 3 arguments:

> 1. The tag
> 2. The parent-tag of tag (can be nil)
> 3. The value of `ecb-font-lock-tags`.

> Every function must return the display of the tag as string, colorized if the third argument is not nil.

> The following functions are predefined:

> - For each element E of `ecb--semantic-format-function-alist` exists a function with name “ecb–<(cdr E)>”. These functions are just aliase to the builtin format-functions of semantic. See the docstring of these functions to see what they do. Example: (semantic-name-nonterminal . semantic-format-tag-name) is an element of `ecb--semantic-format-function-alist`. Therefore the alias-function for this element is named `ecb--semantic-format-tag-name`.
> - For every cdr in `ecb--semantic-format-function-alist` with name “semantic-XYZ” a function with name “ecb-XYC” is predefined. The differences between the semantic- and the ECB-version are:
>   - The ECB-version displays for type tags only the type-name and nothing else (exception: In c++-mode a template specifier is appended to the type-name if a template instead a normal class).
>   - The ECB-version displays type-tags according to the setting in `ecb-type-tag-display`. This is useful for better recognizing different classes, structs etc. in the ECB-method window.

>   For all tags which are not types the display of the ECB-version is identical to the semantic version. Example: For `ecb--semantic-format-tag-name` (one of the builtin semantic formatters) the pendant is `ecb-format-tag-name`.

> This functionality also allows the user to display tags as UML. To enable this functionality set the function for a major-mode \(e.g. `jde-mode`) to `ecb--semantic-format-tag-uml-concise-prototype`, `ecb--semantic-format-tag-uml-prototype`, or `ecb--semantic-format-tag-uml-abbreviate` the ECB-versions of these functions.

> If the value is `nil`, i.e. neither a function for a major-mode is defined nor the special 'default, then `ecb--semantic-format-tag-prototype` is used for displaying the tags.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: tag-jump-sets-mark

> Set the mark after jumping to a tag from the ECB-method buffer. If set the user can easily jump back.

— User Option: tag-visit-post-actions

> Actions to perform after visiting a tag from the Method-buffer. With this option actions can be added which will be performed after visiting the start of the tag in the source-buffer.

> This functionality is set on a `major-mode` base, i.e. for every `major-mode` a different setting can be used. The value of this option is a list of cons-cells:

> - The car is either a `major-mode` symbol or the special symbol 'default.
> - The cdr is a list of action-functions or nil.

> ECB first performs all actions defined for the special symbol 'default (if any) and then all actions defined for current `major-mode` (if any).

> ECB offers some predefined senseful action-functions. Currently there are: `ecb-tag-visit-highlight-tag-header` `ecb-tag-visit-smart-tag-start` `ecb-tag-visit-recenter` `ecb-tag-visit-recenter-top` `ecb-tag-visit-goto-doc-start` `ecb-tag-visit-narrow-tag` See the documentation of these function for details what they do.

> But you can add any arbitrary function if the following conditions are fulfilled: The function gets the semantic tag as argument, returns the (new) point after finishing its job and the function must not put the point outside the tag-boundaries of the tag-argument.

— User Option: type-tag-display

> How to display semantic type-tags in the methods buffer. Normally all tag displaying, colorizing and facing is done by semantic according to the value returned by `ecb--semantic-format-face-alist` and the semantic display-function (e.g. one from `ecb--semantic-format-tag-functions`). But sometimes a finer distinction in displaying the different type specifiers of type-tags can be useful. For a description when this option is evaluated look at `ecb-tag-display-function`!

> This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

> - The car is either a major-mode symbol or the special symbol 'default which means if no setting for a certain major-mode is defined then the cdr of the 'default cons-cell is used.
> - The cdr is a list of 3-element-lists:
>   1. First entry is a semantic type specifier in string-form. Current available type specifiers are for example “class”, “interface”, “struct”, “typedef” and “enum”. In addition to these ones there is also a special ECB type specifier “group” which is related to grouping tags (see `ecb-post-process-semantic-taglist` and `ecb-group-function-tags-with-parents`). Any arbitrary specifier can be set here but if it is not “group” or not known by semantic it will be useless.
>   2. Second entry is a flag which indicates if the type-specifier string from (1.) itself should be removed (if there is any) from the display.
>   3. Third entry is the face which is used in the ECB-method window to display type-tags with this specifier. ECB has some predefined faces for this (`ecb-type-tag-class-face`, `ecb-type-tag-interface-face`, `ecb-type-tag-struct-face`, `ecb-type-tag-typedef-face`, `ecb-type-tag-union-face`, `ecb-type-tag-enum-face` and `ecb-type-tag-group-face`) but any arbitrary face can be set here. This face is merged with the faces semantic already uses to display a tag, i.e. the result is a display where all face-attributes of the ECB-face take effect plus all face-attributes of the semantic-faces which are not set in the ECB-face (with XEmacs this merge doesn't work so here the ECB-face replaces the semantic-faces; this may be fixed in future versions).

> The default value is nil means there is no special ECB-displaying of type-tags in addition to the displaying and colorizing semantic does. But a value like the following could be a useful setting:

>             ((default
>                ("class" t ecb-type-tag-class-face)
>                ("group" nil ecb-type-tag-group-face))
>              (c-mode
>               ("struct" nil ecb-type-tag-struct-face)
>               ("typedef" nil ecb-type-tag-typedef-face)))

> This means that in `c-mode` only “struct”s and “typedef”s are displayed with special faces (the specifiers itself are not removed) and in all other modes “class”s and grouping-tags (see `ecb-tag-display-function`, `ecb-group-function-tags-with-parents`) have special faces and the “class” specifier-string is removed from the display.

> This options takes only effect for semantic-sources - means sources supported by semantic!

— User Option: type-tag-expansion

> Default expansion of semantic type-tags. Semantic groups type-tags in different type-specifiers. Current available type specifiers are for example “class”, “interface”, “struct”, “typedef”, “union” and “enum”. In addition to these ones there is also a special ECB type-specifier “group” which is related to grouping tags (see `ecb-post-process-semantic-taglist`).

> This option defines which type-specifiers should be expanded at file-open-time. Any arbitrary specifier can be set here but if it is not “group” or not known by semantic it will be useless.

> This functionality is set on a major-mode base, i.e. for every major-mode a different setting can be used. The value of this option is a list of cons-cells:

> - The car is either a major-mode symbol or the special symbol `default` which means if no setting for a certain major-mode is defined then the cdr of the `default` cons-cell is used.
> - The cdr is either a list of type-specifiers which should be expanded at file-open-time or the symbol `all-specifiers` (then a type-tag is always expanded regardless of its type-specifier).

> This options takes only effect for semantic-sources - means sources supported by semantic!