comparison man/speedbar.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

\input texinfo   @c -*-texinfo-*-
@c $Id: speedbar.texi,v 1.10 2002/03/16 19:33:21 eliz Exp $

@setfilename ../info/speedbar
@settitle Speedbar: File/Tag summarizing utility
@syncodeindex fn cp

@copying
Copyright @copyright{} 1999, 2000, 2002 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation

only when a buffer of the applicable type is shown.  This allows
authors of other packages to provide speedbar summaries customized to
the needs of that mode.

Throughout this manual, activities are defined as `clicking on', or
`expanding' items.  Clicking means using using @kbd{Mouse-2} on a
button.  Expanding refers to clicking on an expansion button to display
an expanded summary of the entry the expansion button is
on.  @xref{Basic Navigation}.

@menu

@node Introduction, Basic Navigation, , Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex introduction

To start using speedbar use the command @kbd{M-x speedbar RET} or select
it from the Tools menu in versions of Emacs with speedbar installed by
default.  This command will open a new frame to summarize the local
files.  On X Window systems or on MS-Windows, speedbar's frame is twenty
characters wide, and will mimic the height of the frame from which it
was started.  It positions itself to the left or right of the frame you
started it from.

To use speedbar effectively, it is important to understand its
relationship with the frame you started it from.  This frame is the
@dfn{attached frame} which speedbar will use as a reference point.  Once
started, speedbar watches the contents of this frame, and attempts to

@cindex key bindings

These key bindings are common across all modes:

@table @kbd
@item delete, SPC
@cindex scrolling in speedbar
Scroll up and down one page.
@item Q
@cindex quitting speedbar
Quit speedbar, and kill the frame.
@item q
Quit speedbar, and hide the frame.  This makes it faster to restore the

duration of the specialized buffer's use.  Minor display modes
will follow the general rules of their major counterparts in terms of
key bindings and visuals, but will have specialized behaviors.

@menu
* RMAIL::  Managing folders in speedbar
* Info::   Browsing topics in speedbar
* GDB::    Managing the current stack trace in speedbar
@end menu

@node RMAIL, Info, Minor Modes, Minor Modes
@comment  node-name,  next,  previous,  up
@section RMAIL

@comment  node-name,  next,  previous,  up
@section GDB
@cindex gdb
@cindex gud

If you are debugging an application with GDB in Emacs, speedbar can show
you the current stack when the current buffer is the @file{*gdb*}
buffer.  Usually, it will just report that there is no stack, but when
the application is stopped, the current stack will be shown.

You can click on any stack element and gdb will move to that stack
level.  You can then check variables local to that level at the GDB
prompt.

This mode has the unfortunate side-effect of breaking GDB's repeat
feature when you hit @kbd{RET} since your previous command is overridden
with a stack fetching command.

@node Customizing, Extending, Minor Modes, Top
@comment  node-name,  next,  previous,  up
@chapter Customizing
@cindex customizing

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 @code{or}ed since each one
returns non-nil if it displays a message.  They are:

@table @code
@cindex @code{speedbar-item-info-file-helper}
@item speedbar-item-info-file-helper
This takes an optional @var{filename} parameter.  You can derive your own

will be displayed.   @var{mouse} is the face to display over the text
when the mouse passes over it.  @var{function} is called whenever the
user clicks on the text.

