GNU Info

(speedbar)Creating a display

---

Prev: Tagging Extensions Up: Extending

---

Enter node , (file) or (file)node

Creating a display
==================

   Rendering a display in speedbar is completely flexible.  When your
button function is called, see Note: Minor Display Modes, and Note:
Major Display Modes, you have control to `insert' anything you want.

   The conventions allow almost anything to be inserted, but several
helper functions are provided to make it easy to create the standardized
buttons.

   To understand the built in functions, each `button' in speedbar
consists of four important pieces of data.  The text to be displayed,
token data to be associated with the text, a function to call, and some
face to display it in.

   When a function is provided, then that text becomes mouse activated,
meaning the mouse will highlight the text.

   Additionally, for data which can form deep trees, each line is given
a depth which indicates how far down the tree it is.  This information
is stored in invisible text at the beginning of each line, and is used
by the navigation commands.

 - Function: speedbar-insert-button text face mouse function &optional
          token prevline
     This function inserts one button into the current location.  TEXT
     is the text to insert.  FACE is the face in which it will be
     displayed.   MOUSE is the face to display over the text when the
     mouse passes over it.  FUNCTION is called whenever the user clicks
     on the text.

     The optional argument TOKEN is extra data to associated with the
     text.  Lastly PREVLINE should be non-nil if you want this line to
     appear directly after the last button which was created instead of
     on the next line.

 - Function: 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
     Create a tag line with EXP-BUTTON-TYPE for the small expansion
     button.  This is the button that expands or contracts a node (if
     applicable), and EXP-BUTTON-CHAR the character in it (`+', `-',
     `?', etc).  EXP-BUTTON-FUNCTION is the function to call if it's
     clicked on.  Button types are `'bracket', `'angle', `'curly',
     `'expandtag', `'statictag', or nil.  EXP-BUTTON-DATA is extra data
     attached to the text forming the expansion button.

     Next, TAG-BUTTON is the text of the tag.  TAG-BUTTON-FUNCTION is
     the function to call if clicked on, and TAG-BUTTON-DATA is the
     data to attach to the text field (such a tag positioning, etc).
     TAG-BUTTON-FACE is a face used for this type of tag.

     Lastly, DEPTH shows the depth of expansion.

     This function assumes that the cursor is in the speedbar window at
     the position to insert a new item, and that the new item will end
     with a CR.

 - Function: speedbar-insert-generic-list level list expand-fun find-fun
     At LEVEL, (the current indentation level desired) insert a generic
     multi-level alist LIST.  Associations with lists get `{+}' tags
     (to expand into more nodes) and those with positions or other data
     just get a `>' as the indicator.  `{+}' buttons will have the
     function EXPAND-FUN and the token is the `cdr' list.  The token
     name will have the function FIND-FUN and not token.

     Each element of the list can have one of these forms:

    `(NAME . marker-or-number)'
          One tag at this level.

    `(NAME (NAME . marker-or-number) (NAME . marker-or-number) ... )'
          One group of tags.

    `(NAME marker-or-number (NAME . marker-or-number) ... )'
          One Group of tags where the group has a starting position.

     When you use `speedbar-insert-generic-list', there are some
     variables you can set buffer-locally to change the behavior.  The
     most obvious is `speedbar-tag-hierarchy-method'.  Note: Tag
     Hierarchy Methods.

      - Variable: speedbar-generic-list-group-expand-button-type
          This is the button type used for groups of tags, whether
          expanded or added in via a hierarchy method.  Two good values
          are `'curly' and `'expandtag'.  Curly is the default button,
          and `'expandtag' is useful if the groups also has a position.

      - Variable: speedbar-generic-list-tag-button-type
          This is the button type used for a single tag.  Two good
          values are `nil' and `'statictag'.  `nil' is the default, and
          `'statictag' has the same width as `'expandtag'.