1 ;;; foldout.el --- Folding extensions for outline-mode and outline-minor-mode.
3 ;; Copyright (C) 1994 Kevin Broadey.
5 ;; Author: Kevin Broadey <KevinB@bartley.demon.co.uk>
6 ;; Created: 27 Jan 1994
7 ;; Version: foldout.el 1.8 dated 94/03/15 at 13:30:59
8 ;; Keywords: folding, outline
11 ;; foldout|Kevin Broadey|KevinB@bartley.demon.co.uk|
12 ;; Folding editor extensions for outline-mode and outline-minor-mode|
13 ;; Date: 94/03/15|Version: 1.8|~/misc/foldout.el.Z|
15 ;; This file is not part of GNU Emacs, but it is distributed under the same
18 ;; GNU Emacs is free software; you can redistribute it and/or modify
19 ;; it under the terms of the GNU General Public License as published by
20 ;; the Free Software Foundation; either version 1, or (at your option)
23 ;; GNU Emacs is distributed in the hope that it will be useful,
24 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
25 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 ;; GNU General Public License for more details.
28 ;; You should have received a copy of the GNU General Public License
29 ;; along with GNU Emacs; see the file COPYING. If not, write to
30 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
34 ;; This file provides folding editor extensions for outline-mode and
35 ;; outline-minor-mode buffers. What's a "folding editor"? Read on...
37 ;; Imagine you're in an outline-mode buffer and you've hidden all the text and
38 ;; subheadings under your level-1 headings. You now want to look at the stuff
39 ;; hidden under one of these headings. Normally you'd do C-c C-e (show-entry)
40 ;; to expose the body or C-c C-i to expose the child (level-2) headings.
42 ;; With foldout, you do C-c C-z (foldout-zoom-subtree). This exposes the body
43 ;; and child subheadings and narrows the buffer so that only the level-1
44 ;; heading, the body and the level-2 headings are visible. If you now want to
45 ;; look under one of the level-2 headings, position the cursor on it and do C-c
46 ;; C-z again. This exposes the level-2 body and its level-3 child subheadings
47 ;; and narrows the buffer again. You can keep on zooming in on successive
48 ;; subheadings as much as you like. A string in the modeline tells you how
51 ;; When zooming in on a heading you might only want to see the child
52 ;; subheadings. You do this by specifying a numeric argument: C-u C-c C-z.
53 ;; You can specify the number of levels of children too (c.f. show-children):
54 ;; e.g. M-2 C-c C-z exposes two levels of child subheadings. Alternatively,
55 ;; you might only be interested in the body. You do this by specifying a
56 ;; negative argument: M-- C-c C-z. You can also cause the whole subtree to be
57 ;; expanded, similar to C-c C-s (show-subtree), by specifying a zero argument:
60 ;; While you're zoomed in you can still use outline-mode's exposure and hiding
61 ;; functions. It won't upset foldout at all. Also, since the buffer is
62 ;; narrowed, "global" editing actions will only affect the stuff under the
63 ;; zoomed-in heading. This is useful for restricting changes to a particular
64 ;; chapter or section of your document.
66 ;; You unzoom (exit) a fold by doing C-c C-x (foldout-exit-fold). This hides
67 ;; all the text and subheadings under the top-level heading and returns you to
68 ;; the previous view of the buffer. Specifying a numeric argument exits that
69 ;; many folds. Specifying a zero argument exits *all* folds.
71 ;; You might want to exit a fold *without* hiding the text and subheadings.
72 ;; You do this by specifying a negative argument. For example, M--2 C-c C-x
73 ;; exits two folds and leaves the text and subheadings exposed.
75 ;; Foldout also provides mouse bindings for entering and exiting folds and for
76 ;; showing and hiding text. Hold down Meta and Control, then click a mouse
77 ;; button as follows:-
79 ;; mouse-1 (foldout-mouse-zoom) zooms in on the heading clicked on:-
81 ;; single click expose body
82 ;; double click expose subheadings
83 ;; triple click expose body and subheadings
84 ;; quad click expose entire subtree
86 ;; mouse-2 (foldout-mouse-show) exposes text under the heading clicked on:-
88 ;; single click expose body
89 ;; double click expose subheadings
90 ;; triple click expose body and subheadings
91 ;; quad click expose entire subtree
93 ;; mouse-3 (foldout-mouse-hide-or-exit) hides text under the heading clicked
94 ;; on or exits the fold:-
96 ;; single click hide subtree
97 ;; double click exit fold and hide text
98 ;; triple click exit fold without hiding text
99 ;; quad click exit all folds and hide text
101 ;; You can change the modifier keys used by setting `foldout-mouse-modifiers'.
105 ;; To use foldout, put this in your .emacs:-
107 ;; (require 'foldout)
109 ;; If you don't want it loaded until you need it, try this instead:-
111 ;; (eval-after-load "outline" '(require 'foldout))
115 ;; Get out-xtra.el by Per Abrahamsen <abraham@iesd.auc.dk> for more
116 ;; outline-mode goodies. In particular, `outline-hide-sublevels' makes
117 ;; setup a lot easier.
119 ;; folding.el by Jamie Lokier <u90jl@ecs.ox.ac.uk> supports folding by
120 ;; recognising special marker text in you file.
122 ;; c-outline.el (by me) provides outline-mode support to recognise `C'
123 ;; statements as outline headings, so with foldout you can have a folding `C'
124 ;; code editor without having to put in start- and end-of-fold markers. This
130 ;; Changed meaning of prefix arg to foldout-zoom-subtree. arg > 0 now means
131 ;; "expose that many children" instead of just "expose children" so it is more
132 ;; like `show-children' (C-c C-i). Arg of C-u on its own only shows one level
133 ;; of children, though, so you can still zoom by doing C-u C-c C-z.
135 ;; I can't think of a good meaning for the value of a negative prefix. Any
138 ;; Added advertisement for my c-outline.el package. Now you can have a folding
139 ;; editor for c-mode without any effort!
142 ;; I got fed up trying to work out how many blank lines there were outside the
143 ;; narrowed region when inside a fold. Now *all* newlines before the following
144 ;; heading are *in* the narrowed region. Thus, if the cursor is at point-max,
145 ;; the number of blank lines above it is the number you'll get above the next
148 ;; Since all newlines are now inside the narrowed region, when exiting a fold
149 ;; add a newline at the end of the region if there isn't one so that the
150 ;; following heading doesn't accidentally get joined to the body text.
152 ;; Bugfix: `foldout-mouse-modifiers' should be `defvar', not `defconst'.
154 ;; Use "cond" instead of "case" so that lemacs-19.9 users can use the mouse.
156 ;; Improve "Commentary" entry on using the mouse.
158 ;; Add "Installation" keyword.
161 ;; Add mouse support functions foldout-mouse-zoom, foldout-mouse-show,
162 ;; foldout-mouse-hide-or-exit.
165 ;; Rename `foldout-enter-subtree' to `foldout-zoom-subtree' and change
166 ;; keystroke from C-g to C-z. This is more mnemonic and leaves C-g alone, as
167 ;; users expect this to cancel the current key sequence.
169 ;; Added better commentary at the request of RMS. Added stuff to comply with
170 ;; the lisp-mnt.el conventions. Added instructions on how best to load the
174 ;; Bugfix: end-of-fold marking was wrong:-
176 ;; End of narrowed region should be one character on from
177 ;; (outline-end-of-subtree) so it includes the end-of-line at the end of the
178 ;; last line of the subtree.
180 ;; End-of-fold marker should be outside the narrowed region so text inserted
181 ;; at the end of the region goes before the marker. Need to make a special
182 ;; case for end-of-buffer because it is impossible to set a marker that will
183 ;; follow eob. Bummer.
186 ;; Changed `foldout-zoom-subtree'. A zero arg now makes it expose the entire
187 ;; subtree on entering the fold. As before, < 0 shows only the body and > 0
188 ;; shows only the subheadings.
191 ;; Fixed a dumb bug - didn't make `foldout-modeline-string' buffer-local :-(
193 ;; Changed `foldout-exit-fold' to use prefix arg to say how many folds to exit.
194 ;; Negative arg means exit but don't hide text. Zero arg means exit all folds.
196 ;; Added `foldout-inhibit-key-bindings' to inhibit key bindings.
199 ;; Released to the net. Inspired by a question in gnu.emacs.help from
200 ;; Jason D Lohn <jlohn@eng.umd.edu>.
206 ;; something has gone very wrong if outline-minor-mode isn't bound now.
207 (if (not (boundp 'outline-minor-mode
))
208 (error "Can't find outline-minor-mode"))
210 (defconst foldout-fold-list nil
211 "List of start and end markers for the folds currently entered.
212 An end marker of NIL means the fold ends after (point-max).")
213 (make-variable-buffer-local 'foldout-fold-list
)
215 (defconst foldout-modeline-string nil
216 "Modeline string announcing that we are in an outline fold.")
217 (make-variable-buffer-local 'foldout-modeline-string
)
219 ;; put our minor mode string immediately following outline-minor-mode's
220 (or (assq 'foldout-modeline-string minor-mode-alist
)
221 (let ((outl-entry (memq (assq 'outline-minor-mode minor-mode-alist
)
223 (foldout-entry '((foldout-modeline-string foldout-modeline-string
))))
225 ;; something's wrong with outline if we can't find it
226 (if (null outl-entry
)
227 (error "Can't find outline-minor-mode in minor-mode-alist"))
229 ;; slip our fold announcement into the list
230 (setcdr outl-entry
(nconc foldout-entry
(cdr outl-entry
)))
234 (defun foldout-zoom-subtree (&optional exposure
)
235 "Open the subtree under the current heading and narrow to it.
237 Normally the body and the immediate subheadings are exposed, but
238 optional arg EXPOSURE \(interactively with prefix arg\) changes this:-
240 EXPOSURE > 0 exposes n levels of subheadings (c.f. show-children)
241 EXPOSURE < 0 exposes only the body
242 EXPOSURE = 0 exposes the entire subtree"
246 (outline-back-to-heading)
247 (let* ((exposure-value (prefix-numeric-value exposure
))
249 (start-marker (point-marker))
250 (end (progn (outline-end-of-subtree)
251 (skip-chars-forward "\n\^M")
253 ;; I need a marker that will follow the end of the region even when
254 ;; text is inserted right at the end. Text gets inserted *after*
255 ;; markers, so I need it at end+1. Unfortunately I can't set a
256 ;; marker at (point-max)+1, so I use NIL to mean the region ends at
258 (end-marker (if (eobp) nil
(set-marker (make-marker) (1+ end
))))
261 ;; narrow to this subtree
262 (narrow-to-region start end
)
264 ;; show the body and/or subheadings for this heading
270 ((< exposure-value
0)
274 ((> exposure-value
0)
275 (show-children exposure-value
))
280 ;; save the location of the fold we are entering
281 (setq foldout-fold-list
(cons (cons start-marker end-marker
)
284 ;; update the modeline
285 (foldout-update-modeline)
289 (defun foldout-exit-fold (&optional num-folds
)
290 "Return to the ARG'th enclosing fold view. With ARG = 0 exit all folds.
292 Normally causes exited folds to be hidden, but with ARG < 0, -ARG folds are
293 exited and text is left visible."
295 (let (start-marker end-marker
(hide-fold t
))
297 ;; check there are some folds to leave
298 (if (null foldout-fold-list
)
299 (error "Not in a fold!"))
302 ;; catch a request to leave all folds
304 (setq num-folds
(length foldout-fold-list
)))
306 ;; have we been told not to hide the fold?
309 num-folds
(- num-folds
)))
312 ;; limit the number of folds if we've been told to exit too many
313 (setq num-folds
(min num-folds
(length foldout-fold-list
)))
319 ;; get the fold at the top of the stack
320 (setq start-marker
(car (car foldout-fold-list
))
321 end-marker
(cdr (car foldout-fold-list
))
322 foldout-fold-list
(cdr foldout-fold-list
)
323 num-folds
(1- num-folds
))
325 ;; Make sure there is a newline at the end of this fold,
326 ;; otherwise the following heading will get joined to the body
330 (goto-char end-marker
)
332 (or (memq (preceding-char) '(?
\n ?\^M
))
335 ;; If this is the last fold to exit, hide the text unless we've
336 ;; been told not to. Note that at the moment point is at the
337 ;; beginning of the following heading if there is one.
339 ;; Also, make sure that the newline before the following heading
340 ;; is \n otherwise it will be hidden. If there is a newline
341 ;; before this one, make it visible too so we do the same as
342 ;; outline.el and leave a blank line before the heading.
343 (if (zerop num-folds
)
344 (let ((beginning-of-heading (point))
345 (end-of-subtree (if end-marker
348 (if (memq (preceding-char)
355 (outline-flag-region start-marker end-of-subtree ?\^M
))
357 ;; make sure the next heading is exposed
359 (outline-flag-region end-of-subtree
360 beginning-of-heading ?
\n))
363 ;; zap the markers so they don't slow down editing
364 (set-marker start-marker nil
)
365 (if end-marker
(set-marker end-marker nil
))
368 ;; have we exited enough folds?
369 until
(zerop num-folds
))
371 ;; narrow to the enclosing fold if there is one
372 (if foldout-fold-list
374 (setq start-marker
(car (car foldout-fold-list
))
375 end-marker
(cdr (car foldout-fold-list
)))
376 (narrow-to-region start-marker
378 (1- (marker-position end-marker
))
383 ;; update the modeline
384 (foldout-update-modeline)
388 (defun foldout-update-modeline ()
389 "Set the modeline string to indicate our fold depth."
390 (let ((depth (length foldout-fold-list
)))
391 (setq foldout-modeline-string
393 ;; if we're not in a fold, keep quiet
396 ;; in outline-minor-mode we're after "Outl:xx" in the modeline
398 (format ":%d" depth
))
399 ;; otherwise just announce the depth (I guess we're in outline-mode)
403 (format " Inside %d folds" depth
))
407 (defun foldout-mouse-zoom (event)
408 "Zoom in on the heading clicked on.
410 How much is exposed by the zoom depends on the number of mouse clicks:-
414 3 expose body and subheadings
415 4 expose entire subtree"
418 ;; swallow intervening mouse events so we only get the final click-count.
419 (setq event
(foldout-mouse-swallow-events event
))
421 ;; go to the heading clicked on
422 (foldout-mouse-goto-heading event
)
425 (foldout-zoom-subtree
426 (let ((nclicks (event-click-count event
)))
428 ((= nclicks
1) -
1) ; body only
429 ((= nclicks
2) +1) ; subheadings only
430 ((= nclicks
3) nil
) ; body and subheadings
431 (t 0))))) ; entire subtree
433 (defun foldout-mouse-show (event)
434 "Show what is hidden under the heading clicked on.
436 What gets exposed depends on the number of mouse clicks:-
440 3 expose body and subheadings
441 4 expose entire subtree"
444 ;; swallow intervening mouse events so we only get the final click-count.
445 (setq event
(foldout-mouse-swallow-events event
))
448 (foldout-mouse-goto-heading event
)
449 (let ((nclicks (event-click-count event
)))
451 ((= nclicks
1) (show-entry))
452 ((= nclicks
2) (show-children))
453 ((= nclicks
3) (show-entry) (show-children))
454 (t (show-subtree)))))
456 (defun foldout-mouse-hide-or-exit (event)
457 "Hide the subtree under the heading clicked on, or exit a fold.
459 What happens depends on the number of mouse clicks:-
462 2 exit fold and hide text
463 3 exit fold without hiding text
464 4 exit all folds and hide text"
467 ;; swallow intervening mouse events so we only get the final click-count.
468 (setq event
(foldout-mouse-swallow-events event
))
471 (let ((nclicks (event-click-count event
)))
474 (foldout-mouse-goto-heading event
)
478 ((= nclicks
2) 1) ; exit and hide
479 ((= nclicks
3) -
1) ; exit don't hide
480 (t 0)))))) ; exit all
483 (defun foldout-mouse-swallow-events (event)
484 "Swallow intervening mouse events so we only get the final click-count.
485 Signal an error if the final event isn't the same type as the first one."
486 (let ((initial-event-type (event-basic-type event
)))
487 (while (null (sit-for 0 double-click-time
'nodisplay
))
488 (setq event
(read-event)))
489 (or (eq initial-event-type
(event-basic-type event
))
493 (defun foldout-mouse-goto-heading (event)
494 "Go to the heading where the mouse event started. Signal an error
495 if the event didn't occur on a heading."
496 (goto-char (posn-point (event-start event
)))
497 (or (outline-on-heading-p)
498 ;; outline.el sometimes treats beginning-of-buffer as a heading
499 ;; even though outline-on-heading returns nil.
500 (save-excursion (beginning-of-line) (bobp))
501 (error "Not a heading line")))
506 (defvar foldout-inhibit-key-bindings nil
507 "Set non-NIL before loading foldout to inhibit key bindings.")
509 (defvar foldout-mouse-modifiers
'(meta control
)
510 "List of modifier keys to apply to foldout's mouse events.
512 The default (meta control) makes foldout bind its functions to
513 M-C-down-mouse-{1,2,3}.
515 Valid modifiers are shift, control, meta, alt, hyper and super.")
517 (if foldout-inhibit-key-bindings
519 (define-key outline-mode-map
"\C-c\C-z" 'foldout-zoom-subtree
)
520 (define-key outline-mode-map
"\C-c\C-x" 'foldout-exit-fold
)
521 (define-key outline-minor-mode-map
522 (concat outline-minor-mode-prefix
"\C-z") 'foldout-zoom-subtree
)
523 (define-key outline-minor-mode-map
524 (concat outline-minor-mode-prefix
"\C-x") 'foldout-exit-fold
)
526 (let* ((modifiers (apply 'concat
531 ((eq modifier
'shift
) ?S
)
532 ((eq modifier
'control
) ?C
)
533 ((eq modifier
'meta
) ?M
)
534 ((eq modifier
'alt
) ?A
)
535 ((eq modifier
'hyper
) ?H
)
536 ((eq modifier
'super
) ?s
)
537 (t (error "invalid mouse modifier %s"
540 foldout-mouse-modifiers
)))
541 (mouse-1 (vector (intern (concat modifiers
"down-mouse-1"))))
542 (mouse-2 (vector (intern (concat modifiers
"down-mouse-2"))))
543 (mouse-3 (vector (intern (concat modifiers
"down-mouse-3")))))
545 (define-key outline-mode-map mouse-1
'foldout-mouse-zoom
)
546 (define-key outline-mode-map mouse-2
'foldout-mouse-show
)
547 (define-key outline-mode-map mouse-3
'foldout-mouse-hide-or-exit
)
549 (define-key outline-minor-mode-map mouse-1
'foldout-mouse-zoom
)
550 (define-key outline-minor-mode-map mouse-2
'foldout-mouse-show
)
551 (define-key outline-minor-mode-map mouse-3
'foldout-mouse-hide-or-exit
)
556 ;;; foldout.el ends here