The optional argument @var{token} is extra data to associated with the
text.  Lastly @var{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.
@end defun

@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

Create a tag line with @var{exp-button-type} for the small expansion
button.  This is the button that expands or contracts a node (if
applicable), and @var{exp-button-char} the character in it (@samp{+},
@samp{-}, @samp{?},
etc).  @var{exp-button-function} is the function to call if it's clicked
on.  Button types are @code{'bracket}, @code{'angle}, @code{'curly},
@code{'expandtag}, @code{'statictag}, or nil.  @var{exp-button-data} is
extra data attached to the text forming the expansion button.

Next, @var{tag-button} is the text of the tag.
@var{tag-button-function} is the function to call if clicked on, and
@var{tag-button-data} is the data to attach to the text field (such a
tag positioning, etc).  @var{tag-button-face} is a face used for this

@xref{Tag Hierarchy Methods}.

@defvar 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
@code{'curly} and @code{'expandtag}.  Curly is the default button, and
@code{'expandtag} is useful if the groups also has a position.
@end defvar

@defvar speedbar-generic-list-tag-button-type
This is the button type used for a single tag.
Two good values are @code{nil} and @code{'statictag}.
@code{nil} is the default, and @code{'statictag} has the same width as
@code{'expandtag}.
@end defvar

@end defun

@node Index, , Extending, Top

@printindex cp

@bye
@c  LocalWords:  speedbar's xref slowbar kbd subsubsection
@c  LocalWords:  keybindings

88155:d7ddb3e565de

\input texinfo   @c -*-texinfo-*-

@setfilename ../info/speedbar
@settitle Speedbar: File/Tag summarizing utility
@syncodeindex fn cp

@copying
Copyright @copyright{} 1999, 2000, 2002, 2003, 2004,
   2005 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation

only when a buffer of the applicable type is shown.  This allows
authors of other packages to provide speedbar summaries customized to
the needs of that mode.

Throughout this manual, activities are defined as `clicking on', or
`expanding' items.  Clicking means using @kbd{Mouse-2} on a
button.  Expanding refers to clicking on an expansion button to display
an expanded summary of the entry the expansion button is
on.  @xref{Basic Navigation}.

@menu

@node Introduction, Basic Navigation, , Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex introduction

To start using speedbar use the command @kbd{M-x speedbar RET} or
select it from the @samp{Options->Show/Hide} sub-menu.  This command
will open a new frame to summarize the local files.  On X Window
systems or on MS-Windows, speedbar's frame is twenty characters wide,
and will mimic the height of the frame from which it was started.  It
positions itself to the left or right of the frame you started it
from.

To use speedbar effectively, it is important to understand its
relationship with the frame you started it from.  This frame is the
@dfn{attached frame} which speedbar will use as a reference point.  Once
started, speedbar watches the contents of this frame, and attempts to

@cindex key bindings

These key bindings are common across all modes:

@table @kbd
@item Q
@cindex quitting speedbar
Quit speedbar, and kill the frame.
@item q
Quit speedbar, and hide the frame.  This makes it faster to restore the

duration of the specialized buffer's use.  Minor display modes
will follow the general rules of their major counterparts in terms of
key bindings and visuals, but will have specialized behaviors.

@menu
* RMAIL::  Managing folders.
* Info::   Browsing topics.
* GDB::    Watching expressions or managing the current
            stack trace.
@end menu

@node RMAIL, Info, Minor Modes, Minor Modes
@comment  node-name,  next,  previous,  up
@section RMAIL

@comment  node-name,  next,  previous,  up
@section GDB
@cindex gdb
@cindex gud

You can debug an application with GDB in Emacs using graphical mode or
text command mode (@pxref{GDB Graphical Interface,,, emacs, The
extensible self-documenting text editor}).

If you are using graphical mode you can see how selected variables
change each time your program stops (@pxref{Watch Expressions,,,
emacs, The extensible self-documenting text editor}).

If you are using text command mode, speedbar can show
you the current stack when the current buffer is the @file{*gdb*}
buffer.  Usually, it will just report that there is no stack, but when
the application is stopped, the current stack will be shown.

You can click on any stack element and gdb will move to that stack
level.  You can then check variables local to that level at the GDB
prompt.

@node Customizing, Extending, Minor Modes, Top
@comment  node-name,  next,  previous,  up
@chapter Customizing
@cindex customizing

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 @code{or}ed since each one
returns non-@code{nil} if it displays a message.  They are:

@table @code
@cindex @code{speedbar-item-info-file-helper}
@item speedbar-item-info-file-helper
This takes an optional @var{filename} parameter.  You can derive your own

will be displayed.   @var{mouse} is the face to display over the text
when the mouse passes over it.  @var{function} is called whenever the
user clicks on the text.

The optional argument @var{token} is extra data to associated with the
text.  Lastly @var{prevline} should be non-@code{nil} if you want this line to
appear directly after the last button which was created instead of on
the next line.
@end defun

@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

Create a tag line with @var{exp-button-type} for the small expansion
button.  This is the button that expands or contracts a node (if
applicable), and @var{exp-button-char} the character in it (@samp{+},
@samp{-}, @samp{?}, etc).  @var{exp-button-function} is the function
to call if it's clicked on.  Button types are @code{bracket},
@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and
@code{nil}.  @var{exp-button-data} is extra data attached to the text
forming the expansion button.

Next, @var{tag-button} is the text of the tag.
@var{tag-button-function} is the function to call if clicked on, and
@var{tag-button-data} is the data to attach to the text field (such a
tag positioning, etc).  @var{tag-button-face} is a face used for this

@xref{Tag Hierarchy Methods}.

@defvar 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
@code{curly} and @code{expandtag}.  Curly is the default button, and
@code{expandtag} is useful if the groups also has a position.
@end defvar

@defvar speedbar-generic-list-tag-button-type
This is the button type used for a single tag.
Two good values are @code{nil} and @code{statictag}.
@code{nil} is the default, and @code{statictag} has the same width as
@code{expandtag}.
@end defvar

@end defun

@node Index, , Extending, Top

@printindex cp

@bye
@c  LocalWords:  speedbar's xref slowbar kbd subsubsection
@c  LocalWords:  keybindings

@ignore
   arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02
@end ignore