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