1;;; foldout.el --- folding extensions for outline-mode and outline-minor-mode 2 3;; Copyright (C) 1994, 2001, 2002, 2003, 2004, 2005, 4;; 2006, 2007 Free Software Foundation, Inc. 5 6;; Author: Kevin Broadey <KevinB@bartley.demon.co.uk> 7;; Maintainer: FSF 8;; Created: 27 Jan 1994 9;; Version: foldout.el 1.10 dated 94/05/19 at 17:09:12 10;; Keywords: folding, outlines 11 12;; This file is part of GNU Emacs. 13 14;; GNU Emacs is free software; you can redistribute it and/or modify 15;; it under the terms of the GNU General Public License as published by 16;; the Free Software Foundation; either version 2, or (at your option) 17;; any later version. 18 19;; GNU Emacs is distributed in the hope that it will be useful, 20;; but WITHOUT ANY WARRANTY; without even the implied warranty of 21;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22;; GNU General Public License for more details. 23 24;; You should have received a copy of the GNU General Public License 25;; along with GNU Emacs; see the file COPYING. If not, write to the 26;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 27;; Boston, MA 02110-1301, USA. 28 29;;; Commentary: 30 31;; This file provides folding editor extensions for outline-mode and 32;; outline-minor-mode buffers. What's a "folding editor"? Read on... 33;; 34;; Imagine you're in an outline-mode buffer and you've hidden all the text and 35;; subheadings under your level-1 headings. You now want to look at the stuff 36;; hidden under one of these headings. Normally you'd do C-c C-e (show-entry) 37;; to expose the body or C-c C-i to expose the child (level-2) headings. 38;; 39;; With foldout, you do C-c C-z (foldout-zoom-subtree). This exposes the body 40;; and child subheadings and narrows the buffer so that only the level-1 41;; heading, the body and the level-2 headings are visible. If you now want to 42;; look under one of the level-2 headings, position the cursor on it and do C-c 43;; C-z again. This exposes the level-2 body and its level-3 child subheadings 44;; and narrows the buffer again. You can keep on zooming in on successive 45;; subheadings as much as you like. A string in the modeline tells you how 46;; deep you've gone. 47;; 48;; When zooming in on a heading you might only want to see the child 49;; subheadings. You do this by specifying a numeric argument: C-u C-c C-z. 50;; You can specify the number of levels of children too (c.f. show-children): 51;; e.g. M-2 C-c C-z exposes two levels of child subheadings. Alternatively, 52;; you might only be interested in the body. You do this by specifying a 53;; negative argument: M-- C-c C-z. You can also cause the whole subtree to be 54;; expanded, similar to C-c C-s (show-subtree), by specifying a zero argument: 55;; M-0 C-c C-z. 56;; 57;; While you're zoomed in you can still use outline-mode's exposure and hiding 58;; functions. It won't upset foldout at all. Also, since the buffer is 59;; narrowed, "global" editing actions will only affect the stuff under the 60;; zoomed-in heading. This is useful for restricting changes to a particular 61;; chapter or section of your document. 62;; 63;; You unzoom (exit) a fold by doing C-c C-x (foldout-exit-fold). This hides 64;; all the text and subheadings under the top-level heading and returns you to 65;; the previous view of the buffer. Specifying a numeric argument exits that 66;; many folds. Specifying a zero argument exits *all* folds. 67;; 68;; You might want to exit a fold *without* hiding the text and subheadings. 69;; You do this by specifying a negative argument. For example, M--2 C-c C-x 70;; exits two folds and leaves the text and subheadings exposed. 71;; 72;; Foldout also provides mouse bindings for entering and exiting folds and for 73;; showing and hiding text. Hold down Meta and Control, then click a mouse 74;; button as follows:- 75;; 76;; mouse-1 (foldout-mouse-zoom) zooms in on the heading clicked on:- 77;; 78;; single click expose body 79;; double click expose subheadings 80;; triple click expose body and subheadings 81;; quad click expose entire subtree 82;; 83;; mouse-2 (foldout-mouse-show) exposes text under the heading clicked on:- 84;; 85;; single click expose body 86;; double click expose subheadings 87;; triple click expose body and subheadings 88;; quad click expose entire subtree 89;; 90;; mouse-3 (foldout-mouse-hide-or-exit) hides text under the heading clicked 91;; on or exits the fold:- 92;; 93;; single click hide subtree 94;; double click exit fold and hide text 95;; triple click exit fold without hiding text 96;; quad click exit all folds and hide text 97;; 98;; You can change the modifier keys used by setting `foldout-mouse-modifiers'. 99 100;;; Installation: 101 102;; To use foldout, put this in your .emacs:- 103;; 104;; (require 'foldout) 105;; 106;; If you don't want it loaded until you need it, try this instead:- 107;; 108;; (eval-after-load "outline" '(require 'foldout)) 109 110;;; Advertisements: 111 112;; Get out-xtra.el by Per Abrahamsen <abraham@iesd.auc.dk> for more 113;; outline-mode goodies. In particular, `outline-hide-sublevels' makes 114;; setup a lot easier. 115;; 116;; folding.el by Jamie Lokier <u90jl@ecs.ox.ac.uk> supports folding by 117;; recognising special marker text in you file. 118;; 119;; c-outline.el (by me) provides outline-mode support to recognise `C' 120;; statements as outline headings, so with foldout you can have a folding `C' 121;; code editor without having to put in start- and end-of-fold markers. This 122;; is a real winner! 123 124;;; ChangeLog: 125 126;; 1.10 21-Mar-94 127;; foldout.el is now part of the GNU Emacs distribution!! 128;; Put in changes made by RMS to version 1.8 to keep the diffs to a minimum. 129;; bugfix: numeric arg to foldout-exit-fold wasn't working - looks like I don't 130;; know how to use the Common LISP `loop' macro after all, so use `while' 131;; instead. 132 133;; 1.9 15-Mar-94 134;; Didn't test that very well, did I? The change to foldout-zoom-subtree 135;; affected foldout-mouse-zoom: if the heading under the `level n' one clicked 136;; on was at `level n+2' then it didn't get exposed. Sorry about that! 137 138;; 1.8 15-Mar-94 139;; Changed meaning of prefix arg to foldout-zoom-subtree. arg > 0 now means 140;; "expose that many children" instead of just "expose children" so it is more 141;; like `show-children' (C-c C-i). Arg of C-u on its own only shows one level 142;; of children, though, so you can still zoom by doing C-u C-c C-z. 143;; 144;; I can't think of a good meaning for the value of a negative prefix. Any 145;; suggestions? 146;; 147;; Added advertisement for my c-outline.el package. Now you can have a folding 148;; editor for c-mode without any effort! 149 150;; 1.7 7-Mar-94 151;; I got fed up trying to work out how many blank lines there were outside the 152;; narrowed region when inside a fold. Now *all* newlines before the following 153;; heading are *in* the narrowed region. Thus, if the cursor is at point-max, 154;; the number of blank lines above it is the number you'll get above the next 155;; heading. 156;; 157;; Since all newlines are now inside the narrowed region, when exiting a fold 158;; add a newline at the end of the region if there isn't one so that the 159;; following heading doesn't accidentally get joined to the body text. 160;; 161;; Bugfix: `foldout-mouse-modifiers' should be `defvar', not `defconst'. 162;; 163;; Use "cond" instead of "case" so that lemacs-19.9 users can use the mouse. 164;; 165;; Improve "Commentary" entry on using the mouse. 166;; 167;; Add "Installation" keyword. 168 169;; 1.6 3-Mar-94 170;; Add mouse support functions foldout-mouse-zoom, foldout-mouse-show, 171;; foldout-mouse-hide-or-exit. 172 173;; 1.5 11-Feb-94 174;; Rename `foldout-enter-subtree' to `foldout-zoom-subtree' and change 175;; keystroke from C-g to C-z. This is more mnemonic and leaves C-g alone, as 176;; users expect this to cancel the current key sequence. 177;; 178;; Added better commentary at the request of RMS. Added stuff to comply with 179;; the lisp-mnt.el conventions. Added instructions on how best to load the 180;; package. 181 182;; 1.4 2-Feb-94 183;; Bugfix: end-of-fold marking was wrong:- 184;; 185;; End of narrowed region should be one character on from 186;; (outline-end-of-subtree) so it includes the end-of-line at the end of the 187;; last line of the subtree. 188;; 189;; End-of-fold marker should be outside the narrowed region so text inserted 190;; at the end of the region goes before the marker. Need to make a special 191;; case for end-of-buffer because it is impossible to set a marker that will 192;; follow eob. Bummer. 193 194;; 1.3 28-Jan-94 195;; Changed `foldout-zoom-subtree'. A zero arg now makes it expose the entire 196;; subtree on entering the fold. As before, < 0 shows only the body and > 0 197;; shows only the subheadings. 198 199;; 1.2 28-Jan-94 200;; Fixed a dumb bug - didn't make `foldout-modeline-string' buffer-local :-( 201;; 202;; Changed `foldout-exit-fold' to use prefix arg to say how many folds to exit. 203;; Negative arg means exit but don't hide text. Zero arg means exit all folds. 204;; 205;; Added `foldout-inhibit-key-bindings' to inhibit key bindings. 206 207;; 1.1 27-Jan-94 208;; Released to the net. Inspired by a question in gnu.emacs.help from 209;; Jason D Lohn <jlohn@eng.umd.edu>. 210 211;;; Code: 212 213(require 'outline) 214 215;; something has gone very wrong if outline-minor-mode isn't bound now. 216(if (not (boundp 'outline-minor-mode)) 217 (error "Can't find outline-minor-mode")) 218 219(defvar foldout-fold-list nil 220 "List of start and end markers for the folds currently entered. 221An end marker of nil means the fold ends after (point-max).") 222(make-variable-buffer-local 'foldout-fold-list) 223 224(defvar foldout-modeline-string nil 225 "Modeline string announcing that we are in an outline fold.") 226(make-variable-buffer-local 'foldout-modeline-string) 227 228;; put our minor mode string immediately following outline-minor-mode's 229(or (assq 'foldout-modeline-string minor-mode-alist) 230 (let ((outl-entry (memq (assq 'outline-minor-mode minor-mode-alist) 231 minor-mode-alist)) 232 (foldout-entry '((foldout-modeline-string foldout-modeline-string)))) 233 234 ;; something's wrong with outline if we can't find it 235 (if (null outl-entry) 236 (error "Can't find outline-minor-mode in minor-mode-alist")) 237 238 ;; slip our fold announcement into the list 239 (setcdr outl-entry (nconc foldout-entry (cdr outl-entry))) 240 )) 241 242;; outline-flag-region has different `flag' values in outline.el and 243;; noutline.el for hiding and showing text. 244 245(defconst foldout-hide-flag 246 (if (featurep 'noutline) t ?\^M)) 247 248(defconst foldout-show-flag 249 (if (featurep 'noutline) nil ?\n)) 250 251 252(defun foldout-zoom-subtree (&optional exposure) 253 "Open the subtree under the current heading and narrow to it. 254 255Normally the body and the immediate subheadings are exposed, but 256optional arg EXPOSURE \(interactively with prefix arg\) changes this:- 257 258 EXPOSURE > 0 exposes n levels of subheadings (c.f. show-children) 259 EXPOSURE < 0 exposes only the body 260 EXPOSURE = 0 exposes the entire subtree" 261 (interactive "P") 262 (save-excursion 263 (widen) 264 (outline-back-to-heading) 265 (let* ((exposure-value (prefix-numeric-value exposure)) 266 (start (point)) 267 (start-marker (point-marker)) 268 (end (progn (outline-end-of-subtree) 269 (skip-chars-forward "\n\^M") 270 (point))) 271 ;; I need a marker that will follow the end of the region even when 272 ;; text is inserted right at the end. Text gets inserted *after* 273 ;; markers, so I need it at end+1. Unfortunately I can't set a 274 ;; marker at (point-max)+1, so I use nil to mean the region ends at 275 ;; (point-max). 276 (end-marker (if (eobp) nil (set-marker (make-marker) (1+ end)))) 277 ) 278 279 ;; narrow to this subtree 280 (narrow-to-region start end) 281 282 ;; show the body and/or subheadings for this heading 283 (goto-char start) 284 (cond 285 ((null exposure) 286 (show-entry) 287 (show-children)) 288 ((< exposure-value 0) 289 (show-entry)) 290 ((consp exposure) 291 (show-children)) 292 ((> exposure-value 0) 293 (show-children exposure-value)) 294 (t 295 (show-subtree)) 296 ) 297 298 ;; save the location of the fold we are entering 299 (setq foldout-fold-list (cons (cons start-marker end-marker) 300 foldout-fold-list)) 301 302 ;; update the modeline 303 (foldout-update-modeline) 304 ))) 305 306 307(defun foldout-exit-fold (&optional num-folds) 308 "Return to the ARG'th enclosing fold view. With ARG = 0 exit all folds. 309 310Normally causes exited folds to be hidden, but with ARG < 0, -ARG folds are 311exited and text is left visible." 312 (interactive "p") 313 (let ((hide-fold t) start-marker end-marker 314 beginning-of-heading end-of-subtree) 315 316 ;; check there are some folds to leave 317 (if (null foldout-fold-list) 318 (error "Not in a fold!")) 319 320 (cond 321 ;; catch a request to leave all folds 322 ((zerop num-folds) 323 (setq num-folds (length foldout-fold-list))) 324 325 ;; have we been told not to hide the fold? 326 ((< num-folds 0) 327 (setq hide-fold nil 328 num-folds (- num-folds))) 329 ) 330 331 ;; limit the number of folds if we've been told to exit too many 332 (setq num-folds (min num-folds (length foldout-fold-list))) 333 334 ;; exit the folds 335 (widen) 336 (while (not (zerop num-folds)) 337 ;; get the fold at the top of the stack 338 (setq start-marker (car (car foldout-fold-list)) 339 end-marker (cdr (car foldout-fold-list)) 340 foldout-fold-list (cdr foldout-fold-list) 341 num-folds (1- num-folds)) 342 343 ;; Make sure there is a newline at the end of this fold, 344 ;; otherwise the following heading will get joined to the body 345 ;; text. 346 (if end-marker 347 (progn 348 (goto-char end-marker) 349 (forward-char -1) 350 (or (memq (preceding-char) '(?\n ?\^M)) 351 (insert ?\n)))) 352 353 ;; If this is the last fold to exit, hide the text unless we've 354 ;; been told not to. Note that at the moment point is at the 355 ;; beginning of the following heading if there is one. 356 357 ;; Also, make sure that the newline before the following heading 358 ;; is \n otherwise it will be hidden. If there is a newline 359 ;; before this one, make it visible too so we do the same as 360 ;; outline.el and leave a blank line before the heading. 361 (when (zerop num-folds) 362 (if end-marker 363 (setq beginning-of-heading (point) 364 end-of-subtree (progn (forward-char -1) 365 (if (memq (preceding-char) 366 '(?\n ?\^M)) 367 (forward-char -1)) 368 (point)))) 369 ;; hide the subtree 370 (when hide-fold 371 (goto-char start-marker) 372 (hide-subtree)) 373 374 ;; make sure the next heading is exposed 375 (if end-marker 376 (outline-flag-region end-of-subtree beginning-of-heading 377 foldout-show-flag))) 378 379 ;; zap the markers so they don't slow down editing 380 (set-marker start-marker nil) 381 (if end-marker (set-marker end-marker nil)) 382 ) 383 384 ;; narrow to the enclosing fold if there is one 385 (if foldout-fold-list 386 (progn 387 (setq start-marker (car (car foldout-fold-list)) 388 end-marker (cdr (car foldout-fold-list))) 389 (narrow-to-region start-marker 390 (if end-marker 391 (1- (marker-position end-marker)) 392 (point-max))) 393 )) 394 (recenter) 395 396 ;; update the modeline 397 (foldout-update-modeline) 398 )) 399 400 401(defun foldout-update-modeline () 402 "Set the modeline string to indicate our fold depth." 403 (let ((depth (length foldout-fold-list))) 404 (setq foldout-modeline-string 405 (cond 406 ;; if we're not in a fold, keep quiet 407 ((zerop depth) 408 nil) 409 ;; in outline-minor-mode we're after "Outl:xx" in the modeline 410 (outline-minor-mode 411 (format ":%d" depth)) 412 ;; otherwise just announce the depth (I guess we're in outline-mode) 413 ((= depth 1) 414 " Inside 1 fold") 415 (t 416 (format " Inside %d folds" depth)) 417 )))) 418 419 420(defun foldout-mouse-zoom (event) 421 "Zoom in on the heading clicked on. 422 423How much is exposed by the zoom depends on the number of mouse clicks:- 424 425 1 expose body 426 2 expose subheadings 427 3 expose body and subheadings 428 4 expose entire subtree" 429 (interactive "@e") 430 431 ;; swallow intervening mouse events so we only get the final click-count. 432 (setq event (foldout-mouse-swallow-events event)) 433 434 ;; go to the heading clicked on 435 (foldout-mouse-goto-heading event) 436 437 ;; zoom away 438 (foldout-zoom-subtree 439 (let ((nclicks (event-click-count event))) 440 (cond 441 ((= nclicks 1) -1) ; body only 442 ((= nclicks 2) '(1)) ; subheadings only 443 ((= nclicks 3) nil) ; body and subheadings 444 (t 0))))) ; entire subtree 445 446(defun foldout-mouse-show (event) 447 "Show what is hidden under the heading clicked on. 448 449What gets exposed depends on the number of mouse clicks:- 450 451 1 expose body 452 2 expose subheadings 453 3 expose body and subheadings 454 4 expose entire subtree" 455 (interactive "@e") 456 457 ;; swallow intervening mouse events so we only get the final click-count. 458 (setq event (foldout-mouse-swallow-events event)) 459 460 ;; expose the text 461 (foldout-mouse-goto-heading event) 462 (let ((nclicks (event-click-count event))) 463 (cond 464 ((= nclicks 1) (show-entry)) 465 ((= nclicks 2) (show-children)) 466 ((= nclicks 3) (show-entry) (show-children)) 467 (t (show-subtree))))) 468 469(defun foldout-mouse-hide-or-exit (event) 470 "Hide the subtree under the heading clicked on, or exit a fold. 471 472What happens depends on the number of mouse clicks:- 473 474 1 hide subtree 475 2 exit fold and hide text 476 3 exit fold without hiding text 477 4 exit all folds and hide text" 478 (interactive "@e") 479 480 ;; swallow intervening mouse events so we only get the final click-count. 481 (setq event (foldout-mouse-swallow-events event)) 482 483 ;; hide or exit 484 (let ((nclicks (event-click-count event))) 485 (if (= nclicks 1) 486 (progn 487 (foldout-mouse-goto-heading event) 488 (hide-subtree)) 489 (foldout-exit-fold 490 (cond 491 ((= nclicks 2) 1) ; exit and hide 492 ((= nclicks 3) -1) ; exit don't hide 493 (t 0)))))) ; exit all 494 495 496(defun foldout-mouse-swallow-events (event) 497 "Swallow intervening mouse events so we only get the final click-count. 498Signal an error if the final event isn't the same type as the first one." 499 (let ((initial-event-type (event-basic-type event))) 500 (while (null (sit-for 0 double-click-time 'nodisplay)) 501 (setq event (read-event))) 502 (or (eq initial-event-type (event-basic-type event)) 503 (error ""))) 504 event) 505 506(defun foldout-mouse-goto-heading (event) 507 "Go to the heading where the mouse event started. Signal an error 508if the event didn't occur on a heading." 509 (goto-char (posn-point (event-start event))) 510 (or (outline-on-heading-p) 511 ;; outline.el sometimes treats beginning-of-buffer as a heading 512 ;; even though outline-on-heading returns nil. 513 (save-excursion (beginning-of-line) (bobp)) 514 (error "Not a heading line"))) 515 516 517;;; Keymaps: 518 519(defvar foldout-inhibit-key-bindings nil 520 "Set non-nil before loading foldout to inhibit key bindings.") 521 522(defvar foldout-mouse-modifiers '(meta control) 523 "List of modifier keys to apply to foldout's mouse events. 524 525The default (meta control) makes foldout bind its functions to 526M-C-down-mouse-{1,2,3}. 527 528Valid modifiers are shift, control, meta, alt, hyper and super.") 529 530(if foldout-inhibit-key-bindings 531 () 532 (define-key outline-mode-map "\C-c\C-z" 'foldout-zoom-subtree) 533 (define-key outline-mode-map "\C-c\C-x" 'foldout-exit-fold) 534 (let ((map (lookup-key outline-minor-mode-map outline-minor-mode-prefix))) 535 (unless map 536 (setq map (make-sparse-keymap)) 537 (define-key outline-minor-mode-map outline-minor-mode-prefix map)) 538 (define-key map "\C-z" 'foldout-zoom-subtree) 539 (define-key map "\C-x" 'foldout-exit-fold)) 540 (let* ((modifiers (apply 'concat 541 (mapcar (function 542 (lambda (modifier) 543 (vector 544 (cond 545 ((eq modifier 'shift) ?S) 546 ((eq modifier 'control) ?C) 547 ((eq modifier 'meta) ?M) 548 ((eq modifier 'alt) ?A) 549 ((eq modifier 'hyper) ?H) 550 ((eq modifier 'super) ?s) 551 (t (error "invalid mouse modifier %s" 552 modifier))) 553 ?-))) 554 foldout-mouse-modifiers))) 555 (mouse-1 (vector (intern (concat modifiers "down-mouse-1")))) 556 (mouse-2 (vector (intern (concat modifiers "down-mouse-2")))) 557 (mouse-3 (vector (intern (concat modifiers "down-mouse-3"))))) 558 559 (define-key outline-mode-map mouse-1 'foldout-mouse-zoom) 560 (define-key outline-mode-map mouse-2 'foldout-mouse-show) 561 (define-key outline-mode-map mouse-3 'foldout-mouse-hide-or-exit) 562 563 (define-key outline-minor-mode-map mouse-1 'foldout-mouse-zoom) 564 (define-key outline-minor-mode-map mouse-2 'foldout-mouse-show) 565 (define-key outline-minor-mode-map mouse-3 'foldout-mouse-hide-or-exit) 566 )) 567 568(provide 'foldout) 569 570;;; arch-tag: 19d095a2-1f09-42a7-a5ac-e2a3078cfe95 571;;; foldout.el ends here 572