6. Customizing

Speedbar is highly customizable, with a plethora of control elements. Since speedbar is so visual and reduces so much information, this is an important aspect of its behavior.

In general, there are three custom groups you can use to quickly modify speedbar's behavior.

speedbar

Basic speedbar behaviors.

speedbar-vc

Customizations regarding version control handling.

speedbar-faces

Customize speedbar's many colors and fonts.

6.1 Frames and Faces

There are several faces speedbar generates to provide a consistent color scheme across display types. You can customize these faces using your favorite method. They are:

speedbar-button-face

Face used on expand/contract buttons.

speedbar-file-face

Face used on Files. Should also be used on non-directory like nodes.

speedbar-directory-face

Face used for directories, or nodes which consist of groups of other nodes.

speedbar-tag-face

Face used for tags in a file, or for leaf items.

speedbar-selected-face

Face used to highlight the selected item. This would be the current file being edited.

speedbar-highlight-face

Face used when the mouse passes over a button.

You can also customize speedbar's initial frame parameters. How this is accomplished is dependent on your platform being Emacs or XEmacs.

In Emacs, change the alist speedbar-frame-parameters. This variable is used to set up initial details. Height is also automatically added when speedbar is created, though you can override it.

In XEmacs, change the plist speedbar-frame-plist. This is the XEmacs way of doing the same thing.

6.2 Tag Hierarchy Methods

When listing tags within a file, it is possible to get an annoyingly long list of entries. Imenu (which generates the tag list in Emacs) will group some classes of items automatically. Even here, however, some tag groups can be quite large.

To solve this problem, tags can be grouped into logical units through a hierarchy processor. The specific variable to use is speedbar-tag-hierarchy-method. There are several methods that can be applied in any order. They are:

speedbar-trim-words-tag-hierarchy

Find a common prefix for all elements of a group, and trim it off.

speedbar-prefix-group-tag-hierarchy

If a group is too large, place sets of tags into bins based on common prefixes.

speedbar-simple-group-tag-hierarchy

Take all items in the top level list not in a group, and stick them into a `Tags' group.

speedbar-sort-tag-hierarchy

Sort all items, leaving groups on top.

You can also add your own functions to reorganize tags as you see fit.

Some other control variables are:

speedbar-tag-group-name-minimum-length

Default value: 4.

The minimum length of a prefix group name before expanding. Thus, if the speedbar-tag-hierarchy-method includes speedbar-prefix-group-tag-hierarchy and one such group's common characters is less than this number of characters, then the group name will be changed to the form of:

worda to wordb

instead of just

word

This way we won't get silly looking listings.

speedbar-tag-split-minimum-length

Default value: 20.

Minimum length before we stop trying to create sub-lists in tags. This is used by all tag-hierarchy methods that break large lists into sub-lists.

speedbar-tag-regroup-maximum-length

Default value: 10.

Maximum length of submenus that are regrouped. If the regrouping option is used, then if two or more short subgroups are next to each other, then they are combined until this number of items is reached.

6.3 Version Control

When using the file mode in speedbar, information regarding a version control system adds small details to the display. If a file is in a version control system, and is "checked out" or "locked" locally, an asterisk `*' appears at the end of the file name. In addition, the directory name for Version Control systems are left out of the speedbar display.

You can easily add new version control systems into speedbar's detection scheme. To make a directory "disappear" from the list, use the variable speedbar-directory-unshown-regexp.

Next, you need to write entries for two hooks. The first is speedbar-vc-directory-enable-hook which will enable a VC check in the current directory for the group of files being checked. Your hook function should take one parameter (the directory to check) and return t if your VC method is in control here.

The second function is speedbar-vc-in-control-hook. This hook takes two parameters, the path of the file to check, and the file name. Return t if you want to have the asterisk placed near this file.

Lastly, you can change the VC indicator using the variable speedbar-vc-indicator, and specify a single character string.

6.4 Hooks

There are several hooks in speedbar allowing custom behaviors to be added. Available hooks are:

speedbar-visiting-file-hook

Hooks run when speedbar visits a file in the selected frame.

speedbar-visiting-tag-hook

Hooks run when speedbar visits a tag in the selected frame.

speedbar-load-hook

Hooks run when speedbar is loaded.

speedbar-reconfigure-keymaps-hook

Hooks run when the keymaps are regenerated. Keymaps are reconfigured whenever modes change. This will let you add custom key bindings.

speedbar-before-popup-hook

Hooks called before popping up the speedbar frame. New frames are often popped up when "power clicking" on an item to view it.

speedbar-before-delete-hook

Hooks called before deleting or hiding the speedbar frame.

speedbar-mode-hook

Hooks called after creating a speedbar buffer.

speedbar-timer-hook

Hooks called after running the speedbar timer function.

speedbar-scanner-reset-hook

Hook called whenever generic scanners are reset. Set this to implement your own scanning or rescan safe functions with state data.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.