1 ;;; eieio-speedbar.el -- Classes for managing speedbar displays.
4 ;; Copyright (C) 1999, 2000, 2001, 2002, 2005, 2007 Eric M. Ludlam
6 ;; Author: <zappo@gnu.org>
7 ;; RCS: $Id: eieio-speedbar.el,v 1.4 2007-11-26 15:01:05 michaels Exp $
8 ;; Keywords: oop, tools
10 ;; This program is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; This program is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
23 ;; Boston, MA 02110-1301, USA.
25 ;; Please send bug reports, etc. to zappo@gnu.org
29 ;; This provides some classes that can be used as a parent which
30 ;; will automatically provide SPEEDBAR support for any list of objects
33 ;; This file requires speedbar version 0.10 or later.
35 ;;; Creating a new speedbar mode based on a pre-existing object hierarchy
37 ;; To create a new speedbar mode based on lists of objects is easier
38 ;; than creating a whole new speedbar mode from scratch.
40 ;; 1) Objects that will have lists of items that can be expanded
41 ;; should also inherit from the classes:
42 ;; * `eieio-speedbar' - specify your own button behavior
43 ;; * `eieio-speedbar-directory-button' - objects that behave like directories
44 ;; * `eieio-speedbar-file-button' - objects that behave like files
46 ;; 2) Objects that have lists of children should implement the method
47 ;; `eieio-speedbar-object-children' which returns a list of more
48 ;; objects, or a list of strings.
50 ;; 3) Objects that return a list of strings should also implement these
52 ;; * `eieio-speedbar-child-make-tag-lines' - make tag lines for a child.
53 ;; * `eieio-speedbar-child-description' - describe non-object children
55 ;; 4) Objects which have expanded information should implement the method
56 ;; `eieio-speedbar-description' to produce more information.
58 ;; 5) Objects that are associated with a directory should implement
59 ;; the method `eieio-speedbar-derive-line-path' which returns a
62 ;; 6) Objects that have a specialized behavior when clicked should
63 ;; define the method `eieio-speedbar-handle-click'.
65 ;; To initialize a new eieio based speedbar display, do the following.
67 ;; 1) Create a keymap variable `foo-speedbar-key-map'.
68 ;; This keymap variable should be initialized in a function.
69 ;; If you have no special needs, use `eieio-speedbar-key-map'
71 ;; 2) Create a variable containing an easymenu definition compatible
72 ;; with speedbar. if you have no special needs, use
73 ;; `eieio-speedbar-menu'.
75 ;; 3) Create a function which returns the top-level list of children
76 ;; objects to be displayed in speedbar.
78 ;; 4) Call `eieio-speedbar-create' as specified in it's documentation
79 ;; string. This will automatically handle cases when speedbar is
80 ;; not already loaded, and specifying all overload functions.
82 ;; 5) Create an initliazer function which looks like this:
84 ;; (defun my-speedbar-mode-initilaize ()
87 ;; (speedbar-frame-mode 1)
88 ;; (speedbar-change-initial-expansion-list mymodename)
89 ;; (speedbar-get-focus))
91 ;; where `mymodename' is the same value as passed to `eieio-speedbar-create'
92 ;; as the MODENAME parameter.
96 (require 'eieio-custom)
99 ;;; Support a way of adding generic object based modes into speedbar.
101 (defun eieio-speedbar-make-map ()
102 "Make the generic object based speedbar keymap."
103 (let ((map (speedbar-make-specialized-keymap)))
105 ;; General viewing things
106 (define-key map "\C-m" 'speedbar-edit-line)
107 (define-key map "+" 'speedbar-expand-line)
108 (define-key map "=" 'speedbar-expand-line)
109 (define-key map "-" 'speedbar-contract-line)
111 ;; Some object based things
112 (define-key map "C" 'eieio-speedbar-customize-line)
115 (defvar eieio-speedbar-key-map (eieio-speedbar-make-map)
116 "A Generic object based speedbar display keymap.")
118 (defvar eieio-speedbar-menu
119 '([ "Edit Object/Field" speedbar-edit-line t]
120 [ "Expand Object" speedbar-expand-line
121 (save-excursion (beginning-of-line)
122 (looking-at "[0-9]+: *.\\+. "))]
123 [ "Contract Object" speedbar-contract-line
124 (save-excursion (beginning-of-line)
125 (looking-at "[0-9]+: *.-. "))]
127 [ "Customize Object" eieio-speedbar-customize-line
128 (object-p (speedbar-line-token)) ]
130 "Menu part in easymenu format used in speedbar while browsing objects.")
132 ;; Note to self: Fix this silly thing!
133 (defalias 'eieio-speedbar-customize-line 'speedbar-edit-line)
135 (defun eieio-speedbar-create (map-fn map-var menu-var modename fetcher)
136 "Create a speedbar mode for displaying an object hierarchy.
137 MAP-FN is the keymap generator function used for extra keys.
138 MAP-VAR is the keymap variable used.
139 MENU-VAR is the symbol containting an easymenu compatible menu part to use.
140 MODENAME is a s tring used to identify this browser mode.
141 FETCHER is a generic function used to fetch the base object list used when
142 creating the speedbar display."
143 (if (not (featurep 'speedbar))
144 (add-hook 'speedbar-load-hook
146 (list 'eieio-speedbar-create-engine
147 map-fn map-var menu-var modename fetcher)))
148 (eieio-speedbar-create-engine map-fn map-var menu-var modename fetcher)))
150 (defun eieio-speedbar-create-engine (map-fn map-var menu-var modename fetcher)
151 "Create a speedbar mode for displaying an object hierarchy.
152 Called from `eieio-speedbar-create', or the speedbar load-hook.
153 MAP-FN, MAP-VAR, MENU-VAR, MODENAME, and FETCHER are the same as
154 `eieio-speedbar-create'."
155 ;; make sure the keymap exists
157 ;; Add to the expansion list.
158 (speedbar-add-expansion-list
162 (list 'lambda '(dir depth)
163 (list 'eieio-speedbar-buttons 'dir 'depth
164 (list 'quote fetcher)))))
165 ;; Set the special functions.
166 (speedbar-add-mode-functions-list
168 '(speedbar-item-info . eieio-speedbar-item-info)
169 '(speedbar-line-directory . eieio-speedbar-line-path))))
171 (defun eieio-speedbar-buttons (dir-or-object depth fetcher)
172 "Create buttons for the speedbar display.
173 Start in directory DIR-OR-OBJECT. If it is an object, just display that
175 Argument DEPTH specifies how far down we have already been displayed.
176 If it is a directory, use FETCHER to fetch all objects associated with
178 (let ((objlst (cond ((object-p dir-or-object)
179 (list dir-or-object))
180 ((stringp dir-or-object)
181 (funcall fetcher dir-or-object))
184 (speedbar-make-tag-line nil nil nil nil "Empty display" nil nil nil
186 ;; Dump all objects into speedbar
188 (eieio-speedbar-make-tag-line (car objlst) depth)
189 (setq objlst (cdr objlst))))))
192 ;;; DEFAULT SUPERCLASS baseline methods
194 ;; First, define methods onto the superclass so all classes
195 ;; will have some minor support.
197 (defmethod eieio-speedbar-description ((object eieio-default-superclass))
198 "Return a string describing OBJECT."
199 (object-name-string object))
201 (defmethod eieio-speedbar-derive-line-path ((object eieio-default-superclass))
202 "Return the path which OBJECT has something to do with."
205 (defmethod eieio-speedbar-object-buttonname ((object eieio-default-superclass))
206 "Return a string to use as a speedbar button for OBJECT."
207 (object-name-string object))
209 (defmethod eieio-speedbar-make-tag-line ((object eieio-default-superclass)
211 "Insert a tag line into speedbar at point for OBJECT.
212 By default, all objects appear as simple TAGS with no need to inherit from
213 the special `eieio-speedbar' classes. Child classes should redefine this
214 method to create more accurate tag lines.
215 Argument DEPTH is the depth at which the tag line is inserted."
216 (speedbar-make-tag-line nil nil nil nil
217 (eieio-speedbar-object-buttonname object)
218 'eieio-speedbar-object-click
223 (defmethod eieio-speedbar-handle-click ((object eieio-default-superclass))
224 "Handle a click action on OBJECT in speedbar.
225 Any object can be represented as a tag in SPEEDBAR without special
226 attributes. These default objects will be pulled up in a custom
227 object edit buffer doing an in-place edit.
229 If your object represents some other item, override this method
230 and take the apropriate action."
231 (require 'eieio-custom)
232 (speedbar-with-attached-buffer
233 (eieio-customize-object object))
234 (speedbar-maybee-jump-to-attached-frame))
237 ;;; Class definitions
239 ;; Now define a special speedbar class with some
240 ;; variables with :allocation class which can be attached into
241 ;; object hierarchies.
243 ;; These more complex types are for objects which wish to display
244 ;; lists of children buttons.
246 (defclass eieio-speedbar nil
247 ((buttontype :initform nil
250 "The type of expansion button used for objects of this class.
251 Possible values are those symbols supported by the `exp-button-type' argument
252 to `speedbar-make-tag-line'."
254 (buttonface :initform speedbar-tag-face
255 :type (or symbol face)
257 "The face used on the textual part of the button for this class.
258 See `speedbar-make-tag-line' for details."
260 (expanded :initform nil
263 "State of an object being expanded in speedbar.")
265 "Class which provides basic speedbar support for child classes.
266 Add one of thie child classes to this class to the parent list of a class."
269 (defclass eieio-speedbar-directory-button (eieio-speedbar)
270 ((buttontype :initform angle)
271 (buttonface :initform speedbar-directory-face))
272 "Class providing support for objects which behave like a directory."
275 (defclass eieio-speedbar-file-button (eieio-speedbar)
276 ((buttontype :initform bracket)
277 (buttonface :initform speedbar-file-face))
278 "Class providing support for objects which behave like a directory."
282 ;;; Methods to eieio-speedbar-* which do not need to be overriden
284 (defmethod eieio-speedbar-make-tag-line ((object eieio-speedbar)
286 "Insert a tag line into speedbar at point for OBJECT.
287 All objects a child of symbol `eieio-speedbar' can be created from this
288 method. Override this if you need non-traditional tag lines.
289 Argument DEPTH is the depth at which the tag line is inserted."
290 (let ((children (eieio-speedbar-object-children object))
291 (exp (oref object expanded)))
293 (if (eq (oref object buttontype) 'expandtag)
294 (speedbar-make-tag-line 'statictag
296 (eieio-speedbar-object-buttonname object)
297 'eieio-speedbar-object-click
299 (oref object buttonface)
301 (speedbar-make-tag-line (oref object buttontype)
303 (eieio-speedbar-object-buttonname object)
304 'eieio-speedbar-object-click
306 (oref object buttonface)
308 (speedbar-make-tag-line (oref object buttontype)
310 'eieio-speedbar-object-expand
312 (eieio-speedbar-object-buttonname object)
313 'eieio-speedbar-object-click
315 (oref object buttonface)
318 (eieio-speedbar-expand object (1+ depth))))))
320 (defmethod eieio-speedbar-child-make-tag-lines ((object eieio-speedbar) depth)
321 "Base method for creating tag lines for non-object children."
322 (error "You must implement `eieio-speedbar-child-make-tag-lines' for %s"
323 (object-name object)))
325 (defmethod eieio-speedbar-expand ((object eieio-speedbar) depth)
326 "Expand OBJECT at indentation DEPTH.
327 Inserts a list of new tag lines representing expanded elements withing
329 (let ((children (eieio-speedbar-object-children object)))
330 (cond ((object-p (car children))
331 (mapcar (lambda (car)
332 (eieio-speedbar-make-tag-line car depth))
334 (children (eieio-speedbar-child-make-tag-lines object depth)))))
337 ;;; Speedbar specific function callbacks.
339 (defun eieio-speedbar-object-click (text token indent)
340 "Handle a user click on TEXT representing object TOKEN.
341 The object is at indentation level INDENT."
342 (eieio-speedbar-handle-click token))
344 (defun eieio-speedbar-object-expand (text token indent)
345 "Expand object represented by TEXT. TOKEN is the object.
346 INDENT is the current indentation level."
347 (cond ((string-match "+" text) ;we have to expand this file
348 (speedbar-change-expand-button-char ?-)
349 (oset token expanded t)
350 (speedbar-with-writable
352 (end-of-line) (forward-char 1)
353 (eieio-speedbar-expand token (1+ indent)))))
354 ((string-match "-" text) ;we have to contract this node
355 (speedbar-change-expand-button-char ?+)
356 (oset token expanded nil)
357 (speedbar-delete-subblock indent))
358 (t (error "Ooops... not sure what to do")))
359 (speedbar-center-buffer-smartly))
361 (defmethod eieio-speedbar-child-description ((obj eieio-speedbar))
362 "Return a description for a child of OBJ which is not an object."
363 (error "You must implement `eieio-speedbar-child-description' for %s"
366 (defun eieio-speedbar-item-info ()
367 "Display info for the current line when in EDE display mode."
368 ;; Switch across the types of the tokens.
369 (let ((tok (speedbar-line-token)))
370 (cond ((object-p tok)
371 (message (eieio-speedbar-description tok)))
373 (let ((no (eieio-speedbar-find-nearest-object)))
375 (eieio-speedbar-child-description no)))))))
377 (defun eieio-speedbar-find-nearest-object (&optional depth)
378 "Search backwards to the first line associated with an object.
379 Optional argument DEPTH is the current depth of the search."
384 (when (looking-at "^\\([0-9]+\\):")
385 (setq depth (string-to-number (match-string 1))))))
387 (while (and (not (object-p (speedbar-line-token)))
389 (setq depth (1- depth))
390 (re-search-backward (format "^%d:" depth) nil t))
391 (speedbar-line-token))))
393 (defun eieio-speedbar-line-path (&optional depth)
394 "If applicable, return the path to the file the cursor is on.
395 Optional DEPTH is the depth we start at."
400 (looking-at "^\\([0-9]+\\):")
401 (setq depth (string-to-number (match-string 1)))))
402 ;; This whole function is presently bogus. Make it better later.
403 (let ((tok (eieio-speedbar-find-nearest-object depth)))
405 (eieio-speedbar-derive-line-path tok)
406 default-directory))))
409 ;;; Methods to the eieio-speedbar-* classes which need to be overriden.
411 (defmethod eieio-speedbar-object-children ((object eieio-speedbar))
412 "Return a list of children to be displayed in SPEEDBAR.
413 If the return value is a list of OBJECTs, then those objects are
414 queried for details. If the return list is made of strings,
415 then this object will be queried for the details needed
416 to create a speedbar button."
419 (provide 'eieio-speedbar)
421 ;;; eieio-speedbar.el ends here