1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/speedbar.info
3 @settitle Speedbar: File/Tag summarizing utility
8 Copyright @copyright{} 1999--2017 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.3 or
13 any later version published by the Free Software Foundation; with no
14 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
15 and with the Back-Cover Texts as in (a) below. A copy of the license
16 is included in the section entitled ``GNU Free Documentation License''.
18 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
19 modify this GNU manual.''
23 @dircategory Emacs misc features
25 * Speedbar: (speedbar). File/Tag summarizing utility.
30 @center @titlefont{Speedbar}
33 @vskip 0pt plus 1 fill
35 @vskip 0pt plus 1filll
44 Speedbar is a program for Emacs which can be used to summarize
45 information related to the current buffer. Its original inspiration
46 is the ``explorer'' often used in modern development environments, office
47 packages, and web browsers.
49 Speedbar displays a narrow frame in which a tree view is shown. This
50 tree view defaults to containing a list of files and directories. Files
51 can be ``expanded'' to list tags inside. Directories can be expanded to
52 list the files within them. Each file or tag can be jumped to
55 Speedbar expands upon ``explorer'' windows by maintaining context with the
56 user. For example, when using the file view, the current buffer's file
57 is highlighted. Speedbar also mimics the explorer windows by providing
58 multiple display modes. These modes come in two flavors. Major display
59 modes remain consistent across buffers, and minor display modes appear
60 only when a buffer of the applicable type is shown. This allows
61 authors of other packages to provide speedbar summaries customized to
62 the needs of that mode.
64 Throughout this manual, activities are defined as ``clicking on'', or
65 ``expanding'' items. Clicking means using @kbd{mouse-2} on a
66 button. Expanding refers to clicking on an expansion button to display
67 an expanded summary of the entry the expansion button is
68 on. @xref{Basic Navigation}.
75 * Introduction:: Basics of speedbar.
76 * Basic Navigation:: Basics of speedbar common between all modes.
77 * File Mode:: Summarizing files.
78 * Buffer Mode:: Summarizing buffers.
79 * Minor Modes:: Additional minor modes such as Info and RMAIL.
80 * Customizing:: Changing speedbar behavior.
81 * Extending:: Extend speedbar for your own project.
82 * GNU Free Documentation License:: The license for this documentation.
90 To start using speedbar use the command @kbd{M-x speedbar RET} or
91 select it from the @samp{Options->Show/Hide} sub-menu. This command
92 will open a new frame to summarize the local files. On X Window
93 systems or on MS-Windows, speedbar's frame is twenty characters wide,
94 and will mimic the height of the frame from which it was started. It
95 positions itself to the left or right of the frame you started it
98 To use speedbar effectively, it is important to understand its
99 relationship with the frame you started it from. This frame is the
100 @dfn{attached frame} which speedbar will use as a reference point. Once
101 started, speedbar watches the contents of this frame, and attempts to
102 make its contents relevant to the buffer loaded into the attached
103 frame. In addition, all requests made in speedbar that require the
104 display of another buffer will display in the attached frame.
106 When used in terminal mode, the new frame appears the same size as the
107 terminal. Since it is not visible while working in the attached frame,
108 speedbar will save time by using the @dfn{slowbar mode}, where no tracking is
109 done until speedbar is requested to show itself (i.e., the speedbar's
110 frame becomes the selected frame).
112 @cindex @code{speedbar-get-focus}
113 The function to use when switching between frames using the keyboard is
114 @code{speedbar-get-focus}. This function will toggle between frames, and
115 it's useful to bind it to a key in terminal mode. @xref{Customizing}.
117 @node Basic Navigation
118 @chapter Basic Navigation
120 Speedbar can display different types of data, and has several display
121 and behavior modes. These modes all have a common behavior, menu
122 system, and look. If one mode is learned, then the other modes are easy
126 * Basic Key Bindings::
132 @node Basic Key Bindings
133 @section Basic Key Bindings
136 These key bindings are common across all modes:
140 @cindex quitting speedbar
141 Quit speedbar, and kill the frame.
143 Quit speedbar, and hide the frame. This makes it faster to restore the
144 speedbar frame, than if you press @kbd{Q}.
146 @cindex refresh speedbar display
147 Refresh whatever contents are in speedbar.
150 Toggle speedbar to and from slowbar mode. In slowbar mode, frame
151 tracking is not done.
155 Move, respectively, to the next or previous item. A summary of that
156 item will be displayed in the attached frame's minibuffer.
159 Move to the next or previous item in a restricted fashion. If a list is
160 open, the cursor will skip over it. If the cursor is in an open list,
161 it will not leave it.
164 Move forwards and backwards across extended groups. This lets you
165 quickly skip over all files, directories, or other common sub-items at
166 the same current depth.
168 Switch buffers in the attached frame.
171 Speedbar can handle multiple modes. Two are provided by default.
172 These modes are File mode, and Buffers mode. There are accelerators to
173 switch into these different modes.
175 @cindex mode switching hotkeys
178 Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the
179 previous display mode is restored.
181 Switch into File mode.
183 Switch back to the previous mode.
186 Some modes provide groups, lists and tags. @xref{Basic Visuals}. When
187 these are available, some additional common bindings are available.
193 Edit/Open the current group or tag. This behavior is dependent on the
194 mode. In general, files or buffers are opened in the attached frame,
195 and directories or group nodes are expanded locally.
198 Expand the current group, displaying sub items.
199 When used with a prefix argument, any data that may have been cached is
200 flushed. This is similar to a power click. @xref{Mouse Bindings}.
202 Contract the current group, hiding sub items.
206 @section Basic Visuals
209 Speedbar has visual cues for indicating different types of data. These
210 cues are used consistently across the different speedbar modes to make
211 them easier to interpret.
213 At a high level, in File mode, there are directory buttons, sub
214 directory buttons, file buttons, tag buttons, and expansion buttons.
215 This makes it easy to use the mouse to navigate a directory tree, and
216 quickly view files, or a summary of those files.
218 The most basic visual effect used to distinguish between these button
219 types is color and mouse highlighting. Anything the mouse highlights
220 can be clicked on and is called a button (@pxref{Mouse Bindings}).
221 Anything not highlighted by the mouse will not be clickable.
223 Text in speedbar consists of four different types of data. Knowing how
224 to read these textual elements will make it easier to navigate by
225 identifying the types of data available.
230 Groups summarize information in a single line, and provide a high level
231 view of more complex systems, like a directory tree, or manual chapters.
233 Groups appear at different indentation levels, and are prefixed with a
234 @samp{+} in some sort of ``box''. The group name will summarize the
235 information within it, and the expansion box will display that
236 information inline. In File mode, directories and files are ``groups''
237 where the @samp{+} is surrounded by brackets like this:
245 In this example, we see both open and closed directories, in addition to
246 a file. The directories have a box consisting of angle brackets, and a
247 file uses square brackets.
249 In all modes, a group can be ``edited'' by pressing @kbd{RET}, meaning a
250 file will be opened, or a directory explicitly opened in speedbar. A
251 group can be expanded or contracted using @kbd{+} or
252 @kbd{-}. @xref{Basic Key Bindings}.
254 Sometimes groups may have a @samp{?} in its indicator box. This means
255 that it is a group type, but there are no contents, or no known way of
256 extracting contents of that group.
258 When a group has been expanded, the indicator button changes from
259 @samp{+} to @samp{-}. This indicates that the contents are being shown.
260 Click the @samp{-} button to contract the group, or hide the contents
266 Tags are the leaf nodes of the tree system. Tags are generally prefixed
267 with a simple character, such as @samp{>}. Tags can only be jumped to using
268 @kbd{RET} or @kbd{e}.
270 @subsubsection Boolean Flags
272 Sometimes a group or tag is given a boolean flag. These flags appear as
273 extra text characters at the end of the line. File mode uses boolean
274 flags, such as a @samp{*} to indicate that a file has been checked out
275 of a versioning system.
277 For additional flags, see
278 @c Note to self, update these to sub-nodes which are more relevant.
279 @ref{File Mode}, and @ref{Version Control}.
281 @subsubsection Unadorned Text
283 Unadorned text generally starts in column 0, without any special symbols
284 prefixing them. In Buffers mode different buffer groups are prefixed
285 with a description of what the following buffers are (Files, scratch
286 buffers, and invisible buffers.)
288 Unadorned text will generally be colorless, and not clickable.
290 @subsubsection Color Cues
292 Each type of Group, item indicator, and label is given a different
293 color. The colors chosen are dependent on whether the background color
295 Of important note is that the ``current item'', which may be a buffer or
296 file name, is highlighted red, and underlined.
298 Colors can be customized from the group @code{speedbar-faces}. Some
299 modes, such as for Info, will use the Info colors instead of default
300 speedbar colors as an indication of what is currently being displayed.
302 The face naming convention mirrors the File display mode. Modes which
303 do not use files will attempt to use the same colors on analogous
307 @section Mouse Bindings
308 @cindex mouse bindings
310 The mouse has become a common information navigation tool. Speedbar
311 will use the mouse to navigate file systems, buffer lists, and other
312 data. The different textual cues provide buttons which can be clicked
313 on (@pxref{Basic Visuals}). Anything that highlights can be clicked on
314 with the mouse, or affected by the menu.
316 The mouse bindings are:
320 Move cursor to that location.
322 @itemx Double-mouse-1
323 Activate the current button. @kbd{Double-mouse-1} is called a @dfn{double
324 click} on other platforms, and is useful for windows users with two
326 @c Isn't it true that with two-button mice, the right button is mouse-2?
327 @c On GNU/Linux, the right button is mouse-3.
329 @itemx S-Double-mouse-1
331 This has the same effect as @kbd{mouse-2}, except it is called a power
332 click. This means that if a group with an expansion button @samp{+} is
333 clicked, any caches are flushed, and subitems re-read. If it is a name,
334 it will be opened in a new frame.
336 Activate the speedbar menu. The item selected affects the line clicked,
337 not the line where the cursor was.
338 @item mouse-1 @r{(mode line)}
339 Activate the menu. This affects the item the cursor is on before the
340 click, since the mouse was not clicked on anything.
342 Buffers sub-menu. The buffer in the attached frame is switched.
345 When the mouse moves over buttons in speedbar, details of that item
346 should be displayed in the minibuffer of the attached frame. Sometimes
347 this can contain extra information such as file permissions, or tag
350 @node Displays Submenu
351 @section Displays Submenu
352 @cindex displays submenu
354 You can display different data by using different display modes. These
355 specialized modes make it easier to navigate the relevant pieces of
356 information, such as files and directories, or buffers.
358 In the main menu, found by clicking @kbd{mouse-3}, there is a submenu
359 labeled @samp{Displays}. This submenu lets you easily choose between
360 different display modes.
362 The contents are modes currently loaded into emacs. By default, this
363 would include Files, Quick Buffers, and Buffers. Other major display
364 modes such as Info are loaded separately.
370 File mode displays a summary of your current directory. You can display
371 files in the attached frame, or summarize the tags found in files. You
372 can even see if a file is checked out of a version control system, or
373 has some associated object file.
375 Advanced behavior, like copying and renaming files, is also provided.
378 * Directory Display:: What the display means.
379 * Hidden Files:: How to display hidden files.
380 * File Key Bindings:: Performing file operations.
383 @node Directory Display
384 @section Directory Display
385 @cindex directory display
387 There are three major sections in the display. The first line or two is
388 the root directory speedbar is currently viewing. You can jump to one
389 of the parent directories by clicking on the name of the directory you
392 Next, directories are listed. A directory starts with the group
393 indicator button @samp{<+>}. Clicking the directory name makes speedbar
394 load that directory as the root directory for its display. Clicking the
395 @samp{<+>} button will list all directories and files beneath.
397 Next, files are listed. Files start with the group indicator @samp{[+]}
398 or @samp{[?]}. You can jump to a file in the attached frame by clicking
399 on the file name. You can expand a file and look at its tags by
400 clicking on the @samp{[+]} symbol near the file name.
402 A typical session might look like this:
426 In this example, you can see several directories. The directory
427 @file{speedbar} has been opened inline. Inside the directory
428 @file{speedbar}, the file @file{speedbar.el} has its tags exposed.
429 These tags are extensive, and they are summarized into tag groups.
431 Files get additional boolean flags associated with them. Valid flags are:
436 This file has been checked out of a version control
437 system. @xref{Version Control}.
438 @cindex @code{speedbar-obj-alist}
440 This file has an up to date object file associated with it. The
441 variable @code{speedbar-obj-alist} defines how speedbar determines this
444 This file has an out of date object file associated with it.
447 A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this
448 symbol will show all symbols that have been organized into that group.
449 Different types of files have unique tagging methods as defined by their
450 major mode. Tags are generated with either the @code{imenu} package, or
451 through the @code{etags} interface.
453 Tag groups are defined in multiple ways which make it easier to find the
454 tag you are looking for. Imenu keywords explicitly create groups, and
455 speedbar will automatically create groups if tag lists are too long.
457 In our example, Imenu created the groups @samp{Types} and
458 @samp{Variables}. All remaining top-level symbols are then regrouped
459 based on the variable @code{speedbar-tag-hierarchy-method}. The
460 subgroups @samp{def} and @samp{speedbar-} are groupings where the first
461 few characters of the given symbols are specified in the group name.
462 Some group names may say something like @samp{speedbar-t to speedbar-v},
463 indicating that all symbols which alphabetically fall between those
464 categories are included in that sub-group. @xref{Tag Hierarchy Methods}.
467 @section Hidden Files
470 On GNU and Unix systems, a hidden file is a file whose name starts
471 with a period. They are hidden from a regular directory listing
472 because the user is not generally interested in them.
474 In speedbar, a hidden file is a file which isn't very interesting and
475 might prove distracting to the user. Any uninteresting files are
476 removed from the File display. There are two levels of uninterest in
477 speedbar. The first level of uninterest are files which have no
478 expansion method, or way of extracting tags. The second level is any
479 file that matches the same pattern used for completion in
480 @code{find-file}. This is derived from the variable
481 @code{completion-ignored-extensions}.
483 You can toggle the display of uninteresting files from the toggle menu
484 item @samp{Show All Files}. This will display all level one hidden files.
485 These files will be shown with a @samp{?} indicator. Level 2 hidden
486 files will still not be shown.
488 Object files fall into the category of level 2 hidden files. You can
489 determine their presence by the @samp{#} and @samp{!} file indicators.
490 @xref{Directory Display}.
492 @node File Key Bindings
493 @section File Key Bindings
494 @cindex file key bindings
496 File mode has key bindings permitting different file system operations
497 such as copy or rename. These commands all operate on the @dfn{current
498 file}. In this case, the current file is the file at point, or clicked
499 on when pulling up the menu.
503 Move the entire speedbar display up one directory.
505 Display information in the minibuffer about this line. This is the same
506 information shown when navigating with @kbd{n} and @kbd{p}, or moving
507 the mouse over an item.
509 Byte compile the Emacs Lisp file on this line.
511 Load the Emacs Lisp file on this line. If a @file{.elc} file exists,
512 optionally load that.
514 Copy the current file to some other location.
516 Rename the current file, possibly moving it to some other location.
518 Delete the current file.
520 Delete the current file's object file. Use the symbols @samp{#} and
521 @samp{!} to determine if there is an object file available.
524 One menu item toggles the display of all available files. By default,
525 only files which Emacs understands, and knows how to convert into a tag
526 list, are shown. By showing all files, additional files such as text files are
527 also displayed, but they are prefixed with the @samp{[?]} symbol. This
528 means that it is a file, but Emacs doesn't know how to expand it.
534 Buffer mode is very similar to File mode, except that instead of
535 tracking the current directory and all files available there, the
536 current list of Emacs buffers is shown.
538 These buffers can have their tags expanded in the same way as files,
539 and uses the same unknown file indicator (@pxref{File Mode}).
541 Buffer mode does not have file operation bindings, but the following
542 buffer specific key bindings are available:
546 Kill this buffer. Do not touch its file.
548 Revert this buffer, reloading from disk.
551 In addition to Buffer mode, there is also Quick Buffer mode. In fact,
552 Quick Buffers is bound to the @kbd{b} key. The only difference between
553 Buffers and Quick Buffers is that after one operation is performed
554 which affects the attached frame, the display is immediately reverted to
555 the last displayed mode.
557 Thus, if you are in File mode, and you need quick access to a buffer,
558 press @kbd{b}, click on the buffer you want, and speedbar will revert
562 @chapter Minor Display Modes
563 @cindex minor display modes
565 For some buffers, a list of files and tags makes no sense. This could
566 be because files are not currently in reference (such as web pages), or
567 that the files you might be interested have special properties (such as
570 In these cases, a minor display mode is needed. A minor display mode
571 will override any major display mode currently being displayed for the
572 duration of the specialized buffer's use. Minor display modes
573 will follow the general rules of their major counterparts in terms of
574 key bindings and visuals, but will have specialized behaviors.
577 * RMAIL:: Managing folders.
578 * Info:: Browsing topics.
579 * GDB:: Watching expressions or managing the current
587 When using RMAIL, speedbar will display two sections. The first is a
588 layer one reply button. Clicking here will initialize a reply buffer
589 showing only this email address in the @samp{To:} field.
591 The second section lists all RMAIL folders in the same directory as your
592 main RMAIL folder. The general rule is that RMAIL folders always appear
593 in all caps, or numbers. It is possible to save mail in folders with
594 lower case letters, but there is no clean way of detecting such RMAIL folders
595 without opening them all.
597 Each folder can be visited by clicking the name. You can move mail from
598 the current RMAIL folder into a different folder by clicking the
599 @samp{<M>} button. The @samp{M} stands for Move.
601 In this way you can manage your existing RMAIL folders fairly easily
608 When browsing Info files, all local relevant information is displayed in
609 the info buffer and a topical high-level view is provided in speedbar.
610 All top-level info nodes are shown in the speedbar frame, and can be
611 jumped to by clicking the name.
613 You can open these nodes with the @samp{[+]} button to see what sub-topics
614 are available. Since these sub-topics are not examined until you click
615 the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on
616 a @samp{[+]}, indicating that there are no sub-topics.
623 You can debug an application with GDB in Emacs using graphical mode or
624 text command mode (@pxref{GDB Graphical Interface,,, emacs, The
625 extensible self-documenting text editor}).
627 If you are using graphical mode you can see how selected variables
628 change each time your program stops (@pxref{Watch Expressions,,,
629 emacs, The extensible self-documenting text editor}).
631 If you are using text command mode, speedbar can show
632 you the current stack when the current buffer is the @file{*gdb*}
633 buffer. Usually, it will just report that there is no stack, but when
634 the application is stopped, the current stack will be shown.
636 You can click on any stack element and gdb will move to that stack
637 level. You can then check variables local to that level at the GDB
644 Speedbar is highly customizable, with a plethora of control elements.
645 Since speedbar is so visual and reduces so much information, this is an
646 important aspect of its behavior.
648 In general, there are three custom groups you can use to quickly modify
653 Basic speedbar behaviors.
655 Customizations regarding version control handling.
657 Customize speedbar's many colors and fonts.
661 * Frames and Faces:: Visible behaviors.
662 * Tag Hierarchy Methods:: Customizing how tags are displayed.
663 * Version Control:: Adding new VC detection modes.
664 * Hooks:: The many hooks you can use.
667 @node Frames and Faces
668 @section Frames and Faces
670 @cindex frame parameters
672 There are several faces speedbar generates to provide a consistent
673 color scheme across display types. You can customize these faces using
674 your favorite method. They are:
677 @cindex @code{speedbar-button-face}
678 @item speedbar-button-face
679 Face used on expand/contract buttons.
680 @cindex @code{speedbar-file-face}
681 @item speedbar-file-face
682 Face used on Files. Should also be used on non-directory like nodes.
683 @cindex @code{speedbar-directory-face}
684 @item speedbar-directory-face
685 Face used for directories, or nodes which consist of groups of other nodes.
686 @cindex @code{speedbar-tag-face}
687 @item speedbar-tag-face
688 Face used for tags in a file, or for leaf items.
689 @cindex @code{speedbar-selected-face}
690 @item speedbar-selected-face
691 Face used to highlight the selected item. This would be the current
693 @cindex @code{speedbar-highlight-face}
694 @item speedbar-highlight-face
695 Face used when the mouse passes over a button.
698 You can also customize speedbar's initial frame parameters. How this is
699 accomplished is dependent on your platform being Emacs or XEmacs.
701 @cindex @code{speedbar-frame-parameters}, Emacs
702 In Emacs, change the alist @code{speedbar-frame-parameters}. This
703 variable is used to set up initial details. Height is also
704 automatically added when speedbar is created, though you can override
707 @cindex @code{speedbar-frame-plist}, XEmacs
708 In XEmacs, change the plist @code{speedbar-frame-plist}. This is the
709 XEmacs way of doing the same thing.
711 @node Tag Hierarchy Methods
712 @section Tag Hierarchy Methods
713 @cindex tag hierarchy
717 When listing tags within a file, it is possible to get an annoyingly
718 long list of entries. Imenu (which generates the tag list in Emacs)
719 will group some classes of items automatically. Even here, however,
720 some tag groups can be quite large.
722 @cindex @code{speedbar-tag-hierarchy-method}
723 To solve this problem, tags can be grouped into logical units through a
724 hierarchy processor. The specific variable to use is
725 @code{speedbar-tag-hierarchy-method}. There are several methods that
726 can be applied in any order. They are:
729 @cindex @code{speedbar-trim-words-tag-hierarchy}
730 @item speedbar-trim-words-tag-hierarchy
731 Find a common prefix for all elements of a group, and trim it off.
732 @cindex @code{speedbar-prefix-group-tag-hierarchy}
733 @item speedbar-prefix-group-tag-hierarchy
734 If a group is too large, place sets of tags into bins based on common
736 @cindex @code{speedbar-simple-group-tag-hierarchy}
737 @item speedbar-simple-group-tag-hierarchy
738 Take all items in the top level list not in a group, and stick them into
740 @cindex @code{speedbar-sort-tag-hierarchy}
741 @item speedbar-sort-tag-hierarchy
742 Sort all items, leaving groups on top.
745 You can also add your own functions to reorganize tags as you see fit.
747 Some other control variables are:
750 @cindex @code{speedbar-tag-group-name-minimum-length}
751 @item speedbar-tag-group-name-minimum-length
754 The minimum length of a prefix group name before expanding. Thus, if
755 the @code{speedbar-tag-hierarchy-method} includes
756 @code{speedbar-prefix-group-tag-hierarchy} and one such group's common
757 characters is less than this number of characters, then the group name
758 will be changed to the form of:
770 This way we won't get silly looking listings.
772 @cindex @code{speedbar-tag-split-minimum-length}
773 @item speedbar-tag-split-minimum-length
776 Minimum length before we stop trying to create sub-lists in tags.
777 This is used by all tag-hierarchy methods that break large lists into
780 @cindex @code{speedbar-tag-regroup-maximum-length}
781 @item speedbar-tag-regroup-maximum-length
784 Maximum length of submenus that are regrouped.
785 If the regrouping option is used, then if two or more short subgroups
786 are next to each other, then they are combined until this number of
790 @node Version Control
791 @section Version Control
792 @cindex version control
793 @cindex vc extensions
795 When using the file mode in speedbar, information regarding a version
796 control system adds small details to the display. If a file is in a
797 version control system, and is ``checked out'' or ``locked'' locally, an
798 asterisk @samp{*} appears at the end of the file name. In addition,
799 the directory name for Version Control systems are left out of the
802 @cindex @code{speedbar-directory-unshown-regexp}
803 You can easily add new version control systems into speedbar's detection
804 scheme. To make a directory ``disappear'' from the list, use the variable
805 @code{speedbar-directory-unshown-regexp}.
807 @cindex @code{speedbar-vc-path-enable-hook}
808 Next, you need to write entries for two hooks. The first is
809 @code{speedbar-vc-path-enable-hook} which will enable a VC check in the
810 current directory for the group of files being checked. Your hook
811 function should take one parameter (the directory to check) and return
812 @code{t} if your VC method is in control here.
814 @cindex @code{speedbar-vc-in-control-hook}
815 The second function is @code{speedbar-vc-in-control-hook}. This hook
816 takes two parameters, the @var{path} of the file to check, and the
817 @var{file} name. Return @code{t} if you want to have the asterisk
818 placed near this file.
820 @cindex @code{speedbar-vc-indicator}
821 Lastly, you can change the VC indicator using the variable
822 @code{speedbar-vc-indicator}, and specify a single character string.
828 There are several hooks in speedbar allowing custom behaviors to be
829 added. Available hooks are:
832 @cindex @code{speedbar-visiting-file-hook}
833 @item speedbar-visiting-file-hook
834 Hooks run when speedbar visits a file in the selected frame.
835 @cindex @code{speedbar-visiting-tag-hook}
836 @item speedbar-visiting-tag-hook
837 Hooks run when speedbar visits a tag in the selected frame.
838 @cindex @code{speedbar-load-hook}
839 @item speedbar-load-hook
840 Hooks run when speedbar is loaded.
841 @cindex @code{speedbar-reconfigure-keymaps-hook}
842 @item speedbar-reconfigure-keymaps-hook
843 Hooks run when the keymaps are regenerated. Keymaps are reconfigured
844 whenever modes change. This will let you add custom key bindings.
845 @cindex @code{speedbar-before-popup-hook}
846 @item speedbar-before-popup-hook
847 Hooks called before popping up the speedbar frame.
848 New frames are often popped up when ``power clicking'' on an item to view
850 @cindex @code{speedbar-before-delete-hook}
851 @item speedbar-before-delete-hook
852 Hooks called before deleting or hiding the speedbar frame.
853 @cindex @code{speedbar-mode-hook}
854 @item speedbar-mode-hook
855 Hooks called after creating a speedbar buffer.
856 @cindex @code{speedbar-timer-hook}
857 @item speedbar-timer-hook
858 Hooks called after running the speedbar timer function.
859 @cindex @code{speedbar-scanner-reset-hook}
860 @item speedbar-scanner-reset-hook
861 Hook called whenever generic scanners are reset.
862 Set this to implement your own scanning or rescan safe functions with
870 Speedbar can run different types of Major display modes such as Files
871 (@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage
872 different minor display modes for use with buffers handling specialized
875 These major and minor display modes are handled through an extension
876 system which permits specialized keymaps and menu extensions, in
877 addition to a unique rendering function. You can also specify a wide
878 range of tagging functions. The default uses @code{imenu}, but new
879 tagging methods can be easily added. In this chapter, you will
880 learn how to write your own major or minor display modes, and how to
881 create specialized tagging functions.
884 * Minor Display Modes:: How to create a minor display mode.
885 * Major Display Modes:: How to create a major display mode.
886 * Tagging Extensions:: How to create your own tagging methods.
887 * Creating a display:: How to insert buttons and hierarchies.
890 @node Minor Display Modes
891 @section Minor Display Modes
892 @cindex create minor display mode
894 A @dfn{minor display mode} is a mode useful when using a specific type of
895 buffer. This mode might not be useful for any other kind of data or
896 mode, or may just be more useful that a files or buffers based mode when
897 working with a specialized mode.
899 Examples that already exist for speedbar include RMAIL, Info, and gdb.
900 These modes display information specific to the major mode shown in the
903 To enable a minor display mode in your favorite Major mode, follow these
904 steps. The string @samp{@var{name}} is the name of the major mode being
905 augmented with speedbar.
909 Create the keymap variable @code{@var{name}-speedbar-key-map}.
912 Create a function, named whatever you like, which assigns values into your
913 keymap. Use this command to create the keymap before assigning
917 (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap))
920 This function creates a special keymap for use in speedbar.
923 Call your install function, or assign it to a hook like this:
926 (if (featurep 'speedbar)
927 (@var{name}-install-speedbar-variables)
928 (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))
932 Create an easymenu compatible vector named
933 @code{@var{name}-speedbar-menu-items}. This will be spliced into
934 speedbar's control menu.
937 Create a function called @code{@var{name}-speedbar-buttons}. This function
938 should take one variable, which is the buffer for which it will create
939 buttons. At this time @code{(current-buffer)} will point to the
940 uncleared speedbar buffer.
943 When writing @code{@var{name}-speedbar-buttons}, the first thing you will
944 want to do is execute a check to see if you need to re-create your
945 display. If it needs to be cleared, you need to erase the speedbar
946 buffer yourself, and start drawing buttons. @xref{Creating a display}.
948 @node Major Display Modes
949 @section Major Display Modes
950 @cindex create major display mode
952 Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap,
953 an easy-menu segment, and writing several functions. These items can be
954 given any name, and are made the same way as in a minor display mode
955 (@pxref{Minor Display Modes}). Once this is done, these items need to be
958 Because this setup activity may or may not have speedbar available when
959 it is being loaded, it is necessary to create an install function. This
960 function should create and initialize the keymap, and add your
961 expansions into the customization tables.
963 @cindex @code{speedbar-make-specialized-keymap}
964 When creating the keymap, use the function
965 @code{speedbar-make-specialized-keymap} instead of other keymap making
966 functions. This will provide you with the initial bindings needed.
967 Some common speedbar functions you might want to bind are:
970 @cindex @code{speedbar-edit-line}
971 @item speedbar-edit-line
972 Edit the item on the current line.
973 @cindex @code{speedbar-expand-line}
974 @item speedbar-expand-line
975 Expand the item under the cursor.
976 With a numeric argument (@kbd{C-u}), flush cached data before expanding.
977 @cindex @code{speedbar-contract-line}
978 @item speedbar-contract-line
979 Contract the item under the cursor.
982 @cindex @code{speedbar-line-path}
983 These function require that function @code{speedbar-line-path} be
984 correctly overloaded to work.
986 Next, register your extension like this;
989 (speedbar-add-expansion-list '("MyExtension"
990 MyExtension-speedbar-menu-items
991 MyExtension-speedbar-key-map
992 MyExtension-speedbar-buttons))
995 There are no limitations to the names you use.
997 The first parameter is the string representing your display mode.
998 The second parameter is a variable name containing an easymenu compatible
999 menu definition. This will be stuck in the middle of speedbar's menu.
1000 The third parameter is the variable name containing the keymap we
1002 The last parameter is a function which draws buttons for your mode.
1003 This function must take two parameters. The directory currently being
1004 displayed, and the depth at which you should start rendering buttons.
1005 The function will then draw (starting at the current cursor position)
1006 any buttons deemed necessary based on the input parameters.
1007 @xref{Creating a display}.
1009 Next, you need to register function overrides. This may look something
1013 (speedbar-add-mode-functions-list
1015 (speedbar-item-info . MyExtension-speedbar-item-info)
1016 (speedbar-line-path . MyExtension-speedbar-line-path)))
1019 The first element in the list is the name of you extension. The second
1020 is an alist of functions to overload. The function to overload is
1021 first, followed by what you want called instead.
1023 For @code{speedbar-line-path} your function should take an optional DEPTH
1024 parameter. This is the starting depth for heavily indented lines. If
1025 it is not provided, you can derive it like this:
1032 (looking-at "^\\([0-9]+\\):")
1033 (setq depth (string-to-number (match-string 1)))))
1037 where the depth is stored as invisible text at the beginning of each
1040 The path returned should be the full path name of the file associated
1041 with that line. If the cursor is on a tag, then the file containing
1042 that tag should be returned. This is critical for built in file based
1043 functions to work (meaning less code for you to write). If your display
1044 does not deal in files, you do not need to overload this function.
1046 @cindex @code{speedbar-item-info}
1047 The function @code{speedbar-item-info}, however, is very likely to need
1048 overloading. This function takes no parameters and must derive a text
1049 summary to display in the minibuffer.
1051 There are several helper functions you can use if you are going to use
1052 built in tagging. These functions can be @code{or}ed since each one
1053 returns non-@code{nil} if it displays a message. They are:
1056 @cindex @code{speedbar-item-info-file-helper}
1057 @item speedbar-item-info-file-helper
1058 This takes an optional @var{filename} parameter. You can derive your own
1059 filename, or it will derive it using a (possibly overloaded) function
1060 @code{speedbar-line-file}. It shows details about a file.
1061 @cindex @code{speedbar-item-info-tag-helper}
1062 @item speedbar-item-info-tag-helper
1063 If the current line is a tag, then display information about that tag,
1064 such as its parent file, and location.
1067 Your custom function might look like this:
1070 (defun MyExtension-item-info ()
1071 "Display information about the current line."
1072 (or (speedbar-item-info-tag-helper)
1073 (message "Interesting detail.")))
1076 Once you have done all this, speedbar will show an entry in the
1077 @samp{Displays} menu declaring that your extension is available.
1079 @node Tagging Extensions
1080 @section Tagging Extensions
1082 It is possible to create new methods for tagging files in speedbar.
1083 To do this, you need two basic functions, one function to fetch the
1084 tags from a buffer, the other to insert them below the filename.
1086 @defun my-fetch-dynamic-tags file
1087 Parse @var{file} for a list of tags. Return the list, or @code{t} if there was
1091 The non-error return value can be anything, as long as it can be
1092 inserted by its paired function:
1094 @defun my-insert-tag-list level lst
1095 Insert a list of tags @var{lst} started at indentation level
1096 @var{level}. Creates buttons for each tag, and provides any other
1097 display information required.
1100 @cindex @code{speedbar-create-tag-hierarchy}
1101 It is often useful to use @code{speedbar-create-tag-hierarchy} on your
1102 token list. See that function's documentation for details on what it
1105 @cindex @code{speedbar-dynamic-tags-function-list}
1106 Once these two functions are written, modify the variable
1107 @code{speedbar-dynamic-tags-function-list} to include your parser at the
1108 beginning, like this:
1111 (add-to-list 'speedbar-dynamic-tags-function-list
1112 '(my-fetch-dynamic-tags . my-insert-tag-list))
1115 If your parser is only good for a few types of files, make sure that it
1116 is either a buffer local modification, or that the tag generator returns
1117 @code{t} for non valid buffers.
1119 @node Creating a display
1120 @section Creating a display
1121 @cindex creating a display
1123 Rendering a display in speedbar is completely flexible. When your
1124 button function is called, see @ref{Minor Display Modes}, and @ref{Major
1125 Display Modes}, you have control to @code{insert} anything you want.
1127 The conventions allow almost anything to be inserted, but several helper
1128 functions are provided to make it easy to create the standardized
1131 To understand the built in functions, each ``button'' in speedbar consists
1132 of four important pieces of data. The text to be displayed, token
1133 data to be associated with the text, a function to call, and some face to
1136 When a function is provided, then that text becomes mouse activated,
1137 meaning the mouse will highlight the text.
1139 Additionally, for data which can form deep trees, each line is given a
1140 depth which indicates how far down the tree it is. This information is
1141 stored in invisible text at the beginning of each line, and is used by
1142 the navigation commands.
1144 @defun speedbar-insert-button text face mouse function &optional token prevline
1145 This function inserts one button into the current location.
1146 @var{text} is the text to insert. @var{face} is the face in which it
1147 will be displayed. @var{mouse} is the face to display over the text
1148 when the mouse passes over it. @var{function} is called whenever the
1149 user clicks on the text.
1151 The optional argument @var{token} is extra data to associated with the
1152 text. Lastly @var{prevline} should be non-@code{nil} if you want this line to
1153 appear directly after the last button which was created instead of on
1157 @defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth
1159 Create a tag line with @var{exp-button-type} for the small expansion
1160 button. This is the button that expands or contracts a node (if
1161 applicable), and @var{exp-button-char} the character in it (@samp{+},
1162 @samp{-}, @samp{?}, etc.). @var{exp-button-function} is the function
1163 to call if it's clicked on. Button types are @code{bracket},
1164 @code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and
1165 @code{nil}. @var{exp-button-data} is extra data attached to the text
1166 forming the expansion button.
1168 Next, @var{tag-button} is the text of the tag.
1169 @var{tag-button-function} is the function to call if clicked on, and
1170 @var{tag-button-data} is the data to attach to the text field (such a
1171 tag positioning, etc.). @var{tag-button-face} is a face used for this
1174 Lastly, @var{depth} shows the depth of expansion.
1176 This function assumes that the cursor is in the speedbar window at the
1177 position to insert a new item, and that the new item will end with a CR.
1180 @defun speedbar-insert-generic-list level list expand-fun find-fun
1182 At @var{level}, (the current indentation level desired) insert a generic
1183 multi-level alist @var{list}. Associations with lists get @samp{@{+@}}
1184 tags (to expand into more nodes) and those with positions or other data
1185 just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the
1186 function @var{expand-fun} and the token is the @code{cdr} list. The
1187 token name will have the function @var{find-fun} and not token.
1189 Each element of the list can have one of these forms:
1192 @item (@var{name} . marker-or-number)
1193 One tag at this level.
1194 @item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... )
1196 @item (@var{name} marker-or-number (@var{name} . marker-or-number) ... )
1197 One Group of tags where the group has a starting position.
1200 When you use @code{speedbar-insert-generic-list}, there are some
1201 variables you can set buffer-locally to change the behavior. The most
1202 obvious is @code{speedbar-tag-hierarchy-method}.
1203 @xref{Tag Hierarchy Methods}.
1205 @defvar speedbar-generic-list-group-expand-button-type
1206 This is the button type used for groups of tags, whether expanded
1207 or added in via a hierarchy method. Two good values are
1208 @code{curly} and @code{expandtag}. Curly is the default button, and
1209 @code{expandtag} is useful if the groups also has a position.
1212 @defvar speedbar-generic-list-tag-button-type
1213 This is the button type used for a single tag.
1214 Two good values are @code{nil} and @code{statictag}.
1215 @code{nil} is the default, and @code{statictag} has the same width as
1221 @node GNU Free Documentation License
1222 @appendix GNU Free Documentation License
1223 @include doclicense.texi
1227 @unnumbered Concept Index
1231 @c LocalWords: speedbar's xref slowbar kbd subsubsection
1232 @c LocalWords: keybindings