\input texinfo @c -*-texinfo-*-@c@c $Id: speedbar.texi,v 1.1 2000/10/20 01:53:35 zappo Exp $@c@c This file is part of GNU Emacs@c GNU Emacs is free software; you can redistribute it and/or modify it@c under the terms of the GNU General Public License as published by the@c Free Software Foundation; either version 2 of the License, or (at@c your option) any later version.@c GNU Emacs is distributed in the hope that it will be useful, but@c WITHOUT ANY WARRANTY; without even the implied warraonty of@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU@c General Public License for more details.@c You should have received a copy of the GNU General Public License@c along with Eshell; see the file COPYING. If not, write to the Free@c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.@setfilename ../info/speedbar@settitle Speedbar: File/Tag summarizing utility@ifinfo@formatSTART-INFO-DIR-ENTRY* Speedbar: (speedbar). File/Tag summarizing utility.END-INFO-DIR-ENTRY@end format@end ifinfo@titlepage@sp 10@center @titlefont{speedbar}@vskip 0pt plus 1 fillCopyright @copyright{} 1999, 2000 Eric M. Ludlam@end titlepage@syncodeindex fn cp@node Top, , , (dir)Top@comment node-name, next, previous, upCopyright @copyright{} 1999 Eric M. LudlamSpeedbar is a program for Emacs which can be used to summarizeinformation related to the current buffer. Its original inspirationis the "explorer" often used in modern development environments, officepackages, and web browsers.Speedbar displays a narrow frame in which a tree view is shown. Thistree view defaults to containing a list of files and directories. Filescan be "expanded" to list tags inside. Directories can be expanded tolist the files within itself. Each file or tag can be jumped toimmediately.Speedbar expands upon "explorer" windows by maintaining context with theuser. For example, when using the file view, the current buffer's fileis highlighted. Speedbar also mimics the explorer windows by providingmultiple display modes. These modes come in two flavors. Major displaymodes remain consistent across buffers, and minor display modes appearonly when a buffer of the applicable type is shown. This allowsauthors of other packages to provide speedbar summaries customized tothe needs of that mode.Throughout this manual, activities are defined as "clicking on", or"expanding" items. Clicking means using using @kbd{mouse-2} on abutton. Expanding refers to clicking on an expansion button to displayan expanded summary of the entry the expansion button ison. @xref{Basic Navigation}.@menu* Introduction:: Basics of speedbar.* Basic Navigation:: Basics of speedbar common between all modes.* File Mode:: Summarizing files.* Buffer Mode:: Summarizing buffers.* Minor Modes:: Additional minor modes such as Info and RMAIL.* Customizing:: Changing speedbar behavior.* Extending:: Extend speedbar for your own project.* Index::@end menu@node Introduction, Basic Navigation, , Top@comment node-name, next, previous, up@chapter Introduction@cindex introductionTo start using speedbar use the command @kbd{M-x speedbar RET} or selectit from the Tools menu in versions of Emacs with speedbar installed bydefault. This command will open a new frame to summarize the localfiles. On X Window systems or on MS-Windows, speedbar's frame is twentycharacters wide, and will mimic the height of the frame from which itwas started. It positions itself to the left or right of the frame youstarted it from.To use speedbar effectivly, it is important to understand itsrelationship with the frame you started it from. This frame is the@dfn{attached frame} which speedbar will use as a reference point. Oncestarted, speedbar watches the contents of this frame, and attempts tomake it's contents relevant to the buffer loaded into the attachedframe. In addition, all requests made in speedbar that require thedisplay of another buffer will display in the attached frame.When used in terminal mode, the new frame appears the same size as theterminal. Since it is not visible while working in the attached frame,speedbar will save time by using the @dfn{slowbar mode}, where no tracking isdone until speedbar is requested to show itself (i.e., the speedbar'sframe becomes the selected frame).@cindex @code{speedbar-get-focus}The function to use when switching between frames using the keyboard is@code{speedbar-get-focus}. This function will toggle between frames, andit's useful to bind it to a key in terminal mode. @xref{Customizing}.@node Basic Navigation, File Mode, Introduction, Top@comment node-name, next, previous, up@chapter Basic NavigationSpeedbar can display different types of data, and has several displayand behavior modes. These modes all have a common behavior, menusystem, and look. If one mode is learned, then the other modes are easyto use.@menu* Basic Keybindings::* Basic Visuals::* Mouse Bindings::* Displays Submenu::@end menu@node Basic Keybindings, Basic Visuals, Basic Navigation, Basic Navigation@comment node-name, next, previous, up@section Basic Keybindings@cindex keybindingsThese keybindings are common across all modes:@table @kbd@item delete, SPC@cindex scrolling in speedbarScroll up and down one page.@item Q@cindex quitting speedbarQuit speedbar, and kill the frame.@item qQuit speedbar, and hide the frame. This makes it faster to restore thespeedbar frame, than if you press @kbd{Q}.@item g@cindex refresh speedbar displayRefresh whatever contents are in speedbar.@item t@cindex slowbar modeToggle speedbar to and from slowbar mode. In slowbar mode, frametracking is not done.@item n@itemx p@cindex navigationMove, respectively, to the next or previous item. A summary of thatitem will be displayed in the attached frame's minibuffer.@item M-n@itemx M-pMove to the next or previous item in a restricted fashion. If a list isopen, the cursor will skip over it. If the cursor is in an open list,it will not leave it.@item C-M-n@itemx C-M-nMove forwards and backwards across extended groups. This lets youquickly skip over all files, directories, or other common sub-items atthe same current depth.@item C-x bSwitch buffers in the attached frame.@end tableSpeedbar can handle multiple modes. Two are provided by default.These modes are File mode, and Buffers mode. There are accelerators toswitch into these different modes.@cindex mode switching hotkeys@table @kbd@item bSwitch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, theprevious display mode is restored.@item fSwitch into File mode.@item rSwitch back to the previous mode.@end tableSome modes provide groups, lists and tags. @xref{Basic Visuals}. Whenthese are available, some additional common bindings are available.@cindex common keys@table @kbd@item RET@itemx eEdit/Open the current group or tag. This behavior is dependent on themode. In general, files or buffers are opened in the attached frame,and directories or group nodes are expanded locally.@item +@itemx =Expand the current group, displaying sub items.When used with a prefix argument, any data that may have been cached isflushed. This is similar to a power click. @xref{Mouse Bindings}.@item -Contract the current group, hiding sub items.@end table@node Basic Visuals, Mouse Bindings, Basic Keybindings, Basic Navigation@comment node-name, next, previous, up@section Basic Visuals@cindex visualsSpeedbar has visual cues for indicating different types of data. Thesecues are used consistently across the different speedbar modes to makethem easier to interpret.At a high level, in File mode, there are directory buttons, subdirectory buttons, file buttons, tag buttons, and expansion buttons.This makes it easy to use the mouse to navigate a directory tree, andquickly view files, or a summary of those files.The most basic visual effect used to distinguis between these buttontypes is color and mouse highlighting. Anything the mouse highlightscan be clicked on and is called a button (@pxref{Mouse Bindings}).Anything not highlighted by the mouse will not be clickable.Text in speedbar consists of four different types of data. Knowing howto read these textual elements will make it easier to navigate byidentifying the types of data available.@subsubsection Groups@cindex groupsGroups summarize information in a single line, and provide a high levelview of more complex systems, like a directory tree, or manual chapters.Groups appear at different indentation levels, and are prefixed with a@samp{+} in some sort of "box". The group name will summarize theinformation within it, and the expansion box will display thatinformation inline. In File mode, directories and files are "groups"where the @samp{+} is surrounded by brackets like this:@example<+> include<-> src [+] foo.c@end exampleIn this example, we see both open and closed directories, in addition toa file. The directories have a box consisting of angle brackets, and afile uses square brackets.In all modes, a group can be "edited" by pressing @kbd{RET}, meaning afile will be opened, or a directory explicitly opened in speedbar. Agroup can be expanded or contracted using @kbd{+} or@kbd{-}. @xref{Basic Keybindings}.Sometimes groups may have a @samp{?} in it's indicator box. This meansthat it is a group type, but there are no contents, or no known way ofextracting contents of that group.When a group has been expanded, the indicator button changes from@samp{+} to @samp{-}. This indicates that the contents are being shown.Click the @samp{-} button to contract the group, or hide the contentscurrently displayed.@subsubsection Tags@cindex tagsTags are the leaf nodes of the tree system. Tags are generally prefixedwith a simple character, such as @samp{>}. Tags can only be jumped to using@kbd{RET} or @kbd{e}.@subsubsection Boolean FlagsSometimes a group or tag is given a boolean flag. These flags appear asextra text characters at the end of the line. File mode uses booleanflags, such as a @samp{*} to indicate that a file has been checked outof a versioning system.For additional flags, see@c Note to self, update these to sub-nodes which are more relevant.@ref{File Mode}, and @ref{Version Control}.@subsubsection Unadorned TextUnadorned text generally starts in column 0, without any special symbolsprefixing them. In Buffers mode different buffer groups are prefixedwith a description of what the following buffers are (Files, scratchbuffers, and invisible buffers.)Unadorned text will generally be colorless, and not clickable.@subsubsection Color CuesEach type of Group, item indicator, and label is given a differentcolor. The colors chosen are dependent on whether the background coloris light or dark.Of important note is that the "current item", which may be a buffer orfile name, is highlighted red, and underlined.Colors can be customized from the group @code{speedbar-faces}. Somemodes, such as for Info, will use the Info colors instead of defaultspeedbar colors as an indication of what is currently being displayed.The face naming convention mirrors the File display mode. Modes whichdo not use files will attempt to use the same colors on analogousentries.@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation@comment node-name, next, previous, up@section Mouse Bindings@cindex mouse bindingsThe mouse has become a common information navigation tool. Speedbarwill use the mouse to navigate file systems, buffer lists, and otherdata. The different textual cues provide buttons which can be clickedon (@pxref{Basic Visuals}). Anything that highlights can be clicked onwith the mouse, or effected by the menu.The mouse bindings are:@table @kbd@item mouse-1Move cursor to that location.@item mouse-2@itemx double-mouse-1Activate the current button. @kbd{double-mouse-1} is called a @dfn{doubleclick} on other platforms, and is useful for windows users with twobutton mice.@c Isn't it true that with two-button mice, the right button is mouse-2?@item S-mouse-2@itemx S-double-mouse-1@cindex power clickThis has the same effect as @kbd{mouse-2}, except it is called a powerclick. This means that if a group with an expansion button @samp{+} isclicked, any caches are flushed, and subitems re-read. If it is a name,it will be opened in a new frame.@item mouse-3Activate the speedbar menu. The item selected effects the line clicked,not the line where the cursor was.@item mode-line mouse-1Activate the menu. This affects the item the cursor is on before theclick, since the mouse was not clicked on anything.@item C-mouse-1Buffers sub-menu. The buffer in the attached frame is switched.@end tableWhen the mouse moves over buttons in speedbar, details of that itemshould be displayed in the minibuffer of the attached frame. Sometimesthis can contain extra information such as file permissions, or taglocation.@node Displays Submenu, , Mouse Bindings, Basic Navigation@comment node-name, next, previous, up@section Displays Submenu@cindex displays submenuYou can display different data by using different display modes. Thesespecialized modes make it easier to navigate the relevant pieces ofinformation, such as files and directories, or buffers.In the main menu, found by clicking @kbd{mouse-3}, there is a submenulabeled ``Displays''. This submenu lets you easily choose betweendifferent display modes.The contents are modes currently loaded into emacs. By default, thiswould include Files, Quick Buffers, and Buffers. Other major displaymodes such as Info are loaded separately.@node File Mode, Buffer Mode, Basic Navigation, Top@comment node-name, next, previous, up@chapter File Mode@cindex file modeFile mode displays a summary of your current directory. You can displayfiles in the attached frame, or summarize the tags found in files. Youcan even see if a file is checked out of a version control system, orhas some associated object file.Advanced behavior, like copying and renaming files, is also provided.@menu* Directory Display:: What the display means.* Hidden Files:: How to display hidden files.* File Keybindings:: Performing file operations.@end menu@node Directory Display, Hidden Files, File Mode, File Mode@comment node-name, next, previous, up@section Directory Display@cindex directory displayThere are three major sections in the display. The first line or two isthe root directory speedbar is currently viewing. You can jump to oneof the parent directories by clicking on the name of the directory youwish to jump to.Next, directories are listed. A directory starts with the groupindicator button @samp{<+>}. Clicking the directory name makes speedbarload that directory as the root directory for its display. Clicking the@samp{<+>} button will list all directories and files beneath.Next, files are listed. Files start with the group indicator @samp{[+]}or @samp{[?]}. You can jump to a file in the attached frame by clickingon the file name. You can expand a file and look at its tags byclicking on the @samp{[+]} symbol near the file name.A typical session might look like this:@example~/lisp/<+> checkdoc<+> eieio<-> speedbar [+] Makefile [+] rpm.el # [+] sb-gud.el # [+] sb-info.el # [+] sb-rmail.el # [+] sb-w3.el [-] speedbar.el *! @{+@} Types @{+@} Variables @{+@} def (group) @{+@} speedbar- [+] speedbar.texi *<+> testme[+] align.el[+] autoconf.el@end exampleIn this example, you can see several directories. The directory@file{speedbar} has been opened inline. Inside the directory@file{speedbar}, the file @file{speedbar.el} has its tags exposed.These tags are extensive, and they are summarized into tag groups.Files get additional boolean flags associated with them. Valid flags are:@cindex file flags@table @code@item *This file has been checked out of a version controlsystem. @xref{Version Control}.@cindex @code{speedbar-obj-alist}@item #This file has an up to date object file associated with it. Thevariable @code{speedbar-obj-alist} defines how speedbar determines thisvalue.@item !This file has an out of date object file associated with it.@end tableA Tag group is prefixed with the symbol @samp{@{+@}}. Clicking thissymbol will show all symbols that have been organized into that group.Different types of files have unique tagging methods as defined by theirmajor mode. Tags are generated with either the @code{imenu} package, orthrough the @code{etags} interface.Tag groups are defined in multiple ways which make it easier to find thetag you are looking for. Imenu keywords explicitly create groups, andspeedbar will automatically create groups if tag lists are too long.In our example, Imenu created the groups @samp{Types} and@samp{Variables}. All remaining top-level symbols are then regroupedbased on the variable @code{speedbar-tag-hierarchy-method}. Thesubgroups @samp{def} and @samp{speedbar-} are groupings where the firstfew characters of the given symbols are specified in the group name.Some group names may say something like @samp{speedbar-t to speedbar-v},indicating that all symbols which alphabetically fall between thosecatagories are included in that sub-group. @xref{Tag Hierarchy Methods}.@node Hidden Files, File Keybindings, Directory Display, File Mode@comment node-name, next, previous, up@section Hidden Files@cindex hidden filesOn Unix, a hidden file is a file whose name starts with a period. Theyare hidden from a regular directory listing because the user is notgenerally interested in them.In speedbar, a hidden file is a file which isn't very interesting andmight prove distracting to the user. Any uninteresting files areremoved from the File display. There are two levels of uninterest inspeedbar. The first level of uninterest are files which have noexpansion method, or way of extracting tags. The second level is anyfile that matches the same pattern used for completion in@code{find-file}. This is derived from the variable@code{completion-ignored-extensions}.You can toggle the display of uninteresting files from the toggle menuitem @samp{Show All Files}. This will display all level one hidden files.These files will be shown with a @samp{?} indicator. Level 2 hiddenfiles will still not be shown.Object files fall into the category of level 2 hidden files. You candetermine their presence by the @samp{#} and @samp{!} file indicators.@xref{Directory Display}.@node File Keybindings, , Hidden Files, File Mode@comment node-name, next, previous, up@section File Keybindings@cindex file keybindingsFile mode has keybindings permitting different file system operationssuch as copy or rename. These commands all operate on the @dfn{currentfile}. In this case, the current file is the file at point, or clickedon when pulling up the menu.@table @kbd@item UMove the entire speedbar display up one directory.@item IDisplay information in the minibuffer about this line. This is the sameinformation shown when navigating with @kbd{n} and @kbd{p}, or movingthe mouse over an item.@item BByte compile the Emacs Lisp file on this line.@item LLoad the Emacs Lisp file on this line. If a @file{.elc} file exists,optionally load that.@item CCopy the current file to some other location.@item RRename the current file, possibly moving it to some other location.@item DDelete the current file.@item ODelete the current file's object file. Use the symbols @samp{#} and@samp{!} to determine if there is an object file available.@end tableOne menu item toggles the display of all available files. By default,only files which Emacs understands, and knows how to convert into a taglist, are shown. By showing all files, additional files such as text files arealso displayed, but they are prefixed with the @samp{[?]} symbol. Thismeans that it is a file, but Emacs doesn't know how to expand it.@node Buffer Mode, Minor Modes, File Mode, Top@comment node-name, next, previous, up@chapter Buffer Mode@cindex buffer modeBuffer mode is very similar to File mode, except that instead oftracking the current directory and all files available there, thecurrent list of Emacs buffers is shown.These buffers can have their tags expanded in the same way as files,and uses the same unknown file indicator (@pxref{File Mode}).Buffer mode does not have file operation bindings, but the followingbuffer specific keybindings are available:@table @kbd@item kKill this buffer. Do not touch its file.@item rRevert this buffer, reloading from disk.@end tableIn addition to Buffer mode, there is also Quick Buffer mode. In fact,Quick Buffers is bound to the @kbd{b} key. The only difference betweenBuffers and Quick Buffers is that after one operation is performedwhich effects the attached frame, the display is immediately reverted tothe last displayed mode.Thus, if you are in File mode, and you need quick access to a buffer,press @kbd{b}, click on the buffer you want, and speedbar will revertback to File mode.@node Minor Modes, Customizing, Buffer Mode, Top@comment node-name, next, previous, up@chapter Minor Display Modes@cindex minor display modesFor some buffers, a list of files and tags makes no sense. This couldbe because files are not currently in reference (such as web pages), orthat the files you might be interested have special properties (such asemail folders.)In these cases, a minor display mode is needed. A minor display modewill override any major display mode currently being displayed for theduration of the specialized buffer's use. Minor display modeswill follow the general rules of their major counterparts in terms ofkeybindings and visuals, but will have specialized behaviors.@menu* RMAIL:: Managing folders in speedbar* Info:: Browsing topics in speedbar* GDB:: Managing the current stack trace in speedbar@end menu@node RMAIL, Info, Minor Modes, Minor Modes@comment node-name, next, previous, up@section RMAIL@cindex RMAILWhen using RMAIL, speedbar will display two sections. The first is alayer one reply button. Clicking here will initialize a reply buffershowing only this email address in the @samp{To:} field.The second section lists all RMAIL folders in the same directory as yourmain RMAIL folder. The general rule is that RMAIL folders always appearin all caps, or numbers. It is possible to save mail in folders withlower case letters, but there is no clean way of detecting such RMAIL folderswithout opening them all.Each folder can be visited by clicking the name. You can move mail fromthe current RMAIL folder into a different folder by clicking the@samp{<M>} button. The @samp{M} stands for Move.In this way you can manage your existing RMAIL folders fairly easilyusing the mouse.@node Info, GDB, RMAIL, Minor Modes@comment node-name, next, previous, up@section Info@cindex InfoWhen browsing Info files, all local relevant information is displayed inthe info buffer and a topical high-level view is provided in speedbar.All top-level info nodes are shown in the speedbar frame, and can bejumped to by clicking the name.You can open these nodes with the @samp{[+]} button to see what sub-topicsare available. Since these sub-topics are not examined until you clickthe @samp{[+]} button, sometimes a @samp{[?]} will appear when you click ona @samp{[+]}, indicating that there are no sub-topics.@node GDB, , Info, Minor Modes@comment node-name, next, previous, up@section GDB@cindex gdb@cindex gudIf you are debugging an application with GDB in Emacs, speedbar can showyou the current stack when the current buffer is the @file{*gdb*}buffer. Usually, it will just report that there is no stack, but whenthe application is stopped, the current stack will be shown.You can click on any stack element and gdb will move to that stacklevel. You can then check variables local to that level at the GDBprompt.This mode has the unfortunate side-effect of breaking GDB's repeatfeature when you hit @kbd{RET} since your previous command is overriddenwith a stack fetching command.@node Customizing, Extending, Minor Modes, Top@comment node-name, next, previous, up@chapter Customizing@cindex customizingSpeedbar is highly customizable, with a plethora of control elements.Since speedbar is so visual and reduces so much information, this is animportant aspect of its behavior.In general, there are three custom groups you can use to quickly modifyspeedbar's behavior.@table @code@item speedbarBasic speedbar behaviors.@item speedbar-vcCustomizations regarding version control handling.@item speedbar-facesCustomize speedbar's many colors and fonts.@end table@menu* Frames and Faces:: Visible behaviors.* Tag Hierarchy Methods:: Customizing how tags are displayed.* Version Control:: Adding new VC detection modes.* Hooks:: The many hooks you can use.@end menu@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing@comment node-name, next, previous, up@section Frames and Faces@cindex faces@cindex frame parametersThere are several faces speedbar generates to provide a consistentcolor scheme across display types. You can customize these faces usingyour favorite method. They are:@table @asis@cindex @code{speedbar-button-face}@item speedbar-button-faceFace used on expand/contract buttons.@cindex @code{speedbar-file-face}@item speedbar-file-faceFace used on Files. Should also be used on non-directory like nodes.@cindex @code{speedbar-directory-face}@item speedbar-directory-faceFace used for directories, or nodes which consist of groups of other nodes.@cindex @code{speedbar-tag-face}@item speedbar-tag-faceFace used for tags in a file, or for leaf items.@cindex @code{speedbar-selected-face}@item speedbar-selected-faceFace used to highlight the selected item. This would be the currentfile being edited.@cindex @code{speedbar-highlight-face}@item speedbar-highlight-faceFace used when the mouse passes over a button.@end tableYou can also customize speedbar's initial frame parameters. How this isaccomplished is dependent on your platform being Emacs or XEmacs.@cindex @code{speedbar-frame-parameters}, EmacsIn Emacs, change the alist @code{speedbar-frame-parameters}. Thisvariable is used to set up initial details. Height is alsoautomatically added when speedbar is created, though you can overrideit.@cindex @code{speedbar-frame-plist}, XEmacsIn XEmacs, change the plist @code{speedbar-frame-plist}. This is theXEmacs way of doing the same thing.@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing@comment node-name, next, previous, up@section Tag Hierarchy Methods@cindex tag hierarchy@cindex tag groups@cindex tag sortingWhen listing tags within a file, it is possible to get an annoyinglylong list of entries. Imenu (which generates the tag list in Emacs)will group some classes of items automatically. Even here, however,some tag groups can be quite large.@cindex @code{speedbar-tag-hierarchy-method}To solve this problem, tags can be grouped into logical units through ahierarchy processor. The specific variable to use is@code{speedbar-tag-hierarchy-method}. There are several methods thatcan be applied in any order. They are:@table @code@cindex @code{speedbar-trim-words-tag-hierarchy}@item speedbar-trim-words-tag-hierarchyFind a common prefix for all elements of a group, and trim it off.@cindex @code{speedbar-prefix-group-tag-hierarchy}@item speedbar-prefix-group-tag-hierarchyIf a group is too large, place sets of tags into bins based on commonprefixes.@cindex @code{speedbar-simple-group-tag-hierarchy}@item speedbar-simple-group-tag-hierarchyTake all items in the top level list not in a group, and stick them intoa @samp{Tags} group.@cindex @code{speedbar-sort-tag-hierarchy}@item speedbar-sort-tag-hierarchySort all items, leaving groups on top.@end tableYou can also add your own functions to reorganize tags as you see fit.Some other control variables are:@table @code@cindex @code{speedbar-tag-group-name-minimum-length}@item speedbar-tag-group-name-minimum-lengthDefault value: 4.The minimum length of a prefix group name before expanding. Thus, ifthe @code{speedbar-tag-hierarchy-method} includes@code{speedbar-prefix-group-tag-hierarchy} and one such group's commoncharacters is less than this number of characters, then the group namewill be changed to the form of:@exampleworda to wordb@end exampleinstead of just@exampleword@end exampleThis way we won't get silly looking listings.@cindex @code{speedbar-tag-split-minimum-length}@item speedbar-tag-split-minimum-lengthDefault value: 20.Minimum length before we stop trying to create sub-lists in tags.This is used by all tag-hierarchy methods that break large lists intosub-lists.@cindex @code{speedbar-tag-regroup-maximum-length}@item speedbar-tag-regroup-maximum-lengthDefault value: 10.Maximum length of submenus that are regrouped.If the regrouping option is used, then if two or more short subgroupsare next to each other, then they are combined until this number ofitems is reached.@end table@node Version Control, Hooks, Tag Hierarchy Methods, Customizing@comment node-name, next, previous, up@section Version Control@cindex version control@cindex vc extensionsWhen using the file mode in speedbar, information regarding a versioncontrol system adds small details to the display. If a file is in aversion control system, and is ``checked out'', or ``locked'' locally, anasterisk @samp{*} is placed at the end of the file name. In addition,the directory name for Version Control systems are left out of thespeedbar display.@cindex @code{speedbar-directory-unshown-regexp}You can easily add new version control systems into speedbar's detectionscheme. To make a directory ``disappear'' from the list, use the variable@code{speedbar-directory-unshown-regexp}.@cindex @code{speedbar-vc-path-enable-hook}Next, you need to write entries for two hooks. The first is@code{speedbar-vc-path-enable-hook} which will enable a VC check in thecurrent directory for the group of files being checked. Your hookfunction should take one parameter (the directory to check) and return@code{t} if your VC method is in control here.@cindex @code{speedbar-vc-in-control-hook}The second function is @code{speedbar-vc-in-control-hook}. This hooktakes two parameters, the @var{path} of the file to check, and the@var{file} name. Return @code{t} if you want to have the asteriskplaced near this file.@cindex @code{speedbar-vc-indicator}Lastly, you can change the VC indicator using the variable@code{speedbar-vc-indicator}, and specify a single character string.@node Hooks, , Version Control, Customizing@comment node-name, next, previous, up@section Hooks@cindex hooksThere are several hooks in speedbar allowing custom behaviors to beadded. Available hooks are:@table @code@cindex @code{speedbar-visiting-file-hook}@item speedbar-visiting-file-hookHooks run when speedbar visits a file in the selected frame.@cindex @code{speedbar-visiting-tag-hook}@item speedbar-visiting-tag-hookHooks run when speedbar visits a tag in the selected frame.@cindex @code{speedbar-load-hook}@item speedbar-load-hookHooks run when speedbar is loaded.@cindex @code{speedbar-reconfigure-keymaps-hook}@item speedbar-reconfigure-keymaps-hookHooks run when the keymaps are regenerated. Keymaps are reconfiguredwhenever modes change. This will let you add custom keybindings.@cindex @code{speedbar-before-popup-hook}@item speedbar-before-popup-hookHooks called before popping up the speedbar frame.New frames are often popped up when ``power clicking'' on an item to viewit.@cindex @code{speedbar-before-delete-hook}@item speedbar-before-delete-hookHooks called before deleting or hiding the speedbar frame.@cindex @code{speedbar-mode-hook}@item speedbar-mode-hookHooks called after creating a speedbar buffer.@cindex @code{speedbar-timer-hook}@item speedbar-timer-hookHooks called after running the speedbar timer function.@cindex @code{speedbar-scanner-reset-hook}@item speedbar-scanner-reset-hookHook called whenever generic scanners are reset.Set this to implement your own scanning or rescan safe functions withstate data.@end table@node Extending, Index, Customizing, Top@comment node-name, next, previous, up@chapter Extending@cindex extendingSpeedbar can run different types of Major display modes such as Files(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also managedifferent minor display modes for use with buffers handling specializeddata.These major and minor display modes are handled through an extensionsystem which permits specialized keymaps and menu extensions, inaddition to a unique rendering function. You can also specify a widerange of tagging functions. The default uses @code{imenu}, but newtagginging methods can be easilly added. In this chapter, you willlearn how to write your own major or minor display modes, and how tocreate specialized tagging functions.@menu* Minor Display Modes:: How to create a minor display mode.* Major Display Modes:: How to create a major display mode.* Tagging Extentions:: How to create your own tagging methods.* Creating a display:: How to insert buttons and hierarchies.@end menu@node Minor Display Modes, Major Display Modes, Extending, Extending@section Minor Display Modes@cindex create minor display modeA @dfn{minor display mode} is a mode useful when using a specific type ofbuffer. This mode might not be useful for any other kind of data ormode, or may just be more useful that a files or buffers based mode whenworking with a specialized mode.Examples that already exist for speedbar include RMAIL, Info, and gdb.These modes display information specific to the major mode shown in theattached frame.To enable a minor display mode in your favorite Major mode, follow thesesteps. The string @samp{@var{name}} is the name of the major mode beingaugmented with speedbar.@enumerate@itemCreate the keymap variable @code{@var{name}-speedbar-key-map}.@itemCreate a function, named whatever you like, which assigns values into yourkeymap. Use this command to create the keymap before assigningbindings:@smallexample (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap))@end smallexampleThis function creates a special keymap for use in speedbar.@itemCall your install function, or assign it to a hook like this:@smallexample(if (featurep 'speedbar) (@var{name}-install-speedbar-variables) (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))@end smallexample@itemCreate an easymenu compatible vector named@code{@var{name}-speedbar-menu-items}. This will be spliced intospeedbar's control menu.@itemCreate a function called @code{@var{name}-speedbar-buttons}. This functionshould take one variable, which is the buffer for which it will createbuttons. At this time @code{(current-buffer)} will point to theuncleared speedbar buffer.@end enumerateWhen writing @code{@var{name}-speedbar-buttons}, the first thing you willwant to do is execute a check to see if you need to re-create yourdisplay. If it needs to be cleared, you need to erase the speedbarbuffer yourself, and start drawing buttons. @xref{Creating a display}.@node Major Display Modes, Tagging Extentions, Minor Display Modes, Extending@section Major Display Modes@cindex create major display modeCreating a @dfn{Major Display Mode} for speedbar requires authoring a keymap,an easy-menu segment, and writing several functions. These items can begiven any name, and are made the same way as in a minor display mode(@pxref{Minor Display Modes}). Once this is done, these items need to beregistered.Because this setup activity may or may not have speedbar available whenit is being loaded, it is necessary to create an install function. Thisfunction should create and initialize the keymap, and add yourexpansions into the customization tables.@cindex @code{speedbar-make-specialized-keymap}When creating the keymap, use the function@code{speedbar-make-specialized-keymap} instead of other keymap makingfunctions. This will provide you with the initial bindings needed.Some common speedbar functions you might want to bind are:@table @code@cindex @code{speedbar-edit-line}@item speedbar-edit-lineEdit the item on the current line.@cindex @code{speedbar-expand-line}@item speedbar-expand-lineExpand the item under the cursor.With a numeric argument (@kbd{C-u}), flush cached data before expanding.@cindex @code{speedbar-contract-line}@item speedbar-contract-lineContract the item under the cursor.@end table@cindex @code{speedbar-line-path}These function require that function @code{speedbar-line-path} becorrectly overloaded to work.Next, register your extension like this;@example (speedbar-add-expansion-list '("MyExtension" MyExtension-speedbar-menu-items MyExtension-speedbar-key-map MyExtension-speedbar-buttons))@end exampleThere are no limitations to the names you use.The first parameter is the string representing your display mode.The second parameter is a variable name containing an easymenu compatiblemenu definition. This will be stuck in the middle of speedbar's menu.The third parameter is the variable name containing the keymap wediscussed earlier.The last parameter is a function which draws buttons for your mode.This function must take two parameters. The directory currently beingdisplayed, and the depth at which you should start rendering buttons.The function will then draw (starting at the current cursor position)any buttons deemed necessary based on the input parameters.@xref{Creating a display}.Next, you need to register function overrides. This may look somethinglike this:@example(speedbar-add-mode-functions-list '("MYEXTENSION" (speedbar-item-info . MyExtension-speedbar-item-info) (speedbar-line-path . MyExtension-speedbar-line-path)))@end exampleThe first element in the list is the name of you extension. The secondis an alist of functions to overload. The function to overload isfirst, followed by what you want called instead.For @code{speedbar-line-path} your function should take an optional DEPTHparameter. This is the starting depth for heavily indented lines. Ifit is not provided, you can derive it like this:@example(save-match-data (if (not depth) (progn (beginning-of-line) (looking-at "^\\([0-9]+\\):") (setq depth (string-to-int (match-string 1)))))@end example@noindentwhere the depth is stored as invisible text at the beginning of eachline.The path returned should be the full path name of the file associatedwith that line. If the cursor is on a tag, then the file containingthat tag should be returned. This is critical for built in file basedfunctions to work (meaning less code for you to write). If your displaydoes not deal in files, you do not need to overload this function.@cindex @code{speedbar-item-info}The function @code{speedbar-item-info}, however, is very likely to needoverloading. This function takes no parameters and must derive a textsummary to display in the minibuffer.There are several helper functions you can use if you are going to usebuilt in tagging. These functions can be @code{or}ed since each onereturns non-nil if it displays a message. They are:@table @code@cindex @code{speedbar-item-info-file-helper}@item speedbar-item-info-file-helperThis takes an optional @var{filename} parameter. You can derive your ownfilename, or it will derive it using a (possibly overloaded) function@code{speedbar-line-file}. It shows details about a file.@cindex @code{speedbar-item-info-tag-helper}@item speedbar-item-info-tag-helperIf the current line is a tag, then display information about that tag,such as its parent file, and location.@end tableYour custom function might look like this:@example(defun MyExtension-item-info () "Display information about the current line." (or (speedbar-item-info-tag-helper) (message "Interesting detail.")))@end exampleOnce you have done all this, speedbar will show an entry in the@samp{Displays} menu declaring that your extension is available.@node Tagging Extentions, Creating a display, Major Display Modes, Extending@section Tagging ExtentionsIt is possible to create new methods for tagging files in speedbar.To do this, you need two basic functions, one function to fetch thetags from a buffer, the other to insert them below the filename.@defun my-fetch-dynamic-tags fileParse @var{file} for a list of tags. Return the list, or @code{t} if there wasan error.@end defunThe non-error return value can be anything, as long as it can beinserted by it's paired function:@defun my-insert-tag-list level lstInsert a list of tags @var{lst} started at indentation level@var{level}. Creates buttons for each tag, and provides any otherdisplay information requried.@end defun@cindex @code{speedbar-create-tag-hierarchy}It is often useful to use @code{speedbar-create-tag-hierarchy} on yourtoken list. See that function's documentation for details on what itrequires.@cindex @code{speedbar-dynamic-tags-function-list}Once these two functions are written, modify the variable@code{speedbar-dynamic-tags-function-list} to include your parser at thebeginning, like this:@example(add-to-list 'speedbar-dynamic-tags-function-list '(my-fetch-dynamic-tags . my-insert-tag-list))@end exampleIf your parser is only good for a few types of files, make sure that itis either a buffer local modification, or that the tag generator returns@code{t} for non valid buffers.@node Creating a display, , Tagging Extentions, Extending@section Creating a display@cindex creating a displayRendering a display in speedbar is completely flexible. When yourbutton function is called, see @ref{Minor Display Modes}, and @ref{MajorDisplay Modes}, you have control to @code{insert} anything you want.The conventions allow almost anything to be inserted, but several helperfunctions are provided to make it easy to create the standardizedbuttons.To understand the built in functions, each "button" in speedbar consistsof four important pieces of data. The text to be displayed, tokendata to be associated with the text, a function to call, and some face todisplay it in.When a function is provided, then that text becomes mouse activated,meaning the mouse will highlight the text.Additionally, for data which can form deep trees, each line is given adepth which indicates how far down the tree it is. This information isstored in invisible text at the beginning of each line, and is used bythe navigation commands.@defun speedbar-insert-button text face mouse function &optional token prevlineThis function inserts one button into the current location.@var{text} is the text to insert. @var{face} is the face in which itwill be displayed. @var{mouse} is the face to display over the textwhen the mouse passes over it. @var{function} is called whenever theuser clicks on the text.The optional argument @var{token} is extra data to associated with thetext. Lastly @var{prevline} should be non-nil if you want this line toappear directly after the last button which was created instead of onthe next line.@end defun@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 depthCreate a tag line with @var{exp-button-type} for the small expansionbutton. This is the button that expands or contracts a node (ifapplicable), and @var{exp-button-char} the character in it (@samp{+},@samp{-}, @samp{?},etc). @var{exp-button-function} is the function to call if it's clickedon. Button types are @code{'bracket}, @code{'angle}, @code{'curly},@code{'expandtag}, @code{'statictag}, or nil. @var{exp-button-data} isextra data attached to the text forming the expansion button.Next, @var{tag-button} is the text of the tag.@var{tag-button-function} is the function to call if clicked on, and@var{tag-button-data} is the data to attach to the text field (such atag positioning, etc). @var{tag-button-face} is a face used for thistype of tag.Lastly, @var{depth} shows the depth of expansion.This function assumes that the cursor is in the speedbar window at theposition to insert a new item, and that the new item will end with a CR@end defun@defun speedbar-insert-generic-list level list expand-fun find-funAt @var{level}, (the current indentation level desired) insert a genericmulti-level alist @var{list}. Associations with lists get @samp{@{+@}}tags (to expand into more nodes) and those with positions or other datajust get a @samp{>} as the indicator. @samp{@{+@}} buttons will have thefunction @var{expand-fun} and the token is the @code{cdr} list. Thetoken name will have the function @var{find-fun} and not token.Each element of the list can have one of these forms:@table @code@item (@var{name} . marker-or-number)One tag at this level.@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... )One group of tags.@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... )One Group of tags where the group has a starting position.@end tableWhen you use @code{speedbar-insert-generic-list}, there are somevariables you can set buffer-locally to change the behavior. The mostobvious is @code{speedbar-tag-hierarchy-method}.@xref{Tag Hierarchy Methods}.@defvar speedbar-generic-list-group-expand-button-typeThis is the button type used for groups of tags, whether expandedor added in via a hierarchy method. Two good values are@code{'curly} and @code{'expandtag}. Curly is the default button, and@code{'expandtag} is useful if the groups also has a position.@end defvar@defvar speedbar-generic-list-tag-button-typeThis is the button type used for a single tag.Two good values are @code{nil} and @code{'statictag}.@code{nil} is the default, and @code{'statictag} has the same width as@code{'expandtag}.@end defvar@end defun@node Index, , Extending, Top@comment node-name, next, previous, up@unnumbered Concept Index@printindex cp@bye@c LocalWords: speedbar's xref Keybindings slowbar kbd subsubsection@c LocalWords: keybindings