1 \input texinfo @c -*-texinfo-*-
3 @c $Id: speedbar.texi,v 1.7 2007-11-26 15:02:20 michaels Exp $
6 @c This file is part of GNU Emacs
8 @c GNU Emacs is free software; you can redistribute it and/or modify it
9 @c under the terms of the GNU General Public License as published by the
10 @c Free Software Foundation; either version 2 of the License, or (at
11 @c your option) any later version.
13 @c GNU Emacs is distributed in the hope that it will be useful, but
14 @c WITHOUT ANY WARRANTY; without even the implied warranty of
15 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 @c General Public License for more details.
18 @c You should have received a copy of the GNU General Public License
19 @c along with GNU Emacs; see the file COPYING. If not, write to the
20 @c Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 @c Boston, MA 02110-1301, USA.
23 @setfilename speedbar.info
24 @settitle Speedbar: File/Tag summarizing utility
28 * Speedbar: (speedbar). File/Tag summarizing utility.
31 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2005 Free Software Foundation, Inc.
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.2 or
36 any later version published by the Free Software Foundation; with the
37 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
38 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
39 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
40 license is included in the section entitled ``GNU Free Documentation
41 License'' in the Emacs manual.
43 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
44 this GNU Manual, like GNU software. Copies published by the Free
45 Software Foundation raise funds for GNU development.''
47 This document is part of a collection distributed under the GNU Free
48 Documentation License. If you want to distribute this document
49 separately from the collection, you can do so by adding a copy of the
50 license to the document, as described in section 6 of the license.
56 * Speedbar: (speedbar). File/Tag summarizing utility.
61 @center @titlefont{Speedbar}
64 @vskip 0pt plus 1 fill
66 @vskip 0pt plus 1filll
72 @node Top, , , (dir)Top
73 @comment node-name, next, previous, up
75 Speedbar is a program for Emacs which can be used to summarize
76 information related to the current buffer. Its original inspiration
77 is the `explorer' often used in modern development environments, office
78 packages, and web browsers.
80 Speedbar displays a narrow frame in which a tree view is shown. This
81 tree view defaults to containing a list of files and directories. Files
82 can be `expanded' to list tags inside. Directories can be expanded to
83 list the files within itself. Each file or tag can be jumped to
86 Speedbar expands upon `explorer' windows by maintaining context with the
87 user. For example, when using the file view, the current buffer's file
88 is highlighted. Speedbar also mimics the explorer windows by providing
89 multiple display modes. These modes come in two flavors. Major display
90 modes remain consistent across buffers, and minor display modes appear
91 only when a buffer of the applicable type is shown. This allows
92 authors of other packages to provide speedbar summaries customized to
93 the needs of that mode.
95 Throughout this manual, activities are defined as `clicking on', or
96 `expanding' items. Clicking means using @kbd{Mouse-2} on a
97 button. Expanding refers to clicking on an expansion button to display
98 an expanded summary of the entry the expansion button is
99 on. @xref{Basic Navigation}.
102 * Introduction:: Basics of speedbar.
103 * Basic Navigation:: Basics of speedbar common between all modes.
104 * File Mode:: Summarizing files.
105 * Buffer Mode:: Summarizing buffers.
106 * Minor Modes:: Additional minor modes such as Info and RMAIL.
107 * Customizing:: Changing speedbar behavior.
108 * Extending:: Extend speedbar for your own project.
112 @node Introduction, Basic Navigation, , Top
113 @comment node-name, next, previous, up
114 @chapter Introduction
117 To start using speedbar use the command @kbd{M-x speedbar RET} or select
118 it from the Tools menu in versions of Emacs with speedbar installed by
119 default. This command will open a new frame to summarize the local
120 files. On X Window systems or on MS-Windows, speedbar's frame is twenty
121 characters wide, and will mimic the height of the frame from which it
122 was started. It positions itself to the left or right of the frame you
125 To use speedbar effectively, it is important to understand its
126 relationship with the frame you started it from. This frame is the
127 @dfn{attached frame} which speedbar will use as a reference point. Once
128 started, speedbar watches the contents of this frame, and attempts to
129 make its contents relevant to the buffer loaded into the attached
130 frame. In addition, all requests made in speedbar that require the
131 display of another buffer will display in the attached frame.
133 When used in terminal mode, the new frame appears the same size as the
134 terminal. Since it is not visible while working in the attached frame,
135 speedbar will save time by using the @dfn{slowbar mode}, where no tracking is
136 done until speedbar is requested to show itself (i.e., the speedbar's
137 frame becomes the selected frame).
139 @cindex @code{speedbar-get-focus}
140 The function to use when switching between frames using the keyboard is
141 @code{speedbar-get-focus}. This function will toggle between frames, and
142 it's useful to bind it to a key in terminal mode. @xref{Customizing}.
144 @node Basic Navigation, File Mode, Introduction, Top
145 @comment node-name, next, previous, up
146 @chapter Basic Navigation
148 Speedbar can display different types of data, and has several display
149 and behavior modes. These modes all have a common behavior, menu
150 system, and look. If one mode is learned, then the other modes are easy
154 * Basic Key Bindings::
160 @node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation
161 @comment node-name, next, previous, up
162 @section Basic Key Bindings
165 These key bindings are common across all modes:
169 @cindex quitting speedbar
170 Quit speedbar, and kill the frame.
172 Quit speedbar, and hide the frame. This makes it faster to restore the
173 speedbar frame, than if you press @kbd{Q}.
175 @cindex refresh speedbar display
176 Refresh whatever contents are in speedbar.
179 Toggle speedbar to and from slowbar mode. In slowbar mode, frame
180 tracking is not done.
184 Move, respectively, to the next or previous item. A summary of that
185 item will be displayed in the attached frame's minibuffer.
188 Move to the next or previous item in a restricted fashion. If a list is
189 open, the cursor will skip over it. If the cursor is in an open list,
190 it will not leave it.
193 Move forwards and backwards across extended groups. This lets you
194 quickly skip over all files, directories, or other common sub-items at
195 the same current depth.
197 Switch buffers in the attached frame.
200 Speedbar can handle multiple modes. Two are provided by default.
201 These modes are File mode, and Buffers mode. There are accelerators to
202 switch into these different modes.
204 @cindex mode switching hotkeys
207 Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the
208 previous display mode is restored.
210 Switch into File mode.
212 Switch back to the previous mode.
215 Some modes provide groups, lists and tags. @xref{Basic Visuals}. When
216 these are available, some additional common bindings are available.
222 Edit/Open the current group or tag. This behavior is dependent on the
223 mode. In general, files or buffers are opened in the attached frame,
224 and directories or group nodes are expanded locally.
227 Expand the current group, displaying sub items.
228 When used with a prefix argument, any data that may have been cached is
229 flushed. This is similar to a power click. @xref{Mouse Bindings}.
231 Contract the current group, hiding sub items.
234 @node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation
235 @comment node-name, next, previous, up
236 @section Basic Visuals
239 Speedbar has visual cues for indicating different types of data. These
240 cues are used consistently across the different speedbar modes to make
241 them easier to interpret.
243 At a high level, in File mode, there are directory buttons, sub
244 directory buttons, file buttons, tag buttons, and expansion buttons.
245 This makes it easy to use the mouse to navigate a directory tree, and
246 quickly view files, or a summary of those files.
248 The most basic visual effect used to distinguish between these button
249 types is color and mouse highlighting. Anything the mouse highlights
250 can be clicked on and is called a button (@pxref{Mouse Bindings}).
251 Anything not highlighted by the mouse will not be clickable.
253 Text in speedbar consists of four different types of data. Knowing how
254 to read these textual elements will make it easier to navigate by
255 identifying the types of data available.
260 Groups summarize information in a single line, and provide a high level
261 view of more complex systems, like a directory tree, or manual chapters.
263 Groups appear at different indentation levels, and are prefixed with a
264 @samp{+} in some sort of `box'. The group name will summarize the
265 information within it, and the expansion box will display that
266 information inline. In File mode, directories and files are `groups'
267 where the @samp{+} is surrounded by brackets like this:
275 In this example, we see both open and closed directories, in addition to
276 a file. The directories have a box consisting of angle brackets, and a
277 file uses square brackets.
279 In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a
280 file will be opened, or a directory explicitly opened in speedbar. A
281 group can be expanded or contracted using @kbd{+} or
282 @kbd{-}. @xref{Basic Key Bindings}.
284 Sometimes groups may have a @samp{?} in its indicator box. This means
285 that it is a group type, but there are no contents, or no known way of
286 extracting contents of that group.
288 When a group has been expanded, the indicator button changes from
289 @samp{+} to @samp{-}. This indicates that the contents are being shown.
290 Click the @samp{-} button to contract the group, or hide the contents
296 Tags are the leaf nodes of the tree system. Tags are generally prefixed
297 with a simple character, such as @samp{>}. Tags can only be jumped to using
298 @kbd{RET} or @kbd{e}.
300 @subsection Boolean Flags
302 Sometimes a group or tag is given a boolean flag. These flags appear as
303 extra text characters at the end of the line. File mode uses boolean
304 flags, such as a @samp{*} to indicate that a file has been checked out
305 of a versioning system.
307 For additional flags, see
308 @c Note to self, update these to sub-nodes which are more relevant.
309 @ref{File Mode}, and @ref{Version Control}.
311 @subsection Unadorned Text
313 Unadorned text generally starts in column 0, without any special symbols
314 prefixing them. In Buffers mode different buffer groups are prefixed
315 with a description of what the following buffers are (Files, scratch
316 buffers, and invisible buffers.)
318 Unadorned text will generally be colorless, and not clickable.
320 @subsection Color Cues
322 Each type of Group, item indicator, and label is given a different
323 color. The colors chosen are dependent on whether the background color
325 Of important note is that the `current item', which may be a buffer or
326 file name, is highlighted red, and underlined.
328 Colors can be customized from the group @code{speedbar-faces}. Some
329 modes, such as for Info, will use the Info colors instead of default
330 speedbar colors as an indication of what is currently being displayed.
332 The face naming convention mirrors the File display mode. Modes which
333 do not use files will attempt to use the same colors on analogous
336 @node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation
337 @comment node-name, next, previous, up
338 @section Mouse Bindings
339 @cindex mouse bindings
341 The mouse has become a common information navigation tool. Speedbar
342 will use the mouse to navigate file systems, buffer lists, and other
343 data. The different textual cues provide buttons which can be clicked
344 on (@pxref{Basic Visuals}). Anything that highlights can be clicked on
345 with the mouse, or affected by the menu.
347 The mouse bindings are:
351 Move cursor to that location.
353 @itemx Double-Mouse-1
354 Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double
355 click} on other platforms, and is useful for windows users with two
357 @c Isn't it true that with two-button mice, the right button is Mouse-2?
358 @c On GNU/Linux, the right button is Mouse-3.
360 @itemx S-Double-Mouse-1
362 This has the same effect as @kbd{Mouse-2}, except it is called a power
363 click. This means that if a group with an expansion button @samp{+} is
364 clicked, any caches are flushed, and subitems re-read. If it is a name,
365 it will be opened in a new frame.
367 Activate the speedbar menu. The item selected affects the line clicked,
368 not the line where the cursor was.
369 @item Mouse-1 @r{(mode line)}
370 Activate the menu. This affects the item the cursor is on before the
371 click, since the mouse was not clicked on anything.
373 Buffers sub-menu. The buffer in the attached frame is switched.
376 When the mouse moves over buttons in speedbar, details of that item
377 should be displayed in the minibuffer of the attached frame. Sometimes
378 this can contain extra information such as file permissions, or tag
381 @node Displays Submenu, , Mouse Bindings, Basic Navigation
382 @comment node-name, next, previous, up
383 @section Displays Submenu
384 @cindex displays submenu
386 You can display different data by using different display modes. These
387 specialized modes make it easier to navigate the relevant pieces of
388 information, such as files and directories, or buffers.
390 In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu
391 labeled @samp{Displays}. This submenu lets you easily choose between
392 different display modes.
394 The contents are modes currently loaded into emacs. By default, this
395 would include Files, Quick Buffers, and Buffers. Other major display
396 modes such as Info are loaded separately.
398 @node File Mode, Buffer Mode, Basic Navigation, Top
399 @comment node-name, next, previous, up
403 File mode displays a summary of your current directory. You can display
404 files in the attached frame, or summarize the tags found in files. You
405 can even see if a file is checked out of a version control system, or
406 has some associated object file.
408 Advanced behavior, like copying and renaming files, is also provided.
411 * Directory Display:: What the display means.
412 * Hidden Files:: How to display hidden files.
413 * File Key Bindings:: Performing file operations.
416 @node Directory Display, Hidden Files, File Mode, File Mode
417 @comment node-name, next, previous, up
418 @section Directory Display
419 @cindex directory display
421 There are three major sections in the display. The first line or two is
422 the root directory speedbar is currently viewing. You can jump to one
423 of the parent directories by clicking on the name of the directory you
426 Next, directories are listed. A directory starts with the group
427 indicator button @samp{<+>}. Clicking the directory name makes speedbar
428 load that directory as the root directory for its display. Clicking the
429 @samp{<+>} button will list all directories and files beneath.
431 Next, files are listed. Files start with the group indicator @samp{[+]}
432 or @samp{[?]}. You can jump to a file in the attached frame by clicking
433 on the file name. You can expand a file and look at its tags by
434 clicking on the @samp{[+]} symbol near the file name.
436 A typical session might look like this:
460 In this example, you can see several directories. The directory
461 @file{speedbar} has been opened inline. Inside the directory
462 @file{speedbar}, the file @file{speedbar.el} has its tags exposed.
463 These tags are extensive, and they are summarized into tag groups.
465 Files get additional boolean flags associated with them. Valid flags are:
470 This file has been checked out of a version control
471 system. @xref{Version Control}.
472 @cindex @code{speedbar-obj-alist}
474 This file has an up to date object file associated with it. The
475 variable @code{speedbar-obj-alist} defines how speedbar determines this
478 This file has an out of date object file associated with it.
481 A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this
482 symbol will show all symbols that have been organized into that group.
483 Different types of files have unique tagging methods as defined by their
484 major mode. Tags are generated with either the @code{imenu} package, or
485 through the @code{etags} interface.
487 Tag groups are defined in multiple ways which make it easier to find the
488 tag you are looking for. Imenu keywords explicitly create groups, and
489 speedbar will automatically create groups if tag lists are too long.
491 In our example, Imenu created the groups @samp{Types} and
492 @samp{Variables}. All remaining top-level symbols are then regrouped
493 based on the variable @code{speedbar-tag-hierarchy-method}. The
494 subgroups @samp{def} and @samp{speedbar-} are groupings where the first
495 few characters of the given symbols are specified in the group name.
496 Some group names may say something like @samp{speedbar-t to speedbar-v},
497 indicating that all symbols which alphabetically fall between those
498 categories are included in that sub-group. @xref{Tag Hierarchy Methods}.
500 @node Hidden Files, File Key Bindings, Directory Display, File Mode
501 @comment node-name, next, previous, up
502 @section Hidden Files
505 On GNU and Unix systems, a hidden file is a file whose name starts
506 with a period. They are hidden from a regular directory listing
507 because the user is not generally interested in them.
509 In speedbar, a hidden file is a file which isn't very interesting and
510 might prove distracting to the user. Any uninteresting files are
511 removed from the File display. There are two levels of uninterest in
512 speedbar. The first level of uninterest are files which have no
513 expansion method, or way of extracting tags. You can define which
514 files are interesting with
515 @code{speedbar-supported-extension-expressions}. The second level is
516 any file that matches the same pattern used for completion in
517 @code{find-file}. This is derived from the variable
518 @code{completion-ignored-extensions}. This filter will override the
519 supported extensions, so if you add something to be supported, and
520 it doesn't appear, check for this.
522 You can toggle the display of uninteresting files from the toggle menu
523 item @samp{Show All Files}. This will display all level one hidden files.
524 These files will be shown with a @samp{?} indicator. Level 2 hidden
525 files will still not be shown.
527 Object files fall into the category of level 2 hidden files. You can
528 determine their presence by the @samp{#} and @samp{!} file indicators.
529 @xref{Directory Display}.
531 @node File Key Bindings, , Hidden Files, File Mode
532 @comment node-name, next, previous, up
533 @section File Key Bindings
534 @cindex file key bindings
536 File mode has key bindings permitting different file system operations
537 such as copy or rename. These commands all operate on the @dfn{current
538 file}. In this case, the current file is the file at point, or clicked
539 on when pulling up the menu.
543 Move the entire speedbar display up one directory.
545 Display information in the minibuffer about this line. This is the same
546 information shown when navigating with @kbd{n} and @kbd{p}, or moving
547 the mouse over an item.
549 Byte compile the Emacs Lisp file on this line.
551 Load the Emacs Lisp file on this line. If a @file{.elc} file exists,
552 optionally load that.
554 Copy the current file to some other location.
556 Rename the current file, possibly moving it to some other location.
558 Delete the current file.
560 Delete the current file's object file. Use the symbols @samp{#} and
561 @samp{!} to determine if there is an object file available.
564 One menu item toggles the display of all available files. By default,
565 only files which Emacs understands, and knows how to convert into a tag
566 list, are shown. By showing all files, additional files such as text files are
567 also displayed, but they are prefixed with the @samp{[?]} symbol. This
568 means that it is a file, but Emacs doesn't know how to expand it.
570 @node Buffer Mode, Minor Modes, File Mode, Top
571 @comment node-name, next, previous, up
575 Buffer mode is very similar to File mode, except that instead of
576 tracking the current directory and all files available there, the
577 current list of Emacs buffers is shown.
579 These buffers can have their tags expanded in the same way as files,
580 and uses the same unknown file indicator (@pxref{File Mode}).
582 Buffer mode does not have file operation bindings, but the following
583 buffer specific key bindings are available:
587 Kill this buffer. Do not touch its file.
589 Revert this buffer, reloading from disk.
592 In addition to Buffer mode, there is also Quick Buffer mode. In fact,
593 Quick Buffers is bound to the @kbd{b} key. The only difference between
594 Buffers and Quick Buffers is that after one operation is performed
595 which affects the attached frame, the display is immediately reverted to
596 the last displayed mode.
598 Thus, if you are in File mode, and you need quick access to a buffer,
599 press @kbd{b}, click on the buffer you want, and speedbar will revert
602 @node Minor Modes, Customizing, Buffer Mode, Top
603 @comment node-name, next, previous, up
604 @chapter Minor Display Modes
605 @cindex minor display modes
607 For some buffers, a list of files and tags makes no sense. This could
608 be because files are not currently in reference (such as web pages), or
609 that the files you might be interested have special properties (such as
612 In these cases, a minor display mode is needed. A minor display mode
613 will override any major display mode currently being displayed for the
614 duration of the specialized buffer's use. Minor display modes
615 will follow the general rules of their major counterparts in terms of
616 key bindings and visuals, but will have specialized behaviors.
619 * RMAIL:: Managing folders in speedbar
620 * Info:: Browsing topics in speedbar
621 * GDB:: Managing the current stack trace in speedbar
624 @node RMAIL, Info, Minor Modes, Minor Modes
625 @comment node-name, next, previous, up
629 When using RMAIL, speedbar will display two sections. The first is a
630 layer one reply button. Clicking here will initialize a reply buffer
631 showing only this email address in the @samp{To:} field.
633 The second section lists all RMAIL folders in the same directory as your
634 main RMAIL folder. The general rule is that RMAIL folders always appear
635 in all caps, or numbers. It is possible to save mail in folders with
636 lower case letters, but there is no clean way of detecting such RMAIL folders
637 without opening them all.
639 Each folder can be visited by clicking the name. You can move mail from
640 the current RMAIL folder into a different folder by clicking the
641 @samp{<M>} button. The @samp{M} stands for Move.
643 In this way you can manage your existing RMAIL folders fairly easily
646 @node Info, GDB, RMAIL, Minor Modes
647 @comment node-name, next, previous, up
651 When browsing Info files, all local relevant information is displayed in
652 the info buffer and a topical high-level view is provided in speedbar.
653 All top-level info nodes are shown in the speedbar frame, and can be
654 jumped to by clicking the name.
656 You can open these nodes with the @samp{[+]} button to see what sub-topics
657 are available. Since these sub-topics are not examined until you click
658 the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on
659 a @samp{[+]}, indicating that there are no sub-topics.
661 @node GDB, , Info, Minor Modes
662 @comment node-name, next, previous, up
667 If you are debugging an application with GDB in Emacs, speedbar can show
668 you the current stack when the current buffer is the @file{*gdb*}
669 buffer. Usually, it will just report that there is no stack, but when
670 the application is stopped, the current stack will be shown.
672 You can click on any stack element and gdb will move to that stack
673 level. You can then check variables local to that level at the GDB
676 This mode has the unfortunate side-effect of breaking GDB's repeat
677 feature when you hit @kbd{RET} since your previous command is overridden
678 with a stack fetching command.
680 @node Customizing, Extending, Minor Modes, Top
681 @comment node-name, next, previous, up
685 Speedbar is highly customizable, with a plethora of control elements.
686 Since speedbar is so visual and reduces so much information, this is an
687 important aspect of its behavior.
689 In general, there are three custom groups you can use to quickly modify
694 Basic speedbar behaviors.
696 Customizations regarding version control handling.
698 Customize speedbar's many colors and fonts.
702 * Frames and Faces:: Visible behaviors.
703 * Tag Hierarchy Methods:: Customizing how tags are displayed.
704 * Version Control:: Adding new VC detection modes.
705 * Hooks:: The many hooks you can use.
708 @node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing
709 @comment node-name, next, previous, up
710 @section Frames and Faces
712 @cindex frame parameters
714 There are several faces speedbar generates to provide a consistent
715 color scheme across display types. You can customize these faces using
716 your favorite method. They are:
719 @cindex @code{speedbar-button-face}
720 @item speedbar-button-face
721 Face used on expand/contract buttons.
722 @cindex @code{speedbar-file-face}
723 @item speedbar-file-face
724 Face used on Files. Should also be used on non-directory like nodes.
725 @cindex @code{speedbar-directory-face}
726 @item speedbar-directory-face
727 Face used for directories, or nodes which consist of groups of other nodes.
728 @cindex @code{speedbar-tag-face}
729 @item speedbar-tag-face
730 Face used for tags in a file, or for leaf items.
731 @cindex @code{speedbar-selected-face}
732 @item speedbar-selected-face
733 Face used to highlight the selected item. This would be the current
735 @cindex @code{speedbar-highlight-face}
736 @item speedbar-highlight-face
737 Face used when the mouse passes over a button.
740 You can also customize speedbar's initial frame parameters. How this is
741 accomplished is dependent on your platform being Emacs or XEmacs.
743 @cindex @code{speedbar-frame-parameters}, Emacs
744 In Emacs, change the alist @code{speedbar-frame-parameters}. This
745 variable is used to set up initial details. Height is also
746 automatically added when speedbar is created, though you can override
749 @cindex @code{speedbar-frame-plist}, XEmacs
750 In XEmacs, change the plist @code{speedbar-frame-plist}. This is the
751 XEmacs way of doing the same thing.
753 @node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing
754 @comment node-name, next, previous, up
755 @section Tag Hierarchy Methods
756 @cindex tag hierarchy
760 When listing tags within a file, it is possible to get an annoyingly
761 long list of entries. Imenu (which generates the tag list in Emacs)
762 will group some classes of items automatically. Even here, however,
763 some tag groups can be quite large.
765 @cindex @code{speedbar-tag-hierarchy-method}
766 To solve this problem, tags can be grouped into logical units through a
767 hierarchy processor. The specific variable to use is
768 @code{speedbar-tag-hierarchy-method}. There are several methods that
769 can be applied in any order. They are:
772 @cindex @code{speedbar-trim-words-tag-hierarchy}
773 @item speedbar-trim-words-tag-hierarchy
774 Find a common prefix for all elements of a group, and trim it off.
775 @cindex @code{speedbar-prefix-group-tag-hierarchy}
776 @item speedbar-prefix-group-tag-hierarchy
777 If a group is too large, place sets of tags into bins based on common
779 @cindex @code{speedbar-simple-group-tag-hierarchy}
780 @item speedbar-simple-group-tag-hierarchy
781 Take all items in the top level list not in a group, and stick them into
783 @cindex @code{speedbar-sort-tag-hierarchy}
784 @item speedbar-sort-tag-hierarchy
785 Sort all items, leaving groups on top.
788 You can also add your own functions to reorganize tags as you see fit.
790 Some other control variables are:
793 @cindex @code{speedbar-tag-group-name-minimum-length}
794 @item speedbar-tag-group-name-minimum-length
797 The minimum length of a prefix group name before expanding. Thus, if
798 the @code{speedbar-tag-hierarchy-method} includes
799 @code{speedbar-prefix-group-tag-hierarchy} and one such group's common
800 characters is less than this number of characters, then the group name
801 will be changed to the form of:
813 This way we won't get silly looking listings.
815 @cindex @code{speedbar-tag-split-minimum-length}
816 @item speedbar-tag-split-minimum-length
819 Minimum length before we stop trying to create sub-lists in tags.
820 This is used by all tag-hierarchy methods that break large lists into
823 @cindex @code{speedbar-tag-regroup-maximum-length}
824 @item speedbar-tag-regroup-maximum-length
827 Maximum length of submenus that are regrouped.
828 If the regrouping option is used, then if two or more short subgroups
829 are next to each other, then they are combined until this number of
833 @node Version Control, Hooks, Tag Hierarchy Methods, Customizing
834 @comment node-name, next, previous, up
835 @section Version Control
836 @cindex version control
837 @cindex vc extensions
839 When using the file mode in speedbar, information regarding a version
840 control system adds small details to the display. If a file is in a
841 version control system, and is ``checked out'' or ``locked'' locally, an
842 asterisk @samp{*} appears at the end of the file name. In addition,
843 the directory name for Version Control systems are left out of the
846 @cindex @code{speedbar-directory-unshown-regexp}
847 You can easily add new version control systems into speedbar's detection
848 scheme. To make a directory ``disappear'' from the list, use the variable
849 @code{speedbar-directory-unshown-regexp}.
851 @cindex @code{speedbar-vc-directory-enable-hook}
852 Next, you need to write entries for two hooks. The first is
853 @code{speedbar-vc-directory-enable-hook} which will enable a VC check in the
854 current directory for the group of files being checked. Your hook
855 function should take one parameter (the directory to check) and return
856 @code{t} if your VC method is in control here.
858 @cindex @code{speedbar-vc-in-control-hook}
859 The second function is @code{speedbar-vc-in-control-hook}. This hook
860 takes two parameters, the @var{path} of the file to check, and the
861 @var{file} name. Return @code{t} if you want to have the asterisk
862 placed near this file.
864 @cindex @code{speedbar-vc-indicator}
865 Lastly, you can change the VC indicator using the variable
866 @code{speedbar-vc-indicator}, and specify a single character string.
868 @node Hooks, , Version Control, Customizing
869 @comment node-name, next, previous, up
873 There are several hooks in speedbar allowing custom behaviors to be
874 added. Available hooks are:
877 @cindex @code{speedbar-visiting-file-hook}
878 @item speedbar-visiting-file-hook
879 Hooks run when speedbar visits a file in the selected frame.
880 @cindex @code{speedbar-visiting-tag-hook}
881 @item speedbar-visiting-tag-hook
882 Hooks run when speedbar visits a tag in the selected frame.
883 @cindex @code{speedbar-load-hook}
884 @item speedbar-load-hook
885 Hooks run when speedbar is loaded.
886 @cindex @code{speedbar-reconfigure-keymaps-hook}
887 @item speedbar-reconfigure-keymaps-hook
888 Hooks run when the keymaps are regenerated. Keymaps are reconfigured
889 whenever modes change. This will let you add custom key bindings.
890 @cindex @code{speedbar-before-popup-hook}
891 @item speedbar-before-popup-hook
892 Hooks called before popping up the speedbar frame.
893 New frames are often popped up when ``power clicking'' on an item to view
895 @cindex @code{speedbar-before-delete-hook}
896 @item speedbar-before-delete-hook
897 Hooks called before deleting or hiding the speedbar frame.
898 @cindex @code{speedbar-mode-hook}
899 @item speedbar-mode-hook
900 Hooks called after creating a speedbar buffer.
901 @cindex @code{speedbar-timer-hook}
902 @item speedbar-timer-hook
903 Hooks called after running the speedbar timer function.
904 @cindex @code{speedbar-scanner-reset-hook}
905 @item speedbar-scanner-reset-hook
906 Hook called whenever generic scanners are reset.
907 Set this to implement your own scanning or rescan safe functions with
911 @node Extending, Index, Customizing, Top
912 @comment node-name, next, previous, up
916 Speedbar can run different types of Major display modes such as Files
917 (@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage
918 different minor display modes for use with buffers handling specialized
921 These major and minor display modes are handled through an extension
922 system which permits specialized keymaps and menu extensions, in
923 addition to a unique rendering function. You can also specify a wide
924 range of tagging functions. The default uses @code{imenu}, but new
925 tagging methods can be easily added. In this chapter, you will
926 learn how to write your own major or minor display modes, and how to
927 create specialized tagging functions.
930 * Minor Display Modes:: How to create a minor display mode.
931 * Major Display Modes:: How to create a major display mode.
932 * Tagging Extensions:: How to create your own tagging methods.
933 * Creating a display:: How to insert buttons and hierarchies.
936 @node Minor Display Modes, Major Display Modes, Extending, Extending
937 @section Minor Display Modes
938 @cindex create minor display mode
940 A @dfn{minor display mode} is a mode useful when using a specific type of
941 buffer. This mode might not be useful for any other kind of data or
942 mode, or may just be more useful that a files or buffers based mode when
943 working with a specialized mode.
945 Examples that already exist for speedbar include RMAIL, Info, and gdb.
946 These modes display information specific to the major mode shown in the
949 To enable a minor display mode in your favorite Major mode, follow these
950 steps. The string @samp{@var{name}} is the name of the major mode being
951 augmented with speedbar.
955 Create the keymap variable @code{@var{name}-speedbar-key-map}.
958 Create a function, named whatever you like, which assigns values into your
959 keymap. Use this command to create the keymap before assigning
963 (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap))
966 This function creates a special keymap for use in speedbar.
969 Call your install function, or assign it to a hook like this:
972 (if (featurep 'speedbar)
973 (@var{name}-install-speedbar-variables)
974 (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))
978 Create an easymenu compatible vector named
979 @code{@var{name}-speedbar-menu-items}. This will be spliced into
980 speedbar's control menu.
983 Create a function called @code{@var{name}-speedbar-buttons}. This function
984 should take one variable, which is the buffer for which it will create
985 buttons. At this time @code{(current-buffer)} will point to the
986 uncleared speedbar buffer.
989 When writing @code{@var{name}-speedbar-buttons}, the first thing you will
990 want to do is execute a check to see if you need to re-create your
991 display. If it needs to be cleared, you need to erase the speedbar
992 buffer yourself, and start drawing buttons. @xref{Creating a display}.
994 @node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending
995 @section Major Display Modes
996 @cindex create major display mode
998 Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap,
999 an easy-menu segment, and writing several functions. These items can be
1000 given any name, and are made the same way as in a minor display mode
1001 (@pxref{Minor Display Modes}). Once this is done, these items need to be
1004 Because this setup activity may or may not have speedbar available when
1005 it is being loaded, it is necessary to create an install function. This
1006 function should create and initialize the keymap, and add your
1007 expansions into the customization tables.
1009 @cindex @code{speedbar-make-specialized-keymap}
1010 When creating the keymap, use the function
1011 @code{speedbar-make-specialized-keymap} instead of other keymap making
1012 functions. This will provide you with the initial bindings needed.
1013 Some common speedbar functions you might want to bind are:
1016 @cindex @code{speedbar-edit-line}
1017 @item speedbar-edit-line
1018 Edit the item on the current line.
1019 @cindex @code{speedbar-expand-line}
1020 @item speedbar-expand-line
1021 Expand the item under the cursor.
1022 With a numeric argument (@kbd{C-u}), flush cached data before expanding.
1023 @cindex @code{speedbar-contract-line}
1024 @item speedbar-contract-line
1025 Contract the item under the cursor.
1028 @cindex @code{speedbar-line-directory}
1029 These function require that function @code{speedbar-line-directory} be
1030 correctly overloaded to work.
1032 Next, register your extension like this;
1035 (speedbar-add-expansion-list '("MyExtension"
1036 MyExtension-speedbar-menu-items
1037 MyExtension-speedbar-key-map
1038 MyExtension-speedbar-buttons))
1041 There are no limitations to the names you use.
1043 The first parameter is the string representing your display mode.
1044 The second parameter is a variable name containing an easymenu compatible
1045 menu definition. This will be stuck in the middle of speedbar's menu.
1046 The third parameter is the variable name containing the keymap we
1048 The last parameter is a function which draws buttons for your mode.
1049 This function must take two parameters. The directory currently being
1050 displayed, and the depth at which you should start rendering buttons.
1051 The function will then draw (starting at the current cursor position)
1052 any buttons deemed necessary based on the input parameters.
1053 @xref{Creating a display}.
1055 Next, you need to register function overrides. This may look something
1059 (speedbar-add-mode-functions-list
1061 (speedbar-item-info . MyExtension-speedbar-item-info)
1062 (speedbar-line-directory . MyExtension-speedbar-line-directory)))
1065 The first element in the list is the name of you extension. The second
1066 is an alist of functions to overload. The function to overload is
1067 first, followed by what you want called instead.
1069 For @code{speedbar-line-directory} your function should take an optional DEPTH
1070 parameter. This is the starting depth for heavily indented lines. If
1071 it is not provided, you can derive it like this:
1078 (looking-at "^\\([0-9]+\\):")
1079 (setq depth (string-to-int (match-string 1)))))
1083 where the depth is stored as invisible text at the beginning of each
1086 The path returned should be the full path name of the file associated
1087 with that line. If the cursor is on a tag, then the file containing
1088 that tag should be returned. This is critical for built in file based
1089 functions to work (meaning less code for you to write). If your display
1090 does not deal in files, you do not need to overload this function.
1092 @cindex @code{speedbar-item-info}
1093 The function @code{speedbar-item-info}, however, is very likely to need
1094 overloading. This function takes no parameters and must derive a text
1095 summary to display in the minibuffer.
1097 There are several helper functions you can use if you are going to use
1098 built in tagging. These functions can be @code{or}ed since each one
1099 returns non-@code{nil} if it displays a message. They are:
1102 @cindex @code{speedbar-item-info-file-helper}
1103 @item speedbar-item-info-file-helper
1104 This takes an optional @var{filename} parameter. You can derive your own
1105 filename, or it will derive it using a (possibly overloaded) function
1106 @code{speedbar-line-file}. It shows details about a file.
1107 @cindex @code{speedbar-item-info-tag-helper}
1108 @item speedbar-item-info-tag-helper
1109 If the current line is a tag, then display information about that tag,
1110 such as its parent file, and location.
1113 Your custom function might look like this:
1116 (defun MyExtension-item-info ()
1117 "Display information about the current line."
1118 (or (speedbar-item-info-tag-helper)
1119 (message "Interesting detail.")))
1122 Once you have done all this, speedbar will show an entry in the
1123 @samp{Displays} menu declaring that your extension is available.
1125 If your major mode is running slowly, you may need to add a set of
1126 stealthy update functions.
1128 @defvar speedbar-stealthy-function-list
1129 @anchor{speedbar-stealthy-function-list}
1130 List of functions to periodically call stealthily.
1131 Each function must return @code{nil} if interrupted, or @code{t} if completed.
1132 Stealthy functions which have a single operation should always return
1133 @code{t}. Functions which take a long time should maintain a state (where
1134 they are in their speedbar related calculations) and permit
1135 interruption. See @dfn{speedbar-check-vc} as a good example.
1138 Stealthy functions are currently used in files mode. The first
1139 activity is to display the main list with minimal decorations though
1140 the buttons function. Once that is done, additional work can be done
1141 decorating different lines after the fact.
1143 For files mode, VC status and read-only markers can calculated after
1144 the first display is up. Because the process of calculating that
1145 information can be slow, these functions are interruptable, and will
1146 continue processing at a later time out.
1148 @node Tagging Extensions, Creating a display, Major Display Modes, Extending
1149 @section Tagging Extensions
1151 It is possible to create new methods for tagging files in speedbar.
1152 To do this, you need two basic functions, one function to fetch the
1153 tags from a buffer, the other to insert them below the filename.
1155 @defun my-fetch-dynamic-tags file
1156 Parse @var{file} for a list of tags. Return the list, or @code{t} if
1157 there was an error. @var{file} is not necessarily available as an
1158 buffer when your function is called. Be sure to load it if it is needed
1159 with code like this:
1163 (set-buffer (find-file-noselect file))
1169 The non-error return value can be anything, as long as it can be
1170 inserted by its paired function:
1172 @defun my-insert-tag-list level lst
1173 Insert a list of tags @var{lst} started at indentation level
1174 @var{level}. Creates buttons for each tag, and provides any other
1175 display information required.
1178 @cindex @code{speedbar-create-tag-hierarchy}
1179 It is often useful to use @code{speedbar-create-tag-hierarchy} on your
1180 tag list @ref{Creating a display}.
1182 @cindex @code{speedbar-dynamic-tags-function-list}
1183 Once these two functions are written, modify the variable
1184 @code{speedbar-dynamic-tags-function-list} to include your parser at the
1185 beginning, like this:
1188 (add-to-list 'speedbar-dynamic-tags-function-list
1189 '(my-fetch-dynamic-tags . my-insert-tag-list))
1192 @defvar speedbar-dynamic-tags-function-list
1193 @anchor{speedbar-dynamic-tags-function-list}
1194 A list of functions which will return and insert a list of tags.
1195 Each element is of the form ( @var{fetch} . @var{insert} ) where @var{fetch}
1196 is a function which takes one parameter (the file to tag) and returns a
1197 list of tags. The tag list can be of any form as long as the
1198 corresponding insert method can handle it. If it returns @code{t}, then an
1199 error occurred, and the next fetch routine is tried.
1200 @var{insert} is a function which takes an INDENTation level, and a @var{list} of
1201 tags to insert. It will then create the speedbar buttons.
1204 If your parser is only good for a few types of files (ie, just texinfo
1205 files), make sure that it is either a buffer local modification (set
1206 only in texi files), or that the tag generator returns @code{t} for
1207 unsupported buffers.
1209 @node Creating a display, , Tagging Extensions, Extending
1210 @section Creating a display
1211 @cindex creating a display
1213 Rendering a display in speedbar is completely flexible. When your
1214 button function is called, see @ref{Minor Display Modes}, and @ref{Major
1215 Display Modes}, you have control to @code{insert} anything you want.
1217 The conventions allow almost anything to be inserted, but several helper
1218 functions are provided to make it easy to create the standardized
1221 To understand the built in functions, each `button' in speedbar consists
1222 of four important pieces of data. The text to be displayed, token
1223 data to be associated with the text, a function to call, and some face to
1226 When a function is provided, then that text becomes mouse activated,
1227 meaning the mouse will highlight the text.
1229 Additionally, for data which can form deep trees, each line is given a
1230 depth which indicates how far down the tree it is. This information is
1231 stored in invisible text at the beginning of each line, and is used by
1232 the navigation commands.
1235 * Creating Buttons::
1236 * Generic Tag Lists::
1240 @node Creating Buttons, Generic Tag Lists, , Creating a display
1241 @subsection Creating Speedbar Buttons
1243 While it is certainly possible to insert your own text and add
1244 decorations to it, it is preferable to use the speedbar button
1245 creation API instead.
1247 @defun speedbar-insert-button text face mouse function &optional token prevline
1248 This function inserts one button into the current location.
1249 @var{text} is the text to insert. @var{face} is the face in which it
1250 will be displayed. @var{mouse} is the face to display over the text
1251 when the mouse passes over it. @var{function} is called whenever the
1252 user clicks on the text.
1254 The optional argument @var{token} is extra data to associated with the
1255 text. Lastly @var{prevline} should be non-@code{nil} if you want this line to
1256 appear directly after the last button which was created instead of on
1260 This routine creates a single button in the display, such as a [+]
1261 button, or the text that goes after it. It is designed to be called
1262 iteratively with indicators on when to add carriage returns between
1265 To insert a more traditional speedbar line that includes an expansion
1266 button followed by clickable text, it is preferable to create a
1267 tag-line. Tag lines should be used to represent typical data a user
1270 @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
1272 Create a tag line with @var{exp-button-type} for the small expansion
1273 button. This is the button that expands or contracts a node (if
1274 applicable), and @var{exp-button-char} the character in it (@samp{+},
1276 etc). @var{exp-button-function} is the function to call if it's clicked
1277 on. Button types are @code{'bracket}, @code{'angle}, @code{'curly},
1278 @code{'expandtag}, @code{'statictag}, or nil. @var{exp-button-data} is
1279 extra data attached to the text forming the expansion button.
1281 Next, @var{tag-button} is the text of the tag.
1282 @var{tag-button-function} is the function to call if clicked on, and
1283 @var{tag-button-data} is the data to attach to the text field (such a
1284 tag positioning, etc). @var{tag-button-face} is a face used for this
1287 Lastly, @var{depth} shows the depth of expansion.
1289 This function assumes that the cursor is in the speedbar window at the
1290 position to insert a new item, and that the new item will end with a CR.
1293 Major display modes that use this function will have a consistant look
1294 and feel and reliable image use.
1296 @node Generic Tag Lists, Expand Buttons, Creating Buttons, Creating a display
1297 @subsection Generic Tag Lists
1299 For data stored in a hierarchical list, it is likely possible to
1300 have the entire data structure inserted with the speedbar generic list
1303 These insertion functions assume that the data represents 'tags', or
1304 data extracted from inside a file, and they are marked with tag
1307 Tags stored in this format can then be manipulated by the tag
1308 hierarchy methods described earlier in this manual.
1310 @defun speedbar-insert-generic-list level list expand-fun find-fun
1312 At @var{level}, (the current indentation level desired) insert a generic
1313 multi-level alist @var{list}. Associations with lists get @samp{@{+@}}
1314 tags (to expand into more nodes) and those with positions or other data
1315 just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the
1316 function @var{expand-fun} and the token is the @code{cdr} list. The
1317 token name will have the function @var{find-fun} and not token.
1319 Each element of the list can have one of these forms:
1322 @item (@var{name} . marker-or-number)
1323 One tag at this level.
1324 @item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... )
1326 @item (@var{name} marker-or-number (@var{name} . marker-or-number) ... )
1327 One Group of tags where the group has a starting position.
1330 When you use @code{speedbar-insert-generic-list}, there are some
1331 variables you can set buffer-locally to change the behavior. The most
1332 obvious is @code{speedbar-tag-hierarchy-method}.
1333 @xref{Tag Hierarchy Methods}.
1335 @defvar speedbar-generic-list-group-expand-button-type
1336 This is the button type used for groups of tags, whether expanded
1337 or added in via a hierarchy method. Two good values are
1338 @code{'curly} and @code{'expandtag}. Curly is the default button, and
1339 @code{'expandtag} is useful if the groups also has a position.
1342 @defvar speedbar-generic-list-tag-button-type
1343 This is the button type used for a single tag.
1344 Two good values are @code{nil} and @code{'statictag}.
1345 @code{nil} is the default, and @code{'statictag} has the same width as
1351 @node Expand Buttons, , Generic Tag Lists, Creating a display
1352 @subsection Expand Buttons
1354 Once you have made some buttons, you need to hitch them up to
1355 do something once clicked on. This is set up with
1356 @code{speedbar-make-tag-line} which takes two functions. One is for
1357 the expand button, and the other for the tag.
1359 The function for the tag can be anything, but the expand button has
1360 certain expectations. When that button is has a @code{+} in it, that
1361 indicates that there is ``more'' inside. A @code{-} indicates that a
1362 section can be closed.
1364 The expand function takes the same signature as all speedbar button
1368 (defun MY-expand-function (text token indent)
1369 "Display more information about MY thing.
1373 This function should then use the @var{text} parameter to determine
1374 what to do. For example:
1377 (cond ((string-match "+" text) ;we have to expand this file
1378 ;; Expand stuff here
1380 ((string-match "-" text) ;we have to contract this node
1381 ;; Contract stuff here
1385 When expanding or contracting, you will need to change the
1386 @code{+} or @code{-} into the opposite symbol. You can do that with
1388 @defun speedbar-change-expand-button-char char
1389 @anchor{speedbar-change-expand-button-char}
1390 Change the expansion button character to @var{char} for the current line.
1393 Our sample would then look like this:
1396 (cond ((string-match "+" text) ;we have to expand this file
1397 ;; Expand stuff here
1398 (speedbar-change-expand-button-char ?-)
1400 ((string-match "-" text) ;we have to contract this node
1401 ;; Contract stuff here
1402 (speedbar-change-expand-button-char ?+)
1406 To expand text, the speedbar buffer needs to be writable. The initial
1407 button insertion function runs while the buffer is writable, but an
1408 expand function will need to change that. The best way is to use
1409 @code{speedbar-with-writable}.
1411 @defun speedbar-with-writable &rest forms
1412 @anchor{speedbar-with-writable}
1413 Allow the speedbar buffer to be writable and evaluate @var{forms}.
1416 Once the buffer is writable, then you can insert more information
1417 using any mechanism you like. Remember that the cursor will be on the
1418 expand button just clicked though. As such, the code might look like
1422 (cond ((string-match "+" text) ;we have to expand this file
1423 ;; Expand stuff here
1424 (speedbar-change-expand-button-char ?-)
1425 (speedbar-with-writable
1427 (end-of-line) (forward-char 1)
1428 ;; Insert goodies here.
1433 Contracting a node is a bit easier. You can just use this built in
1434 function to do the work:
1436 @defun speedbar-delete-subblock indent
1437 @anchor{speedbar-delete-subblock}
1438 Delete text from point to indentation level @var{indent} or greater.
1439 Handles end-of-sublist smartly.
1441 Remember that @var{indent} is also available as passed into
1442 @code{MY-expand-function}.
1445 The end result would then look like this:
1448 (cond ((string-match "+" text) ;we have to expand this file
1449 ;; Expand stuff here
1450 (speedbar-change-expand-button-char ?-)
1451 (speedbar-with-writable
1453 (end-of-line) (forward-char 1)
1454 ;; Insert goodies here.
1457 ((string-match "-" text) ;we have to contract this node
1458 ;; Contract stuff here
1459 (speedbar-change-expand-button-char ?+)
1460 (speedbar-delete-subblock indent))
1464 Expand buttons, unlike other speedbar operations can cause new data to
1465 appear in speedbar which would be useful to force onto the screen.
1466 You can then recenter using this function:
1468 @defun speedbar-center-buffer-smartly
1469 @anchor{speedbar-center-buffer-smartly}
1470 Recenter a speedbar buffer so the current indentation level is all visible.
1471 This assumes that the cursor is on a file, or tag of a file which the user is
1475 @node Index, , Extending, Top
1476 @comment node-name, next, previous, up
1477 @unnumbered Concept Index
1481 @c LocalWords: speedbar's xref slowbar kbd subsubsection
1482 @c LocalWords: keybindings
1485 arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02