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