Untabify doc/misc/*.texi.
[bpt/emacs.git] / doc / misc / speedbar.texi
CommitLineData
4009494e 1\input texinfo @c -*-texinfo-*-
db78a8cb 2@setfilename ../../info/speedbar
4009494e
GM
3@settitle Speedbar: File/Tag summarizing utility
4@syncodeindex fn cp
5
6@copying
7Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
114f9c96 82007, 2008, 2009, 2010 Free Software Foundation, Inc.
4009494e
GM
9
10@quotation
11Permission is granted to copy, distribute and/or modify this document
6a2c4aec 12under the terms of the GNU Free Documentation License, Version 1.3 or
f6310987
GM
13any later version published by the Free Software Foundation; with no
14Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
15and with the Back-Cover Texts as in (a) below. A copy of the license
16is included in the section entitled ``GNU Free Documentation License''.
17
18(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
19modify this GNU manual. Buying copies from the FSF supports it in
20developing GNU and promoting software freedom.''
4009494e
GM
21@end quotation
22@end copying
23
24@dircategory Emacs
25@direntry
26* Speedbar: (speedbar). File/Tag summarizing utility.
27@end direntry
28
29@titlepage
30@sp 10
31@center @titlefont{Speedbar}
32@sp 2
33@center Eric Ludlam
34@vskip 0pt plus 1 fill
35@page
36@vskip 0pt plus 1filll
37@insertcopying
38@end titlepage
39
5dc584b5
KB
40@contents
41
4009494e
GM
42@node Top, , , (dir)Top
43@comment node-name, next, previous, up
44
45Speedbar is a program for Emacs which can be used to summarize
46information related to the current buffer. Its original inspiration
47is the `explorer' often used in modern development environments, office
48packages, and web browsers.
49
50Speedbar displays a narrow frame in which a tree view is shown. This
51tree view defaults to containing a list of files and directories. Files
52can be `expanded' to list tags inside. Directories can be expanded to
53list the files within itself. Each file or tag can be jumped to
54immediately.
55
56Speedbar expands upon `explorer' windows by maintaining context with the
57user. For example, when using the file view, the current buffer's file
58is highlighted. Speedbar also mimics the explorer windows by providing
59multiple display modes. These modes come in two flavors. Major display
60modes remain consistent across buffers, and minor display modes appear
61only when a buffer of the applicable type is shown. This allows
62authors of other packages to provide speedbar summaries customized to
63the needs of that mode.
64
65Throughout this manual, activities are defined as `clicking on', or
66`expanding' items. Clicking means using @kbd{Mouse-2} on a
67button. Expanding refers to clicking on an expansion button to display
68an expanded summary of the entry the expansion button is
69on. @xref{Basic Navigation}.
70
5dc584b5
KB
71@ifnottex
72@insertcopying
73@end ifnottex
74
4009494e
GM
75@menu
76* Introduction:: Basics of speedbar.
77* Basic Navigation:: Basics of speedbar common between all modes.
78* File Mode:: Summarizing files.
79* Buffer Mode:: Summarizing buffers.
80* Minor Modes:: Additional minor modes such as Info and RMAIL.
81* Customizing:: Changing speedbar behavior.
82* Extending:: Extend speedbar for your own project.
83* GNU Free Documentation License:: The license for this documentation.
84* Index::
85@end menu
86
87@node Introduction, Basic Navigation, , Top
88@comment node-name, next, previous, up
89@chapter Introduction
90@cindex introduction
91
92To start using speedbar use the command @kbd{M-x speedbar RET} or
93select it from the @samp{Options->Show/Hide} sub-menu. This command
94will open a new frame to summarize the local files. On X Window
95systems or on MS-Windows, speedbar's frame is twenty characters wide,
96and will mimic the height of the frame from which it was started. It
97positions itself to the left or right of the frame you started it
98from.
99
100To use speedbar effectively, it is important to understand its
101relationship with the frame you started it from. This frame is the
102@dfn{attached frame} which speedbar will use as a reference point. Once
103started, speedbar watches the contents of this frame, and attempts to
104make its contents relevant to the buffer loaded into the attached
105frame. In addition, all requests made in speedbar that require the
106display of another buffer will display in the attached frame.
107
108When used in terminal mode, the new frame appears the same size as the
109terminal. Since it is not visible while working in the attached frame,
110speedbar will save time by using the @dfn{slowbar mode}, where no tracking is
111done until speedbar is requested to show itself (i.e., the speedbar's
112frame becomes the selected frame).
113
114@cindex @code{speedbar-get-focus}
115The function to use when switching between frames using the keyboard is
116@code{speedbar-get-focus}. This function will toggle between frames, and
117it's useful to bind it to a key in terminal mode. @xref{Customizing}.
118
119@node Basic Navigation, File Mode, Introduction, Top
120@comment node-name, next, previous, up
121@chapter Basic Navigation
122
123Speedbar can display different types of data, and has several display
124and behavior modes. These modes all have a common behavior, menu
125system, and look. If one mode is learned, then the other modes are easy
126to use.
127
128@menu
129* Basic Key Bindings::
130* Basic Visuals::
131* Mouse Bindings::
132* Displays Submenu::
133@end menu
134
135@node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation
136@comment node-name, next, previous, up
137@section Basic Key Bindings
138@cindex key bindings
139
140These key bindings are common across all modes:
141
142@table @kbd
143@item Q
144@cindex quitting speedbar
145Quit speedbar, and kill the frame.
146@item q
147Quit speedbar, and hide the frame. This makes it faster to restore the
148speedbar frame, than if you press @kbd{Q}.
149@item g
150@cindex refresh speedbar display
151Refresh whatever contents are in speedbar.
152@item t
153@cindex slowbar mode
154Toggle speedbar to and from slowbar mode. In slowbar mode, frame
155tracking is not done.
156@item n
157@itemx p
158@cindex navigation
159Move, respectively, to the next or previous item. A summary of that
160item will be displayed in the attached frame's minibuffer.
161@item M-n
162@itemx M-p
163Move to the next or previous item in a restricted fashion. If a list is
164open, the cursor will skip over it. If the cursor is in an open list,
165it will not leave it.
166@item C-M-n
40d2791f 167@itemx C-M-p
4009494e
GM
168Move forwards and backwards across extended groups. This lets you
169quickly skip over all files, directories, or other common sub-items at
170the same current depth.
171@item C-x b
172Switch buffers in the attached frame.
173@end table
174
175Speedbar can handle multiple modes. Two are provided by default.
176These modes are File mode, and Buffers mode. There are accelerators to
177switch into these different modes.
178
179@cindex mode switching hotkeys
180@table @kbd
181@item b
182Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the
183previous display mode is restored.
184@item f
185Switch into File mode.
186@item r
187Switch back to the previous mode.
188@end table
189
190Some modes provide groups, lists and tags. @xref{Basic Visuals}. When
191these are available, some additional common bindings are available.
192
193@cindex common keys
194@table @kbd
195@item RET
196@itemx e
197Edit/Open the current group or tag. This behavior is dependent on the
198mode. In general, files or buffers are opened in the attached frame,
199and directories or group nodes are expanded locally.
200@item +
201@itemx =
202Expand the current group, displaying sub items.
203When used with a prefix argument, any data that may have been cached is
204flushed. This is similar to a power click. @xref{Mouse Bindings}.
205@item -
206Contract the current group, hiding sub items.
207@end table
208
209@node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation
210@comment node-name, next, previous, up
211@section Basic Visuals
212@cindex visuals
213
214Speedbar has visual cues for indicating different types of data. These
215cues are used consistently across the different speedbar modes to make
216them easier to interpret.
217
218At a high level, in File mode, there are directory buttons, sub
219directory buttons, file buttons, tag buttons, and expansion buttons.
220This makes it easy to use the mouse to navigate a directory tree, and
221quickly view files, or a summary of those files.
222
223The most basic visual effect used to distinguish between these button
224types is color and mouse highlighting. Anything the mouse highlights
225can be clicked on and is called a button (@pxref{Mouse Bindings}).
226Anything not highlighted by the mouse will not be clickable.
227
228Text in speedbar consists of four different types of data. Knowing how
229to read these textual elements will make it easier to navigate by
230identifying the types of data available.
231
232@subsubsection Groups
233@cindex groups
234
235Groups summarize information in a single line, and provide a high level
236view of more complex systems, like a directory tree, or manual chapters.
237
238Groups appear at different indentation levels, and are prefixed with a
239@samp{+} in some sort of `box'. The group name will summarize the
240information within it, and the expansion box will display that
241information inline. In File mode, directories and files are `groups'
242where the @samp{+} is surrounded by brackets like this:
243
244@example
245<+> include
246<-> src
247 [+] foo.c
248@end example
249
250In this example, we see both open and closed directories, in addition to
251a file. The directories have a box consisting of angle brackets, and a
252file uses square brackets.
253
254In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a
255file will be opened, or a directory explicitly opened in speedbar. A
256group can be expanded or contracted using @kbd{+} or
257@kbd{-}. @xref{Basic Key Bindings}.
258
259Sometimes groups may have a @samp{?} in its indicator box. This means
260that it is a group type, but there are no contents, or no known way of
261extracting contents of that group.
262
263When a group has been expanded, the indicator button changes from
264@samp{+} to @samp{-}. This indicates that the contents are being shown.
265Click the @samp{-} button to contract the group, or hide the contents
266currently displayed.
267
268@subsubsection Tags
269@cindex tags
270
271Tags are the leaf nodes of the tree system. Tags are generally prefixed
272with a simple character, such as @samp{>}. Tags can only be jumped to using
273@kbd{RET} or @kbd{e}.
274
275@subsubsection Boolean Flags
276
277Sometimes a group or tag is given a boolean flag. These flags appear as
278extra text characters at the end of the line. File mode uses boolean
279flags, such as a @samp{*} to indicate that a file has been checked out
280of a versioning system.
281
282For additional flags, see
283@c Note to self, update these to sub-nodes which are more relevant.
284@ref{File Mode}, and @ref{Version Control}.
285
286@subsubsection Unadorned Text
287
288Unadorned text generally starts in column 0, without any special symbols
289prefixing them. In Buffers mode different buffer groups are prefixed
290with a description of what the following buffers are (Files, scratch
291buffers, and invisible buffers.)
292
293Unadorned text will generally be colorless, and not clickable.
294
295@subsubsection Color Cues
296
297Each type of Group, item indicator, and label is given a different
298color. The colors chosen are dependent on whether the background color
299is light or dark.
300Of important note is that the `current item', which may be a buffer or
301file name, is highlighted red, and underlined.
302
303Colors can be customized from the group @code{speedbar-faces}. Some
304modes, such as for Info, will use the Info colors instead of default
305speedbar colors as an indication of what is currently being displayed.
306
307The face naming convention mirrors the File display mode. Modes which
308do not use files will attempt to use the same colors on analogous
309entries.
310
311@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation
312@comment node-name, next, previous, up
313@section Mouse Bindings
314@cindex mouse bindings
315
316The mouse has become a common information navigation tool. Speedbar
317will use the mouse to navigate file systems, buffer lists, and other
318data. The different textual cues provide buttons which can be clicked
319on (@pxref{Basic Visuals}). Anything that highlights can be clicked on
320with the mouse, or affected by the menu.
321
322The mouse bindings are:
323
324@table @kbd
325@item Mouse-1
326Move cursor to that location.
327@item Mouse-2
328@itemx Double-Mouse-1
329Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double
330click} on other platforms, and is useful for windows users with two
331button mice.
332@c Isn't it true that with two-button mice, the right button is Mouse-2?
333@c On GNU/Linux, the right button is Mouse-3.
334@item S-Mouse-2
335@itemx S-Double-Mouse-1
336@cindex power click
337This has the same effect as @kbd{Mouse-2}, except it is called a power
338click. This means that if a group with an expansion button @samp{+} is
339clicked, any caches are flushed, and subitems re-read. If it is a name,
340it will be opened in a new frame.
341@item Mouse-3
342Activate the speedbar menu. The item selected affects the line clicked,
343not the line where the cursor was.
344@item Mouse-1 @r{(mode line)}
345Activate the menu. This affects the item the cursor is on before the
346click, since the mouse was not clicked on anything.
347@item C-Mouse-1
348Buffers sub-menu. The buffer in the attached frame is switched.
349@end table
350
351When the mouse moves over buttons in speedbar, details of that item
352should be displayed in the minibuffer of the attached frame. Sometimes
353this can contain extra information such as file permissions, or tag
354location.
355
356@node Displays Submenu, , Mouse Bindings, Basic Navigation
357@comment node-name, next, previous, up
358@section Displays Submenu
359@cindex displays submenu
360
361You can display different data by using different display modes. These
362specialized modes make it easier to navigate the relevant pieces of
363information, such as files and directories, or buffers.
364
365In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu
366labeled @samp{Displays}. This submenu lets you easily choose between
367different display modes.
368
369The contents are modes currently loaded into emacs. By default, this
370would include Files, Quick Buffers, and Buffers. Other major display
371modes such as Info are loaded separately.
372
373@node File Mode, Buffer Mode, Basic Navigation, Top
374@comment node-name, next, previous, up
375@chapter File Mode
376@cindex file mode
377
378File mode displays a summary of your current directory. You can display
379files in the attached frame, or summarize the tags found in files. You
380can even see if a file is checked out of a version control system, or
381has some associated object file.
382
383Advanced behavior, like copying and renaming files, is also provided.
384
385@menu
386* Directory Display:: What the display means.
387* Hidden Files:: How to display hidden files.
388* File Key Bindings:: Performing file operations.
389@end menu
390
391@node Directory Display, Hidden Files, File Mode, File Mode
392@comment node-name, next, previous, up
393@section Directory Display
394@cindex directory display
395
396There are three major sections in the display. The first line or two is
397the root directory speedbar is currently viewing. You can jump to one
398of the parent directories by clicking on the name of the directory you
399wish to jump to.
400
401Next, directories are listed. A directory starts with the group
402indicator button @samp{<+>}. Clicking the directory name makes speedbar
403load that directory as the root directory for its display. Clicking the
404@samp{<+>} button will list all directories and files beneath.
405
406Next, files are listed. Files start with the group indicator @samp{[+]}
407or @samp{[?]}. You can jump to a file in the attached frame by clicking
408on the file name. You can expand a file and look at its tags by
409clicking on the @samp{[+]} symbol near the file name.
410
411A typical session might look like this:
412
413@example
414~/lisp/
415<+> checkdoc
416<+> eieio
417<-> speedbar
418 [+] Makefile
419 [+] rpm.el #
420 [+] sb-gud.el #
421 [+] sb-info.el #
422 [+] sb-rmail.el #
423 [+] sb-w3.el
424 [-] speedbar.el *!
425 @{+@} Types
426 @{+@} Variables
427 @{+@} def (group)
428 @{+@} speedbar-
429 [+] speedbar.texi *
430<+> testme
431[+] align.el
432[+] autoconf.el
433@end example
434
435In this example, you can see several directories. The directory
436@file{speedbar} has been opened inline. Inside the directory
437@file{speedbar}, the file @file{speedbar.el} has its tags exposed.
438These tags are extensive, and they are summarized into tag groups.
439
440Files get additional boolean flags associated with them. Valid flags are:
441
442@cindex file flags
443@table @code
444@item *
445This file has been checked out of a version control
446system. @xref{Version Control}.
447@cindex @code{speedbar-obj-alist}
448@item #
449This file has an up to date object file associated with it. The
450variable @code{speedbar-obj-alist} defines how speedbar determines this
451value.
452@item !
453This file has an out of date object file associated with it.
454@end table
455
456A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this
457symbol will show all symbols that have been organized into that group.
458Different types of files have unique tagging methods as defined by their
459major mode. Tags are generated with either the @code{imenu} package, or
460through the @code{etags} interface.
461
462Tag groups are defined in multiple ways which make it easier to find the
463tag you are looking for. Imenu keywords explicitly create groups, and
464speedbar will automatically create groups if tag lists are too long.
465
466In our example, Imenu created the groups @samp{Types} and
467@samp{Variables}. All remaining top-level symbols are then regrouped
468based on the variable @code{speedbar-tag-hierarchy-method}. The
469subgroups @samp{def} and @samp{speedbar-} are groupings where the first
470few characters of the given symbols are specified in the group name.
471Some group names may say something like @samp{speedbar-t to speedbar-v},
472indicating that all symbols which alphabetically fall between those
473categories are included in that sub-group. @xref{Tag Hierarchy Methods}.
474
475@node Hidden Files, File Key Bindings, Directory Display, File Mode
476@comment node-name, next, previous, up
477@section Hidden Files
478@cindex hidden files
479
480On GNU and Unix systems, a hidden file is a file whose name starts
481with a period. They are hidden from a regular directory listing
482because the user is not generally interested in them.
483
484In speedbar, a hidden file is a file which isn't very interesting and
485might prove distracting to the user. Any uninteresting files are
486removed from the File display. There are two levels of uninterest in
487speedbar. The first level of uninterest are files which have no
488expansion method, or way of extracting tags. The second level is any
489file that matches the same pattern used for completion in
490@code{find-file}. This is derived from the variable
491@code{completion-ignored-extensions}.
492
493You can toggle the display of uninteresting files from the toggle menu
494item @samp{Show All Files}. This will display all level one hidden files.
495These files will be shown with a @samp{?} indicator. Level 2 hidden
496files will still not be shown.
497
498Object files fall into the category of level 2 hidden files. You can
499determine their presence by the @samp{#} and @samp{!} file indicators.
500@xref{Directory Display}.
501
502@node File Key Bindings, , Hidden Files, File Mode
503@comment node-name, next, previous, up
504@section File Key Bindings
505@cindex file key bindings
506
507File mode has key bindings permitting different file system operations
508such as copy or rename. These commands all operate on the @dfn{current
509file}. In this case, the current file is the file at point, or clicked
510on when pulling up the menu.
511
512@table @kbd
513@item U
514Move the entire speedbar display up one directory.
515@item I
516Display information in the minibuffer about this line. This is the same
517information shown when navigating with @kbd{n} and @kbd{p}, or moving
518the mouse over an item.
519@item B
520Byte compile the Emacs Lisp file on this line.
521@item L
522Load the Emacs Lisp file on this line. If a @file{.elc} file exists,
523optionally load that.
524@item C
525Copy the current file to some other location.
526@item R
527Rename the current file, possibly moving it to some other location.
528@item D
529Delete the current file.
530@item O
531Delete the current file's object file. Use the symbols @samp{#} and
532@samp{!} to determine if there is an object file available.
533@end table
534
535One menu item toggles the display of all available files. By default,
536only files which Emacs understands, and knows how to convert into a tag
537list, are shown. By showing all files, additional files such as text files are
538also displayed, but they are prefixed with the @samp{[?]} symbol. This
539means that it is a file, but Emacs doesn't know how to expand it.
540
541@node Buffer Mode, Minor Modes, File Mode, Top
542@comment node-name, next, previous, up
543@chapter Buffer Mode
544@cindex buffer mode
545
546Buffer mode is very similar to File mode, except that instead of
547tracking the current directory and all files available there, the
548current list of Emacs buffers is shown.
549
550These buffers can have their tags expanded in the same way as files,
551and uses the same unknown file indicator (@pxref{File Mode}).
552
553Buffer mode does not have file operation bindings, but the following
554buffer specific key bindings are available:
555
556@table @kbd
557@item k
558Kill this buffer. Do not touch its file.
559@item r
560Revert this buffer, reloading from disk.
561@end table
562
563In addition to Buffer mode, there is also Quick Buffer mode. In fact,
564Quick Buffers is bound to the @kbd{b} key. The only difference between
565Buffers and Quick Buffers is that after one operation is performed
566which affects the attached frame, the display is immediately reverted to
567the last displayed mode.
568
569Thus, if you are in File mode, and you need quick access to a buffer,
570press @kbd{b}, click on the buffer you want, and speedbar will revert
571back to File mode.
572
573@node Minor Modes, Customizing, Buffer Mode, Top
574@comment node-name, next, previous, up
575@chapter Minor Display Modes
576@cindex minor display modes
577
578For some buffers, a list of files and tags makes no sense. This could
579be because files are not currently in reference (such as web pages), or
580that the files you might be interested have special properties (such as
581email folders.)
582
583In these cases, a minor display mode is needed. A minor display mode
584will override any major display mode currently being displayed for the
585duration of the specialized buffer's use. Minor display modes
586will follow the general rules of their major counterparts in terms of
587key bindings and visuals, but will have specialized behaviors.
588
589@menu
590* RMAIL:: Managing folders.
591* Info:: Browsing topics.
592* GDB:: Watching expressions or managing the current
593 stack trace.
594@end menu
595
596@node RMAIL, Info, Minor Modes, Minor Modes
597@comment node-name, next, previous, up
598@section RMAIL
599@cindex RMAIL
600
601When using RMAIL, speedbar will display two sections. The first is a
602layer one reply button. Clicking here will initialize a reply buffer
603showing only this email address in the @samp{To:} field.
604
605The second section lists all RMAIL folders in the same directory as your
606main RMAIL folder. The general rule is that RMAIL folders always appear
607in all caps, or numbers. It is possible to save mail in folders with
608lower case letters, but there is no clean way of detecting such RMAIL folders
609without opening them all.
610
611Each folder can be visited by clicking the name. You can move mail from
612the current RMAIL folder into a different folder by clicking the
613@samp{<M>} button. The @samp{M} stands for Move.
614
615In this way you can manage your existing RMAIL folders fairly easily
616using the mouse.
617
618@node Info, GDB, RMAIL, Minor Modes
619@comment node-name, next, previous, up
620@section Info
621@cindex Info
622
623When browsing Info files, all local relevant information is displayed in
624the info buffer and a topical high-level view is provided in speedbar.
625All top-level info nodes are shown in the speedbar frame, and can be
626jumped to by clicking the name.
627
628You can open these nodes with the @samp{[+]} button to see what sub-topics
629are available. Since these sub-topics are not examined until you click
630the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on
631a @samp{[+]}, indicating that there are no sub-topics.
632
633@node GDB, , Info, Minor Modes
634@comment node-name, next, previous, up
635@section GDB
636@cindex gdb
637@cindex gud
638
639You can debug an application with GDB in Emacs using graphical mode or
640text command mode (@pxref{GDB Graphical Interface,,, emacs, The
641extensible self-documenting text editor}).
642
643If you are using graphical mode you can see how selected variables
644change each time your program stops (@pxref{Watch Expressions,,,
645emacs, The extensible self-documenting text editor}).
646
647If you are using text command mode, speedbar can show
648you the current stack when the current buffer is the @file{*gdb*}
649buffer. Usually, it will just report that there is no stack, but when
650the application is stopped, the current stack will be shown.
651
652You can click on any stack element and gdb will move to that stack
653level. You can then check variables local to that level at the GDB
654prompt.
655
656@node Customizing, Extending, Minor Modes, Top
657@comment node-name, next, previous, up
658@chapter Customizing
659@cindex customizing
660
661Speedbar is highly customizable, with a plethora of control elements.
662Since speedbar is so visual and reduces so much information, this is an
663important aspect of its behavior.
664
665In general, there are three custom groups you can use to quickly modify
666speedbar's behavior.
667
668@table @code
669@item speedbar
670Basic speedbar behaviors.
671@item speedbar-vc
672Customizations regarding version control handling.
673@item speedbar-faces
674Customize speedbar's many colors and fonts.
675@end table
676
677@menu
678* Frames and Faces:: Visible behaviors.
679* Tag Hierarchy Methods:: Customizing how tags are displayed.
680* Version Control:: Adding new VC detection modes.
681* Hooks:: The many hooks you can use.
682@end menu
683
684@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing
685@comment node-name, next, previous, up
686@section Frames and Faces
687@cindex faces
688@cindex frame parameters
689
690There are several faces speedbar generates to provide a consistent
691color scheme across display types. You can customize these faces using
692your favorite method. They are:
693
694@table @asis
695@cindex @code{speedbar-button-face}
696@item speedbar-button-face
697Face used on expand/contract buttons.
698@cindex @code{speedbar-file-face}
699@item speedbar-file-face
700Face used on Files. Should also be used on non-directory like nodes.
701@cindex @code{speedbar-directory-face}
702@item speedbar-directory-face
703Face used for directories, or nodes which consist of groups of other nodes.
704@cindex @code{speedbar-tag-face}
705@item speedbar-tag-face
706Face used for tags in a file, or for leaf items.
707@cindex @code{speedbar-selected-face}
708@item speedbar-selected-face
709Face used to highlight the selected item. This would be the current
710file being edited.
711@cindex @code{speedbar-highlight-face}
712@item speedbar-highlight-face
713Face used when the mouse passes over a button.
714@end table
715
716You can also customize speedbar's initial frame parameters. How this is
717accomplished is dependent on your platform being Emacs or XEmacs.
718
719@cindex @code{speedbar-frame-parameters}, Emacs
720In Emacs, change the alist @code{speedbar-frame-parameters}. This
721variable is used to set up initial details. Height is also
722automatically added when speedbar is created, though you can override
723it.
724
725@cindex @code{speedbar-frame-plist}, XEmacs
726In XEmacs, change the plist @code{speedbar-frame-plist}. This is the
727XEmacs way of doing the same thing.
728
729@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing
730@comment node-name, next, previous, up
731@section Tag Hierarchy Methods
732@cindex tag hierarchy
733@cindex tag groups
734@cindex tag sorting
735
736When listing tags within a file, it is possible to get an annoyingly
737long list of entries. Imenu (which generates the tag list in Emacs)
738will group some classes of items automatically. Even here, however,
739some tag groups can be quite large.
740
741@cindex @code{speedbar-tag-hierarchy-method}
742To solve this problem, tags can be grouped into logical units through a
743hierarchy processor. The specific variable to use is
744@code{speedbar-tag-hierarchy-method}. There are several methods that
745can be applied in any order. They are:
746
747@table @code
748@cindex @code{speedbar-trim-words-tag-hierarchy}
749@item speedbar-trim-words-tag-hierarchy
750Find a common prefix for all elements of a group, and trim it off.
751@cindex @code{speedbar-prefix-group-tag-hierarchy}
752@item speedbar-prefix-group-tag-hierarchy
753If a group is too large, place sets of tags into bins based on common
754prefixes.
755@cindex @code{speedbar-simple-group-tag-hierarchy}
756@item speedbar-simple-group-tag-hierarchy
757Take all items in the top level list not in a group, and stick them into
758a @samp{Tags} group.
759@cindex @code{speedbar-sort-tag-hierarchy}
760@item speedbar-sort-tag-hierarchy
761Sort all items, leaving groups on top.
762@end table
763
764You can also add your own functions to reorganize tags as you see fit.
765
766Some other control variables are:
767
768@table @code
769@cindex @code{speedbar-tag-group-name-minimum-length}
770@item speedbar-tag-group-name-minimum-length
771Default value: 4.
772
773The minimum length of a prefix group name before expanding. Thus, if
774the @code{speedbar-tag-hierarchy-method} includes
775@code{speedbar-prefix-group-tag-hierarchy} and one such group's common
776characters is less than this number of characters, then the group name
777will be changed to the form of:
778
779@example
780worda to wordb
781@end example
782
783instead of just
784
785@example
786word
787@end example
788
789This way we won't get silly looking listings.
790
791@cindex @code{speedbar-tag-split-minimum-length}
792@item speedbar-tag-split-minimum-length
793Default value: 20.
794
795Minimum length before we stop trying to create sub-lists in tags.
796This is used by all tag-hierarchy methods that break large lists into
797sub-lists.
798
799@cindex @code{speedbar-tag-regroup-maximum-length}
800@item speedbar-tag-regroup-maximum-length
801Default value: 10.
802
803Maximum length of submenus that are regrouped.
804If the regrouping option is used, then if two or more short subgroups
805are next to each other, then they are combined until this number of
806items is reached.
807@end table
808
809@node Version Control, Hooks, Tag Hierarchy Methods, Customizing
810@comment node-name, next, previous, up
811@section Version Control
812@cindex version control
813@cindex vc extensions
814
815When using the file mode in speedbar, information regarding a version
816control system adds small details to the display. If a file is in a
817version control system, and is ``checked out'' or ``locked'' locally, an
818asterisk @samp{*} appears at the end of the file name. In addition,
819the directory name for Version Control systems are left out of the
820speedbar display.
821
822@cindex @code{speedbar-directory-unshown-regexp}
823You can easily add new version control systems into speedbar's detection
824scheme. To make a directory ``disappear'' from the list, use the variable
825@code{speedbar-directory-unshown-regexp}.
826
827@cindex @code{speedbar-vc-path-enable-hook}
828Next, you need to write entries for two hooks. The first is
829@code{speedbar-vc-path-enable-hook} which will enable a VC check in the
830current directory for the group of files being checked. Your hook
831function should take one parameter (the directory to check) and return
832@code{t} if your VC method is in control here.
833
834@cindex @code{speedbar-vc-in-control-hook}
835The second function is @code{speedbar-vc-in-control-hook}. This hook
836takes two parameters, the @var{path} of the file to check, and the
837@var{file} name. Return @code{t} if you want to have the asterisk
838placed near this file.
839
840@cindex @code{speedbar-vc-indicator}
841Lastly, you can change the VC indicator using the variable
842@code{speedbar-vc-indicator}, and specify a single character string.
843
844@node Hooks, , Version Control, Customizing
845@comment node-name, next, previous, up
846@section Hooks
847@cindex hooks
848
849There are several hooks in speedbar allowing custom behaviors to be
850added. Available hooks are:
851
852@table @code
853@cindex @code{speedbar-visiting-file-hook}
854@item speedbar-visiting-file-hook
855Hooks run when speedbar visits a file in the selected frame.
856@cindex @code{speedbar-visiting-tag-hook}
857@item speedbar-visiting-tag-hook
858Hooks run when speedbar visits a tag in the selected frame.
859@cindex @code{speedbar-load-hook}
860@item speedbar-load-hook
861Hooks run when speedbar is loaded.
862@cindex @code{speedbar-reconfigure-keymaps-hook}
863@item speedbar-reconfigure-keymaps-hook
864Hooks run when the keymaps are regenerated. Keymaps are reconfigured
865whenever modes change. This will let you add custom key bindings.
866@cindex @code{speedbar-before-popup-hook}
867@item speedbar-before-popup-hook
868Hooks called before popping up the speedbar frame.
869New frames are often popped up when ``power clicking'' on an item to view
870it.
871@cindex @code{speedbar-before-delete-hook}
872@item speedbar-before-delete-hook
873Hooks called before deleting or hiding the speedbar frame.
874@cindex @code{speedbar-mode-hook}
875@item speedbar-mode-hook
876Hooks called after creating a speedbar buffer.
877@cindex @code{speedbar-timer-hook}
878@item speedbar-timer-hook
879Hooks called after running the speedbar timer function.
880@cindex @code{speedbar-scanner-reset-hook}
881@item speedbar-scanner-reset-hook
882Hook called whenever generic scanners are reset.
883Set this to implement your own scanning or rescan safe functions with
884state data.
885@end table
886
887@node Extending, GNU Free Documentation License, Customizing, Top
888@comment node-name, next, previous, up
889@chapter Extending
890@cindex extending
891
892Speedbar can run different types of Major display modes such as Files
893(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage
894different minor display modes for use with buffers handling specialized
895data.
896
897These major and minor display modes are handled through an extension
898system which permits specialized keymaps and menu extensions, in
899addition to a unique rendering function. You can also specify a wide
900range of tagging functions. The default uses @code{imenu}, but new
901tagging methods can be easily added. In this chapter, you will
902learn how to write your own major or minor display modes, and how to
903create specialized tagging functions.
904
905@menu
906* Minor Display Modes:: How to create a minor display mode.
907* Major Display Modes:: How to create a major display mode.
908* Tagging Extensions:: How to create your own tagging methods.
909* Creating a display:: How to insert buttons and hierarchies.
910@end menu
911
912@node Minor Display Modes, Major Display Modes, Extending, Extending
913@section Minor Display Modes
914@cindex create minor display mode
915
916A @dfn{minor display mode} is a mode useful when using a specific type of
917buffer. This mode might not be useful for any other kind of data or
918mode, or may just be more useful that a files or buffers based mode when
919working with a specialized mode.
920
921Examples that already exist for speedbar include RMAIL, Info, and gdb.
922These modes display information specific to the major mode shown in the
923attached frame.
924
925To enable a minor display mode in your favorite Major mode, follow these
926steps. The string @samp{@var{name}} is the name of the major mode being
927augmented with speedbar.
928
929@enumerate
930@item
931Create the keymap variable @code{@var{name}-speedbar-key-map}.
932
933@item
934Create a function, named whatever you like, which assigns values into your
935keymap. Use this command to create the keymap before assigning
936bindings:
937
938@smallexample
939 (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap))
940@end smallexample
941
942This function creates a special keymap for use in speedbar.
943
944@item
945Call your install function, or assign it to a hook like this:
946
947@smallexample
948(if (featurep 'speedbar)
949 (@var{name}-install-speedbar-variables)
950 (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))
951@end smallexample
952
953@item
954Create an easymenu compatible vector named
955@code{@var{name}-speedbar-menu-items}. This will be spliced into
956speedbar's control menu.
957
958@item
959Create a function called @code{@var{name}-speedbar-buttons}. This function
960should take one variable, which is the buffer for which it will create
961buttons. At this time @code{(current-buffer)} will point to the
962uncleared speedbar buffer.
963@end enumerate
964
965When writing @code{@var{name}-speedbar-buttons}, the first thing you will
966want to do is execute a check to see if you need to re-create your
967display. If it needs to be cleared, you need to erase the speedbar
968buffer yourself, and start drawing buttons. @xref{Creating a display}.
969
970@node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending
971@section Major Display Modes
972@cindex create major display mode
973
974Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap,
975an easy-menu segment, and writing several functions. These items can be
976given any name, and are made the same way as in a minor display mode
977(@pxref{Minor Display Modes}). Once this is done, these items need to be
978registered.
979
980Because this setup activity may or may not have speedbar available when
981it is being loaded, it is necessary to create an install function. This
982function should create and initialize the keymap, and add your
983expansions into the customization tables.
984
985@cindex @code{speedbar-make-specialized-keymap}
986When creating the keymap, use the function
987@code{speedbar-make-specialized-keymap} instead of other keymap making
988functions. This will provide you with the initial bindings needed.
989Some common speedbar functions you might want to bind are:
990
991@table @code
992@cindex @code{speedbar-edit-line}
993@item speedbar-edit-line
994Edit the item on the current line.
995@cindex @code{speedbar-expand-line}
996@item speedbar-expand-line
997Expand the item under the cursor.
998With a numeric argument (@kbd{C-u}), flush cached data before expanding.
999@cindex @code{speedbar-contract-line}
1000@item speedbar-contract-line
1001Contract the item under the cursor.
1002@end table
1003
1004@cindex @code{speedbar-line-path}
1005These function require that function @code{speedbar-line-path} be
1006correctly overloaded to work.
1007
1008Next, register your extension like this;
1009
1010@example
1011 (speedbar-add-expansion-list '("MyExtension"
1012 MyExtension-speedbar-menu-items
1013 MyExtension-speedbar-key-map
1014 MyExtension-speedbar-buttons))
1015@end example
1016
1017There are no limitations to the names you use.
1018
1019The first parameter is the string representing your display mode.
1020The second parameter is a variable name containing an easymenu compatible
1021menu definition. This will be stuck in the middle of speedbar's menu.
1022The third parameter is the variable name containing the keymap we
1023discussed earlier.
1024The last parameter is a function which draws buttons for your mode.
1025This function must take two parameters. The directory currently being
1026displayed, and the depth at which you should start rendering buttons.
1027The function will then draw (starting at the current cursor position)
1028any buttons deemed necessary based on the input parameters.
1029@xref{Creating a display}.
1030
1031Next, you need to register function overrides. This may look something
1032like this:
1033
1034@example
1035(speedbar-add-mode-functions-list
1036 '("MYEXTENSION"
1037 (speedbar-item-info . MyExtension-speedbar-item-info)
1038 (speedbar-line-path . MyExtension-speedbar-line-path)))
1039@end example
1040
1041The first element in the list is the name of you extension. The second
1042is an alist of functions to overload. The function to overload is
1043first, followed by what you want called instead.
1044
1045For @code{speedbar-line-path} your function should take an optional DEPTH
1046parameter. This is the starting depth for heavily indented lines. If
1047it is not provided, you can derive it like this:
1048
1049@example
1050(save-match-data
1051 (if (not depth)
1052 (progn
1053 (beginning-of-line)
1054 (looking-at "^\\([0-9]+\\):")
1055 (setq depth (string-to-int (match-string 1)))))
1056@end example
1057
1058@noindent
1059where the depth is stored as invisible text at the beginning of each
1060line.
1061
1062The path returned should be the full path name of the file associated
1063with that line. If the cursor is on a tag, then the file containing
1064that tag should be returned. This is critical for built in file based
1065functions to work (meaning less code for you to write). If your display
1066does not deal in files, you do not need to overload this function.
1067
1068@cindex @code{speedbar-item-info}
1069The function @code{speedbar-item-info}, however, is very likely to need
1070overloading. This function takes no parameters and must derive a text
1071summary to display in the minibuffer.
1072
1073There are several helper functions you can use if you are going to use
1074built in tagging. These functions can be @code{or}ed since each one
1075returns non-@code{nil} if it displays a message. They are:
1076
1077@table @code
1078@cindex @code{speedbar-item-info-file-helper}
1079@item speedbar-item-info-file-helper
1080This takes an optional @var{filename} parameter. You can derive your own
1081filename, or it will derive it using a (possibly overloaded) function
1082@code{speedbar-line-file}. It shows details about a file.
1083@cindex @code{speedbar-item-info-tag-helper}
1084@item speedbar-item-info-tag-helper
1085If the current line is a tag, then display information about that tag,
1086such as its parent file, and location.
1087@end table
1088
1089Your custom function might look like this:
1090
1091@example
1092(defun MyExtension-item-info ()
1093 "Display information about the current line."
1094 (or (speedbar-item-info-tag-helper)
1095 (message "Interesting detail.")))
1096@end example
1097
1098Once you have done all this, speedbar will show an entry in the
1099@samp{Displays} menu declaring that your extension is available.
1100
1101@node Tagging Extensions, Creating a display, Major Display Modes, Extending
1102@section Tagging Extensions
1103
1104It is possible to create new methods for tagging files in speedbar.
1105To do this, you need two basic functions, one function to fetch the
1106tags from a buffer, the other to insert them below the filename.
1107
1108@defun my-fetch-dynamic-tags file
1109Parse @var{file} for a list of tags. Return the list, or @code{t} if there was
1110an error.
1111@end defun
1112
1113The non-error return value can be anything, as long as it can be
1114inserted by its paired function:
1115
1116@defun my-insert-tag-list level lst
1117Insert a list of tags @var{lst} started at indentation level
1118@var{level}. Creates buttons for each tag, and provides any other
1119display information required.
1120@end defun
1121
1122@cindex @code{speedbar-create-tag-hierarchy}
1123It is often useful to use @code{speedbar-create-tag-hierarchy} on your
1124token list. See that function's documentation for details on what it
1125requires.
1126
1127@cindex @code{speedbar-dynamic-tags-function-list}
1128Once these two functions are written, modify the variable
1129@code{speedbar-dynamic-tags-function-list} to include your parser at the
1130beginning, like this:
1131
1132@example
1133(add-to-list 'speedbar-dynamic-tags-function-list
9360256a 1134 '(my-fetch-dynamic-tags . my-insert-tag-list))
4009494e
GM
1135@end example
1136
1137If your parser is only good for a few types of files, make sure that it
1138is either a buffer local modification, or that the tag generator returns
1139@code{t} for non valid buffers.
1140
1141@node Creating a display, , Tagging Extensions, Extending
1142@section Creating a display
1143@cindex creating a display
1144
1145Rendering a display in speedbar is completely flexible. When your
1146button function is called, see @ref{Minor Display Modes}, and @ref{Major
1147Display Modes}, you have control to @code{insert} anything you want.
1148
1149The conventions allow almost anything to be inserted, but several helper
1150functions are provided to make it easy to create the standardized
1151buttons.
1152
1153To understand the built in functions, each `button' in speedbar consists
1154of four important pieces of data. The text to be displayed, token
1155data to be associated with the text, a function to call, and some face to
1156display it in.
1157
1158When a function is provided, then that text becomes mouse activated,
1159meaning the mouse will highlight the text.
1160
1161Additionally, for data which can form deep trees, each line is given a
1162depth which indicates how far down the tree it is. This information is
1163stored in invisible text at the beginning of each line, and is used by
1164the navigation commands.
1165
1166@defun speedbar-insert-button text face mouse function &optional token prevline
1167This function inserts one button into the current location.
1168@var{text} is the text to insert. @var{face} is the face in which it
1169will be displayed. @var{mouse} is the face to display over the text
1170when the mouse passes over it. @var{function} is called whenever the
1171user clicks on the text.
1172
1173The optional argument @var{token} is extra data to associated with the
1174text. Lastly @var{prevline} should be non-@code{nil} if you want this line to
1175appear directly after the last button which was created instead of on
1176the next line.
1177@end defun
1178
1179@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
1180
1181Create a tag line with @var{exp-button-type} for the small expansion
1182button. This is the button that expands or contracts a node (if
1183applicable), and @var{exp-button-char} the character in it (@samp{+},
1184@samp{-}, @samp{?}, etc). @var{exp-button-function} is the function
1185to call if it's clicked on. Button types are @code{bracket},
1186@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and
1187@code{nil}. @var{exp-button-data} is extra data attached to the text
1188forming the expansion button.
1189
1190Next, @var{tag-button} is the text of the tag.
1191@var{tag-button-function} is the function to call if clicked on, and
1192@var{tag-button-data} is the data to attach to the text field (such a
1193tag positioning, etc). @var{tag-button-face} is a face used for this
1194type of tag.
1195
1196Lastly, @var{depth} shows the depth of expansion.
1197
1198This function assumes that the cursor is in the speedbar window at the
1199position to insert a new item, and that the new item will end with a CR.
1200@end defun
1201
1202@defun speedbar-insert-generic-list level list expand-fun find-fun
1203
1204At @var{level}, (the current indentation level desired) insert a generic
1205multi-level alist @var{list}. Associations with lists get @samp{@{+@}}
1206tags (to expand into more nodes) and those with positions or other data
1207just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the
1208function @var{expand-fun} and the token is the @code{cdr} list. The
1209token name will have the function @var{find-fun} and not token.
1210
1211Each element of the list can have one of these forms:
1212
1213@table @code
1214@item (@var{name} . marker-or-number)
1215One tag at this level.
1216@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... )
1217One group of tags.
1218@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... )
1219One Group of tags where the group has a starting position.
1220@end table
1221
1222When you use @code{speedbar-insert-generic-list}, there are some
1223variables you can set buffer-locally to change the behavior. The most
1224obvious is @code{speedbar-tag-hierarchy-method}.
1225@xref{Tag Hierarchy Methods}.
1226
1227@defvar speedbar-generic-list-group-expand-button-type
1228This is the button type used for groups of tags, whether expanded
1229or added in via a hierarchy method. Two good values are
1230@code{curly} and @code{expandtag}. Curly is the default button, and
1231@code{expandtag} is useful if the groups also has a position.
1232@end defvar
1233
1234@defvar speedbar-generic-list-tag-button-type
1235This is the button type used for a single tag.
1236Two good values are @code{nil} and @code{statictag}.
1237@code{nil} is the default, and @code{statictag} has the same width as
1238@code{expandtag}.
1239@end defvar
1240
1241@end defun
1242
1243@node GNU Free Documentation License, Index, Extending, Top
1244@appendix GNU Free Documentation License
1245@include doclicense.texi
1246
1247
1248@node Index, , GNU Free Documentation License, Top
1249@comment node-name, next, previous, up
1250@unnumbered Concept Index
1251@printindex cp
1252
1253@bye
1254@c LocalWords: speedbar's xref slowbar kbd subsubsection
1255@c LocalWords: keybindings
1256
1257@ignore
1258 arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02
1259@end ignore