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