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