GNU Info

(speedbar)Major Display Modes

---

Next: Tagging Extensions Prev: Minor Display Modes Up: Extending

---

Enter node , (file) or (file)node

Major Display Modes
===================

   Creating a "Major Display Mode" for speedbar requires authoring a
keymap, an easy-menu segment, and writing several functions.  These
items can be given any name, and are made the same way as in a minor
display mode (Note: Minor Display Modes).  Once this is done, these
items need to be registered.

   Because this setup activity may or may not have speedbar available
when it is being loaded, it is necessary to create an install function.
This function should create and initialize the keymap, and add your
expansions into the customization tables.

   When creating the keymap, use the function
`speedbar-make-specialized-keymap' instead of other keymap making
functions.  This will provide you with the initial bindings needed.
Some common speedbar functions you might want to bind are:

`speedbar-edit-line'
     Edit the item on the current line.

`speedbar-expand-line'
     Expand the item under the cursor.  With a numeric argument
     (`C-u'), flush cached data before expanding.

`speedbar-contract-line'
     Contract the item under the cursor.

   These function require that function `speedbar-line-path' be
correctly overloaded to work.

   Next, register your extension like this;

       (speedbar-add-expansion-list '("MyExtension"
                                      MyExtension-speedbar-menu-items
                                      MyExtension-speedbar-key-map
                                      MyExtension-speedbar-buttons))

   There are no limitations to the names you use.

   The first parameter is the string representing your display mode.
The second parameter is a variable name containing an easymenu
compatible menu definition.  This will be stuck in the middle of
speedbar's menu.  The third parameter is the variable name containing
the keymap we discussed earlier.  The last parameter is a function
which draws buttons for your mode.  This function must take two
parameters.  The directory currently being displayed, and the depth at
which you should start rendering buttons.  The function will then draw
(starting at the current cursor position) any buttons deemed necessary
based on the input parameters.  Note: Creating a display.

   Next, you need to register function overrides.  This may look
something like this:

     (speedbar-add-mode-functions-list
      '("MYEXTENSION"
        (speedbar-item-info . MyExtension-speedbar-item-info)
        (speedbar-line-path . MyExtension-speedbar-line-path)))

   The first element in the list is the name of you extension.  The
second is an alist of functions to overload.  The function to overload
is first, followed by what you want called instead.

   For `speedbar-line-path' your function should take an optional DEPTH
parameter.  This is the starting depth for heavily indented lines.  If
it is not provided, you can derive it like this:

     (save-match-data
       (if (not depth)
           (progn
             (beginning-of-line)
             (looking-at "^\\([0-9]+\\):")
             (setq depth (string-to-int (match-string 1)))))

where the depth is stored as invisible text at the beginning of each
line.

   The path returned should be the full path name of the file associated
with that line.  If the cursor is on a tag, then the file containing
that tag should be returned.  This is critical for built in file based
functions to work (meaning less code for you to write).  If your display
does not deal in files, you do not need to overload this function.

   The function `speedbar-item-info', however, is very likely to need
overloading.  This function takes no parameters and must derive a text
summary to display in the minibuffer.

   There are several helper functions you can use if you are going to
use built in tagging.  These functions can be `or'ed since each one
returns non-nil if it displays a message.  They are:

`speedbar-item-info-file-helper'
     This takes an optional FILENAME parameter.  You can derive your own
     filename, or it will derive it using a (possibly overloaded)
     function `speedbar-line-file'.  It shows details about a file.

`speedbar-item-info-tag-helper'
     If the current line is a tag, then display information about that
     tag, such as its parent file, and location.

   Your custom function might look like this:

     (defun MyExtension-item-info ()
       "Display information about the current line."
       (or (speedbar-item-info-tag-helper)
           (message "Interesting detail.")))

   Once you have done all this, speedbar will show an entry in the
`Displays' menu declaring that your extension is available.