-
-;;; Change log:
-;; 0.1 Initial Revision
-;; 0.2 Fixed problem with x-pointer-shape causing future frames not
-;; to be created.
-;; Fixed annoying habit of `speedbar-update-contents' to make
-;; it possible to accidentally kill the speedbar buffer.
-;; Clicking directory names now only changes the contents of
-;; the speedbar, and does not cause a dired mode to appear.
-;; Clicking the <+> next to the directory does cause dired to
-;; be run.
-;; Added XEmacs support, which means timer support moved to a
-;; platform independant call.
-;; Added imenu support. Now modes are supported by imenu
-;; first, and etags only if the imenu call doesn't work.
-;; Imenu is a little faster than etags, and is more emacs
-;; friendly.
-;; Added more user control variables described in the commentary.
-;; Added smart recentering when nodes are opened and closed.
-;; 0.3 x-pointer-shape fixed for emacs 19.35, so I put that check in.
-;; Added invisible codes to the beginning of each line.
-;; Added list aproach to node expansion for easier addition of new
-;; types of things to expand by
-;; Added multi-level path name support
-;; Added multi-level tag name support.
-;; Only mouse-2 is now used for node expansion
-;; Added keys e + - to edit expand, and contract node lines
-;; Added longer legal file regexp for all those modes which support
-;; imenu. (pascal, fortran90, ada, pearl)
-;; Added pascal support to etags from Dave Penkler <dave_penkler@grenoble.hp.com>
-;; Fixed centering algorithm
-;; Tried to choose background independent colors. Made more robust.
-;; Rearranged code into a more logical order
-;; 0.3.1 Fixed doc & broken keybindings
-;; Added mode hooks.
-;; Improved color selection to be background mode smart
-;; `nil' passed to `speedbar-frame-mode' now toggles the frame as
-;; advertised in the doc string
-;; 0.4a Added modified patch from Dan Schmidt <dfan@lglass.com> allowing a
-;; directory cache to be maintained speeding up revisiting of files.
-;; Default raise-lower behavior is now off by default.
-;; Added some menu items for edit expand and contract.
-;; Pre 19.31 emacsen can run without idle timers.
-;; Added some patch information from Farzin Guilak <farzin@protocol.com>
-;; adding xemacs specifics, and some etags upgrades.
-;; Added ability to set a faces symbol-value to a string
-;; representing the desired foreground color. (idea from
-;; Farzin Guilak, but implemented differently)
-;; Fixed problem with 1 character buttons.
-;; Added support for new Imenu marker technique.
-;; Added `speedbar-load-hooks' for things to run only once on
-;; load such as updating one of the many lists.
-;; Added `speedbar-supported-extension-expressions' which is a
-;; list of extensions that speedbar will tag. This variable
-;; should only be updated with `speedbar-add-supported-extension'
-;; Moved configure dialog support to a separate file so
-;; speedbar is not dependant on eieio to run
-;; Fixed list-contraction problem when the item was at the end
-;; of a sublist.
-;; Fixed XEmacs multi-frame timer selecting bug problem.
-;; Added `speedbar-ignored-modes' which is a list of major modes
-;; speedbar will not follow when it is displayed in the selected frame
-;; 0.4 When the file being edited is not in the list, and is a file
-;; that should be in the list, the speedbar cache is replaced.
-;; Temp buffers are now shown in the attached frame not the
-;; speedbar frame
-;; New variables `speedbar-vc-*' and `speedbar-stealthy-function-list'
-;; added. `speedbar-update-current-file' is now a member of
-;; the stealthy list. New function `speedbar-check-vc' will
-;; examine each file and mark it if it is checked out. To
-;; add new version control types, override the function
-;; `speedbar-this-file-in-vc' and `speedbar-vc-check-dir-p'.
-;; The stealth list is interruptible so that long operations
-;; do not interrupt someones editing flow. Other long
-;; speedbar updates will be added to the stealthy list in the
-;; future should interesting ones be needed.
-;; Added many new functions including:
-;; `speedbar-item-byte-compile' `speedbar-item-load'
-;; `speedbar-item-copy' `speedbar-item-rename' `speedbar-item-delete'
-;; and `speedbar-item-info'
-;; If the user kills the speedbar buffer in some way, the frame will
-;; be removed.
-;; 0.4.1 Bug fixes
-;; <mark.jeffries@nomura.co.uk> added `speedbar-update-flag',
-;; XEmacs fixes for menus, and tag sorting, and quit key.
-;; Modeline now updates itself based on window-width.
-;; Frame is cached when closed to make pulling it up again faster.
-;; Speedbars window is now marked as dedicated.
-;; Added bindings: <grossjoh@charly.informatik.uni-dortmund.de>
-;; Long directories are now span multiple lines autmoatically
-;; Added `speedbar-directory-button-trim-method' to specify how to
-;; sorten the directory button to fit on the screen.
-;; 0.4.2 Add one level of full-text cache.
-;; Add `speedbar-get-focus' to switchto/raise the speedbar frame.
-;; Editing thing-on-line will auto-raise the attached frame.
-;; Bound `U' to `speedbar-up-directory' command.
-;; Refresh will now maintain all subdirectories that were open
-;; when the refresh was requested. (This does not include the
-;; tags, only the directories)
-;; 0.4.3 Bug fixes
-;; 0.4.4 Added `speedbar-ignored-path-expressions' and friends.
-;; Configuration menu items not displayed if dialog-mode not present
-;; Speedbar buffer now starts with a space, and is not deleted
-;; ewhen the speedbar frame is closed. This prevents the invisible
-;; frame from preventing buffer switches with other buffers.
-;; Fixed very bad bug in the -add-[extension|path] functions.
-;; Added `speedbar-find-file-in-frame' which will always pop up a frame
-;; that is already display a buffer selected in the speedbar buffer.
-;; Added S-mouse2 as "power click" for always poping up a new frame.
-;; and always rescanning with imenu (ditching the imenu cache), and
-;; always rescanning directories.
-;; 0.4.5 XEmacs bugfixes and enhancements.
-;; Window Title simplified.
-;; 0.4.6 Fixed problems w/ dedicated minibuffer frame.
-;; Fixed errors reported by checkdoc.
-;; 0.5 Mode-specific contents added. Controlled w/ the variable
-;; `speedbar-mode-specific-contents-flag'. See speedbspec
-;; for info on enabling this feature.
-;; `speedbar-load-hook' name change and pointer check against
-;; major-mode. Suggested by Sam Steingold <sds@ptc.com>
-;; Quit auto-selects the attached frame.
-;; Ranamed `speedbar-do-updates' to `speedbar-update-flag'
-;; Passes checkdoc.
-;; 0.5.1 Advice from ptype@dra.hmg.gb:
-;; Use `post-command-idle-hook' in older emacsen
-;; `speedbar-sort-tags' now works with imenu.
-;; Unknown files (marked w/ ?) can now be operated on w/
-;; file commands.
-;; `speedbar-vc-*-hook's for easilly adding new version control systems.
-;; Checkin/out w/ vc will reset the scanners and update the * marker.
-;; Fixed ange-ftp require compile time problem.
-;; Fixed XEmacs menu bar bug.
-;; Added `speedbar-activity-change-focus-flag' to control if the
-;; focus changes w/ mouse events.
-;; Added `speedbar-sort-tags' toggle to the menubar.
-;; Added `speedbar-smart-directory-expand-flag' to toggle how
-;; new directories might be inserted into the speedbar hierarchy.
-;; Added `speedbar-visiting-[tag|file]hook' which is called whenever
-;; speedbar pulls up a file or tag in the attached frame. Setting
-;; this to `reposition-window' will do nice things to function tags.
-;; Fixed text-cache default-directory bug.
-;; Emacs 20 char= support.
-;; 0.5.2 Customization
-;; For older emacsen, you will need to download the new defcustom
-;; package to get nice faces for speedbar
-;; mouse1 Double-click is now the same as middle click.
-;; No mouse pointer shape stuff for XEmacs (is there any?)
-;; 0.5.3 Regressive support for non-custom enabled emacsen.
-;; Fixed serious problem w/ 0.5.2 and ignored paths.
-;; `condition-case' no longer used in timer fcn.
-;; `speedbar-edit-line' is now smarter w/ special modes.
-;; 0.5.4 Fixed more problems for Emacs 20 so speedbar loads correctly.
-;; Updated some documentation strings.
-;; Added customization menu item, and customized some more variables.
-;; 0.5.5 Fixed so that there can be no ignored paths
-;; Added .l & .lsp as lisp, suggested by: sshteingold@cctrading.com
-;; You can now adjust height in `speedbar-frame-parameters'
-;; XEmacs fix for use of `local-variable-p'
-;; 0.5.6 Folded in XEmacs suggestions from Hrvoje Niksic <hniksic@srce.hr>
-;; Several custom changes (group definitions, trim-method & others)
-;; Keymap changes, and ways to add menu items.
-;; Timer use changes for XEmacs 20.4
-;; Regular expression enhancements.
-;; 0.6 Fixed up some frame definition stuff, use more convenience fns.
-;; Rehashed frame creation code for better compatibility.
-;; Fixed setting of kill-buffer hook.
-;; Default speedbar has no menubar, mouse-3 is popup menu,
-;; XEmacs double-click capability (Hrvoje Niksic <hniksic@srce.hr>)
-;; General documentation fixup.
-;; 0.6.1 Fixed button-3 menu for Emacs 20.
-;; 0.6.2 Added autoload tag to `speedbar-get-focus'
+;; Speedbar can be configured to create a special display for certain
+;; modes that do not display tradition file/tag data. Rmail, Info,
+;; and the debugger are examples. These modes can, however, benefit
+;; from a speedbar style display in their own way.
+;;
+;; If your `major-mode' is `foo-mode', the only requirement is to
+;; create a function called `foo-speedbar-buttons' which takes one
+;; argument, BUFFER. BUFFER will be the buffer speedbar wants filled.
+;; In `foo-speedbar-buttons' there are several functions that make
+;; building a speedbar display easy. See the documentation for
+;; `speedbar-with-writable' (needed because the buffer is usually
+;; read-only) `speedbar-make-tag-line', `speedbar-insert-button', and
+;; `speedbar-insert-generic-list'. If you use
+;; `speedbar-insert-generic-list', also read the doc for
+;; `speedbar-tag-hierarchy-method' in case you wish to override it.
+;; The function `speedbar-with-attached-buffer' brings you back to the
+;; buffer speedbar is displaying for.
+;;
+;; For those functions that make buttons, the "function" should be a
+;; symbol that is the function to call when clicked on. The "token"
+;; is extra data you can pass along. The "function" must take three
+;; parameters. They are (TEXT TOKEN INDENT). TEXT is the text of the
+;; button clicked on. TOKEN is the data passed in when you create the
+;; button. INDENT is an indentation level, or 0. You can store
+;; indentation levels with `speedbar-make-tag-line' which creates a
+;; line with an expander (eg. [+]) and a text button.
+;;
+;; Some useful functions when writing expand functions, and click
+;; functions are `speedbar-change-expand-button-char',
+;; `speedbar-delete-subblock', and `speedbar-center-buffer-smartly'.
+;; The variable `speedbar-power-click' is set to t in your functions
+;; when the user shift-clicks. This indications anything from
+;; refreshing cached data to making a buffer appear in a new frame.
+;;
+;; If you wish to add to the default speedbar menu for the case of
+;; `foo-mode', create a variable `foo-speedbar-menu-items'. This
+;; should be a list compatible with the `easymenu' package. It will
+;; be spliced into the main menu. (Available with click-mouse-3). If
+;; you wish to have extra key bindings in your special mode, create a
+;; variable `foo-speedbar-key-map'. Instead of using `make-keymap',
+;; or `make-sparse-keymap', use the function
+;; `speedbar-make-specialized-keymap'. This lets you inherit all of
+;; speedbar's default bindings with low overhead.
+;;
+;; Adding a speedbar top-level display mode:
+;;
+;; Unlike the specialized modes, there are no name requirements,
+;; however the methods for writing a button display, menu, and keymap
+;; are the same. Once you create these items, you can call the
+;; function `speedbar-add-expansion-list'. It takes one parameter
+;; which is a list element of the form (NAME MENU KEYMAP &rest
+;; BUTTON-FUNCTIONS). NAME is a string that will show up in the
+;; Displays menu item. MENU is a symbol containing the menu items to
+;; splice in. KEYMAP is a symbol holding the keymap to use, and
+;; BUTTON-FUNCTIONS are the function names to call, in order, to create
+;; the display.