1 ;;; foldout.el --- folding extensions for outline-mode and outline-minor-mode
3 ;; Copyright (C) 1994, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
5 ;; Author: Kevin Broadey <KevinB@bartley.demon.co.uk>
7 ;; Created: 27 Jan 1994
8 ;; Version: foldout.el 1.10 dated 94/05/19 at 17:09:12
9 ;; Keywords: folding, outlines
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 2, or (at your option)
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to the
25 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
26 ;; Boston, MA 02110-1301, USA.
30 ;; This file provides folding editor extensions for outline-mode and
31 ;; outline-minor-mode buffers. What's a "folding editor"? Read on...
33 ;; Imagine you're in an outline-mode buffer and you've hidden all the text and
34 ;; subheadings under your level-1 headings. You now want to look at the stuff
35 ;; hidden under one of these headings. Normally you'd do C-c C-e (show-entry)
36 ;; to expose the body or C-c C-i to expose the child (level-2) headings.
38 ;; With foldout, you do C-c C-z (foldout-zoom-subtree). This exposes the body
39 ;; and child subheadings and narrows the buffer so that only the level-1
40 ;; heading, the body and the level-2 headings are visible. If you now want to
41 ;; look under one of the level-2 headings, position the cursor on it and do C-c
42 ;; C-z again. This exposes the level-2 body and its level-3 child subheadings
43 ;; and narrows the buffer again. You can keep on zooming in on successive
44 ;; subheadings as much as you like. A string in the modeline tells you how
47 ;; When zooming in on a heading you might only want to see the child
48 ;; subheadings. You do this by specifying a numeric argument: C-u C-c C-z.
49 ;; You can specify the number of levels of children too (c.f. show-children):
50 ;; e.g. M-2 C-c C-z exposes two levels of child subheadings. Alternatively,
51 ;; you might only be interested in the body. You do this by specifying a
52 ;; negative argument: M-- C-c C-z. You can also cause the whole subtree to be
53 ;; expanded, similar to C-c C-s (show-subtree), by specifying a zero argument:
56 ;; While you're zoomed in you can still use outline-mode's exposure and hiding
57 ;; functions. It won't upset foldout at all. Also, since the buffer is
58 ;; narrowed, "global" editing actions will only affect the stuff under the
59 ;; zoomed-in heading. This is useful for restricting changes to a particular
60 ;; chapter or section of your document.
62 ;; You unzoom (exit) a fold by doing C-c C-x (foldout-exit-fold). This hides
63 ;; all the text and subheadings under the top-level heading and returns you to
64 ;; the previous view of the buffer. Specifying a numeric argument exits that
65 ;; many folds. Specifying a zero argument exits *all* folds.
67 ;; You might want to exit a fold *without* hiding the text and subheadings.
68 ;; You do this by specifying a negative argument. For example, M--2 C-c C-x
69 ;; exits two folds and leaves the text and subheadings exposed.
71 ;; Foldout also provides mouse bindings for entering and exiting folds and for
72 ;; showing and hiding text. Hold down Meta and Control, then click a mouse
73 ;; button as follows:-
75 ;; mouse-1 (foldout-mouse-zoom) zooms in on the heading clicked on:-
77 ;; single click expose body
78 ;; double click expose subheadings
79 ;; triple click expose body and subheadings
80 ;; quad click expose entire subtree
82 ;; mouse-2 (foldout-mouse-show) exposes text under the heading clicked on:-
84 ;; single click expose body
85 ;; double click expose subheadings
86 ;; triple click expose body and subheadings
87 ;; quad click expose entire subtree
89 ;; mouse-3 (foldout-mouse-hide-or-exit) hides text under the heading clicked
90 ;; on or exits the fold:-
92 ;; single click hide subtree
93 ;; double click exit fold and hide text
94 ;; triple click exit fold without hiding text
95 ;; quad click exit all folds and hide text
97 ;; You can change the modifier keys used by setting `foldout-mouse-modifiers'.
101 ;; To use foldout, put this in your .emacs:-
103 ;; (require 'foldout)
105 ;; If you don't want it loaded until you need it, try this instead:-
107 ;; (eval-after-load "outline" '(require 'foldout))
111 ;; Get out-xtra.el by Per Abrahamsen <abraham@iesd.auc.dk> for more
112 ;; outline-mode goodies. In particular, `outline-hide-sublevels' makes
113 ;; setup a lot easier.
115 ;; folding.el by Jamie Lokier <u90jl@ecs.ox.ac.uk> supports folding by
116 ;; recognising special marker text in you file.
118 ;; c-outline.el (by me) provides outline-mode support to recognise `C'
119 ;; statements as outline headings, so with foldout you can have a folding `C'
120 ;; code editor without having to put in start- and end-of-fold markers. This
126 ;; foldout.el is now part of the GNU Emacs distribution!!
127 ;; Put in changes made by RMS to version 1.8 to keep the diffs to a minimum.
128 ;; bugfix: numeric arg to foldout-exit-fold wasn't working - looks like I don't
129 ;; know how to use the Common LISP `loop' macro after all, so use `while'
133 ;; Didn't test that very well, did I? The change to foldout-zoom-subtree
134 ;; affected foldout-mouse-zoom: if the heading under the `level n' one clicked
135 ;; on was at `level n+2' then it didn't get exposed. Sorry about that!
138 ;; Changed meaning of prefix arg to foldout-zoom-subtree. arg > 0 now means
139 ;; "expose that many children" instead of just "expose children" so it is more
140 ;; like `show-children' (C-c C-i). Arg of C-u on its own only shows one level
141 ;; of children, though, so you can still zoom by doing C-u C-c C-z.
143 ;; I can't think of a good meaning for the value of a negative prefix. Any
146 ;; Added advertisement for my c-outline.el package. Now you can have a folding
147 ;; editor for c-mode without any effort!
150 ;; I got fed up trying to work out how many blank lines there were outside the
151 ;; narrowed region when inside a fold. Now *all* newlines before the following
152 ;; heading are *in* the narrowed region. Thus, if the cursor is at point-max,
153 ;; the number of blank lines above it is the number you'll get above the next
156 ;; Since all newlines are now inside the narrowed region, when exiting a fold
157 ;; add a newline at the end of the region if there isn't one so that the
158 ;; following heading doesn't accidentally get joined to the body text.
160 ;; Bugfix: `foldout-mouse-modifiers' should be `defvar', not `defconst'.
162 ;; Use "cond" instead of "case" so that lemacs-19.9 users can use the mouse.
164 ;; Improve "Commentary" entry on using the mouse.
166 ;; Add "Installation" keyword.
169 ;; Add mouse support functions foldout-mouse-zoom, foldout-mouse-show,
170 ;; foldout-mouse-hide-or-exit.
173 ;; Rename `foldout-enter-subtree' to `foldout-zoom-subtree' and change
174 ;; keystroke from C-g to C-z. This is more mnemonic and leaves C-g alone, as
175 ;; users expect this to cancel the current key sequence.
177 ;; Added better commentary at the request of RMS. Added stuff to comply with
178 ;; the lisp-mnt.el conventions. Added instructions on how best to load the
182 ;; Bugfix: end-of-fold marking was wrong:-
184 ;; End of narrowed region should be one character on from
185 ;; (outline-end-of-subtree) so it includes the end-of-line at the end of the
186 ;; last line of the subtree.
188 ;; End-of-fold marker should be outside the narrowed region so text inserted
189 ;; at the end of the region goes before the marker. Need to make a special
190 ;; case for end-of-buffer because it is impossible to set a marker that will
191 ;; follow eob. Bummer.
194 ;; Changed `foldout-zoom-subtree'. A zero arg now makes it expose the entire
195 ;; subtree on entering the fold. As before, < 0 shows only the body and > 0
196 ;; shows only the subheadings.
199 ;; Fixed a dumb bug - didn't make `foldout-modeline-string' buffer-local :-(
201 ;; Changed `foldout-exit-fold' to use prefix arg to say how many folds to exit.
202 ;; Negative arg means exit but don't hide text. Zero arg means exit all folds.
204 ;; Added `foldout-inhibit-key-bindings' to inhibit key bindings.
207 ;; Released to the net. Inspired by a question in gnu.emacs.help from
208 ;; Jason D Lohn <jlohn@eng.umd.edu>.
214 ;; something has gone very wrong if outline-minor-mode isn't bound now.
215 (if (not (boundp 'outline-minor-mode
))
216 (error "Can't find outline-minor-mode"))
218 (defvar foldout-fold-list nil
219 "List of start and end markers for the folds currently entered.
220 An end marker of nil means the fold ends after (point-max).")
221 (make-variable-buffer-local 'foldout-fold-list
)
223 (defvar foldout-modeline-string nil
224 "Modeline string announcing that we are in an outline fold.")
225 (make-variable-buffer-local 'foldout-modeline-string
)
227 ;; put our minor mode string immediately following outline-minor-mode's
228 (or (assq 'foldout-modeline-string minor-mode-alist
)
229 (let ((outl-entry (memq (assq 'outline-minor-mode minor-mode-alist
)
231 (foldout-entry '((foldout-modeline-string foldout-modeline-string
))))
233 ;; something's wrong with outline if we can't find it
234 (if (null outl-entry
)
235 (error "Can't find outline-minor-mode in minor-mode-alist"))
237 ;; slip our fold announcement into the list
238 (setcdr outl-entry
(nconc foldout-entry
(cdr outl-entry
)))
241 ;; outline-flag-region has different `flag' values in outline.el and
242 ;; noutline.el for hiding and showing text.
244 (defconst foldout-hide-flag
245 (if (featurep 'noutline
) t ?\^M
))
247 (defconst foldout-show-flag
248 (if (featurep 'noutline
) nil ?
\n))
251 (defun foldout-zoom-subtree (&optional exposure
)
252 "Open the subtree under the current heading and narrow to it.
254 Normally the body and the immediate subheadings are exposed, but
255 optional arg EXPOSURE \(interactively with prefix arg\) changes this:-
257 EXPOSURE > 0 exposes n levels of subheadings (c.f. show-children)
258 EXPOSURE < 0 exposes only the body
259 EXPOSURE = 0 exposes the entire subtree"
263 (outline-back-to-heading)
264 (let* ((exposure-value (prefix-numeric-value exposure
))
266 (start-marker (point-marker))
267 (end (progn (outline-end-of-subtree)
268 (skip-chars-forward "\n\^M")
270 ;; I need a marker that will follow the end of the region even when
271 ;; text is inserted right at the end. Text gets inserted *after*
272 ;; markers, so I need it at end+1. Unfortunately I can't set a
273 ;; marker at (point-max)+1, so I use nil to mean the region ends at
275 (end-marker (if (eobp) nil
(set-marker (make-marker) (1+ end
))))
278 ;; narrow to this subtree
279 (narrow-to-region start end
)
281 ;; show the body and/or subheadings for this heading
287 ((< exposure-value
0)
291 ((> exposure-value
0)
292 (show-children exposure-value
))
297 ;; save the location of the fold we are entering
298 (setq foldout-fold-list
(cons (cons start-marker end-marker
)
301 ;; update the modeline
302 (foldout-update-modeline)
306 (defun foldout-exit-fold (&optional num-folds
)
307 "Return to the ARG'th enclosing fold view. With ARG = 0 exit all folds.
309 Normally causes exited folds to be hidden, but with ARG < 0, -ARG folds are
310 exited and text is left visible."
312 (let ((hide-fold t
) start-marker end-marker
313 beginning-of-heading end-of-subtree
)
315 ;; check there are some folds to leave
316 (if (null foldout-fold-list
)
317 (error "Not in a fold!"))
320 ;; catch a request to leave all folds
322 (setq num-folds
(length foldout-fold-list
)))
324 ;; have we been told not to hide the fold?
327 num-folds
(- num-folds
)))
330 ;; limit the number of folds if we've been told to exit too many
331 (setq num-folds
(min num-folds
(length foldout-fold-list
)))
335 (while (not (zerop num-folds
))
336 ;; get the fold at the top of the stack
337 (setq start-marker
(car (car foldout-fold-list
))
338 end-marker
(cdr (car foldout-fold-list
))
339 foldout-fold-list
(cdr foldout-fold-list
)
340 num-folds
(1- num-folds
))
342 ;; Make sure there is a newline at the end of this fold,
343 ;; otherwise the following heading will get joined to the body
347 (goto-char end-marker
)
349 (or (memq (preceding-char) '(?
\n ?\^M
))
352 ;; If this is the last fold to exit, hide the text unless we've
353 ;; been told not to. Note that at the moment point is at the
354 ;; beginning of the following heading if there is one.
356 ;; Also, make sure that the newline before the following heading
357 ;; is \n otherwise it will be hidden. If there is a newline
358 ;; before this one, make it visible too so we do the same as
359 ;; outline.el and leave a blank line before the heading.
360 (when (zerop num-folds
)
362 (setq beginning-of-heading
(point)
363 end-of-subtree
(progn (forward-char -
1)
364 (if (memq (preceding-char)
370 (goto-char start-marker
)
373 ;; make sure the next heading is exposed
375 (outline-flag-region end-of-subtree beginning-of-heading
378 ;; zap the markers so they don't slow down editing
379 (set-marker start-marker nil
)
380 (if end-marker
(set-marker end-marker nil
))
383 ;; narrow to the enclosing fold if there is one
384 (if foldout-fold-list
386 (setq start-marker
(car (car foldout-fold-list
))
387 end-marker
(cdr (car foldout-fold-list
)))
388 (narrow-to-region start-marker
390 (1- (marker-position end-marker
))
395 ;; update the modeline
396 (foldout-update-modeline)
400 (defun foldout-update-modeline ()
401 "Set the modeline string to indicate our fold depth."
402 (let ((depth (length foldout-fold-list
)))
403 (setq foldout-modeline-string
405 ;; if we're not in a fold, keep quiet
408 ;; in outline-minor-mode we're after "Outl:xx" in the modeline
410 (format ":%d" depth
))
411 ;; otherwise just announce the depth (I guess we're in outline-mode)
415 (format " Inside %d folds" depth
))
419 (defun foldout-mouse-zoom (event)
420 "Zoom in on the heading clicked on.
422 How much is exposed by the zoom depends on the number of mouse clicks:-
426 3 expose body and subheadings
427 4 expose entire subtree"
430 ;; swallow intervening mouse events so we only get the final click-count.
431 (setq event
(foldout-mouse-swallow-events event
))
433 ;; go to the heading clicked on
434 (foldout-mouse-goto-heading event
)
437 (foldout-zoom-subtree
438 (let ((nclicks (event-click-count event
)))
440 ((= nclicks
1) -
1) ; body only
441 ((= nclicks
2) '(1)) ; subheadings only
442 ((= nclicks
3) nil
) ; body and subheadings
443 (t 0))))) ; entire subtree
445 (defun foldout-mouse-show (event)
446 "Show what is hidden under the heading clicked on.
448 What gets exposed depends on the number of mouse clicks:-
452 3 expose body and subheadings
453 4 expose entire subtree"
456 ;; swallow intervening mouse events so we only get the final click-count.
457 (setq event
(foldout-mouse-swallow-events event
))
460 (foldout-mouse-goto-heading event
)
461 (let ((nclicks (event-click-count event
)))
463 ((= nclicks
1) (show-entry))
464 ((= nclicks
2) (show-children))
465 ((= nclicks
3) (show-entry) (show-children))
466 (t (show-subtree)))))
468 (defun foldout-mouse-hide-or-exit (event)
469 "Hide the subtree under the heading clicked on, or exit a fold.
471 What happens depends on the number of mouse clicks:-
474 2 exit fold and hide text
475 3 exit fold without hiding text
476 4 exit all folds and hide text"
479 ;; swallow intervening mouse events so we only get the final click-count.
480 (setq event
(foldout-mouse-swallow-events event
))
483 (let ((nclicks (event-click-count event
)))
486 (foldout-mouse-goto-heading event
)
490 ((= nclicks
2) 1) ; exit and hide
491 ((= nclicks
3) -
1) ; exit don't hide
492 (t 0)))))) ; exit all
495 (defun foldout-mouse-swallow-events (event)
496 "Swallow intervening mouse events so we only get the final click-count.
497 Signal an error if the final event isn't the same type as the first one."
498 (let ((initial-event-type (event-basic-type event
)))
499 (while (null (sit-for 0 double-click-time
'nodisplay
))
500 (setq event
(read-event)))
501 (or (eq initial-event-type
(event-basic-type event
))
505 (defun foldout-mouse-goto-heading (event)
506 "Go to the heading where the mouse event started. Signal an error
507 if the event didn't occur on a heading."
508 (goto-char (posn-point (event-start event
)))
509 (or (outline-on-heading-p)
510 ;; outline.el sometimes treats beginning-of-buffer as a heading
511 ;; even though outline-on-heading returns nil.
512 (save-excursion (beginning-of-line) (bobp))
513 (error "Not a heading line")))
518 (defvar foldout-inhibit-key-bindings nil
519 "Set non-nil before loading foldout to inhibit key bindings.")
521 (defvar foldout-mouse-modifiers
'(meta control
)
522 "List of modifier keys to apply to foldout's mouse events.
524 The default (meta control) makes foldout bind its functions to
525 M-C-down-mouse-{1,2,3}.
527 Valid modifiers are shift, control, meta, alt, hyper and super.")
529 (if foldout-inhibit-key-bindings
531 (define-key outline-mode-map
"\C-c\C-z" 'foldout-zoom-subtree
)
532 (define-key outline-mode-map
"\C-c\C-x" 'foldout-exit-fold
)
533 (let ((map (lookup-key outline-minor-mode-map outline-minor-mode-prefix
)))
535 (setq map
(make-sparse-keymap))
536 (define-key outline-minor-mode-map outline-minor-mode-prefix map
))
537 (define-key map
"\C-z" 'foldout-zoom-subtree
)
538 (define-key map
"\C-x" 'foldout-exit-fold
))
539 (let* ((modifiers (apply 'concat
544 ((eq modifier
'shift
) ?S
)
545 ((eq modifier
'control
) ?C
)
546 ((eq modifier
'meta
) ?M
)
547 ((eq modifier
'alt
) ?A
)
548 ((eq modifier
'hyper
) ?H
)
549 ((eq modifier
'super
) ?s
)
550 (t (error "invalid mouse modifier %s"
553 foldout-mouse-modifiers
)))
554 (mouse-1 (vector (intern (concat modifiers
"down-mouse-1"))))
555 (mouse-2 (vector (intern (concat modifiers
"down-mouse-2"))))
556 (mouse-3 (vector (intern (concat modifiers
"down-mouse-3")))))
558 (define-key outline-mode-map mouse-1
'foldout-mouse-zoom
)
559 (define-key outline-mode-map mouse-2
'foldout-mouse-show
)
560 (define-key outline-mode-map mouse-3
'foldout-mouse-hide-or-exit
)
562 (define-key outline-minor-mode-map mouse-1
'foldout-mouse-zoom
)
563 (define-key outline-minor-mode-map mouse-2
'foldout-mouse-show
)
564 (define-key outline-minor-mode-map mouse-3
'foldout-mouse-hide-or-exit
)
569 ;;; arch-tag: 19d095a2-1f09-42a7-a5ac-e2a3078cfe95
570 ;;; foldout.el ends here