lisp/org-indent.el

   1 ;;; org-indent.el --- Dynamic indentation for  Org-mode
   2 ;; Copyright (C) 2008 Free Software Foundation, Inc.
   3 ;;
   4 ;; Author: Carsten Dominik <carsten at orgmode dot org>
   5 ;; Keywords: outlines, hypermedia, calendar, wp
   6 ;; Homepage: http://orgmode.org
   7 ;; Version: 6.29c
   8 ;;
   9 ;; This file is part of GNU Emacs.
  10 ;;
  11 ;; This file is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 3, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24 ;; Boston, MA 02110-1301, USA.
  25 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  26 ;;
  27 ;;; Commentary:
  28
  29 ;; This is an implementation of dynamic virtual indentation.  It works
  30 ;; by adding text properties to a buffer to make sure lines are
  31 ;; indented according to outline structure.
  32
  33 (require 'org-macs)
  34 (require 'org-compat)
  35 (require 'org)
  36 (eval-when-compile
  37   (require 'cl))
  38
  39
  40 (defgroup org-indent nil
  41   "Options concerning dynamic virtual outline indentation."
  42   :tag "Org Structure"
  43   :group 'org)
  44
  45 (defconst org-indent-max 40
  46   "Maximum indentation in characters")
  47 (defconst org-indent-max-levels 40
  48   "Maximum indentation in characters")
  49
  50 (defvar org-indent-strings nil
  51   "Vector with all indentation strings.
  52 It will be set in `org-indent-initialize'.")
  53 (defvar org-indent-stars nil
  54   "Vector with all indentation star strings.
  55 It will be set in `org-indent-initialize'.")
  56 (defvar org-hide-leading-stars-before-indent-mode nil
  57   "Used locally")
  58
  59 (defcustom org-indent-boundary-char ?\   ; comment to protect space char
  60   "The end of the virtual indentation strings, a single-character string.
  61 The default is just a space, but if you wish, you can use \"|\" or so.
  62 This can be useful on a terminal window - under a windowing system,
  63 it may be prettier to customize the org-indent face."
  64   :group 'org-indent
  65   :set (lambda (var val)
  66          (set var val)
  67          (and org-indent-strings (org-indent-initialize)))
  68   :type 'character)
  69
  70 (defcustom org-indent-mode-turns-off-org-adapt-indentation t
  71   "Non-nil means, turning on org-indent-mode turns off indentation adaptation.
  72 For details see the variable `org-adapt-indentation'."
  73   :group 'org-indent
  74   :type 'boolean)
  75
  76 (defcustom org-indent-mode-turns-on-hiding-stars t
  77   "Non-nil means, turning on org-indent-mode turns on `org-hide-leading-stars'."
  78   :group 'org-indent
  79   :type 'boolean)
  80
  81 (defcustom org-indent-indentation-per-level 2
  82   "Indentation per level in number of characters."
  83   :group 'org-indent
  84   :type 'integer)
  85
  86 (defcustom org-indent-fix-section-after-idle-time 0.2
  87   "Seconds of idle time before fixing virtual indentation of section.
  88 The hooking-in of virtual indentation is not yet perfect.  Occasionally,
  89 a change does not trigger to proper change of indentation.  For this we
  90 have a timer action that fixes indentation in the current section after
  91 a short amount idle time.  If we ever get the integration to work perfectly,
  92 this variable can be set to nil to get rid of the timer."
  93   :group 'org-indent
  94   :type '(choice
  95           (const "Do not install idle timer" nil)
  96           (number :tag "Idle time")))
  97
  98 (defun org-indent-initialize ()
  99   "Initialize the indentation strings and set the idle timer."
 100   ;; We use an idle timer to "repair" the current section, because the
 101   ;; redisplay seems to have some problems.
 102   (unless org-indent-strings
 103     (when org-indent-fix-section-after-idle-time
 104       (run-with-idle-timer
 105        org-indent-fix-section-after-idle-time
 106        t 'org-indent-refresh-section)))
 107   ;; Initialize the indentation and star vectors
 108   (setq org-indent-strings (make-vector (1+ org-indent-max) nil))
 109   (setq org-indent-stars (make-vector (1+ org-indent-max) nil))
 110   (aset org-indent-strings 0 "")
 111   (aset org-indent-stars 0 "")
 112   (loop for i from 1 to org-indent-max do
 113         (aset org-indent-strings i
 114               (org-add-props
 115                   (concat (make-string (1- i) ?\ )
 116                           (char-to-string org-indent-boundary-char))
 117                   nil 'face 'org-indent)))
 118   (loop for i from 1 to org-indent-max-levels do
 119         (aset org-indent-stars i
 120               (org-add-props (make-string i ?*)
 121                   nil 'face 'org-hide))))
 122
 123 ;;;###autoload
 124 (define-minor-mode org-indent-mode
 125   "When active, indent text according to outline structure.
 126
 127 Internally this works by adding `line-prefix' properties to all non-headlines.
 128 These properties are updated locally in idle time.
 129 FIXME:  How to update when broken?"
 130   nil " Ind" nil
 131   (if (org-bound-and-true-p org-inhibit-startup)
 132       (setq org-indent-mode nil)
 133     (if org-indent-mode
 134         (progn
 135           (or org-indent-strings (org-indent-initialize))
 136           (when org-indent-mode-turns-off-org-adapt-indentation
 137             (org-set-local 'org-adapt-indentation nil))
 138           (when org-indent-mode-turns-on-hiding-stars
 139             (org-set-local 'org-hide-leading-stars-before-indent-mode
 140                            org-hide-leading-stars)
 141             (org-set-local 'org-hide-leading-stars t))
 142           (make-local-variable 'buffer-substring-filters)
 143           (add-to-list 'buffer-substring-filters
 144                        'org-indent-remove-properties-from-string)
 145           (org-add-hook 'org-after-demote-entry-hook
 146                         'org-indent-refresh-section nil 'local)
 147           (org-add-hook 'org-after-promote-entry-hook
 148                         'org-indent-refresh-section nil 'local)
 149           (org-add-hook 'org-font-lock-hook
 150                         'org-indent-refresh-to nil 'local)
 151           (and font-lock-mode (org-restart-font-lock))
 152           )
 153       (save-excursion
 154         (save-restriction
 155           (org-indent-remove-properties (point-min) (point-max))
 156           (kill-local-variable 'org-adapt-indentation)
 157           (when (boundp 'org-hide-leading-stars-before-indent-mode)
 158             (org-set-local 'org-hide-leading-stars
 159                            org-hide-leading-stars-before-indent-mode))
 160           (setq buffer-substring-filters
 161                 (delq 'org-indent-remove-properties-from-string
 162                       buffer-substring-filters))
 163           (remove-hook 'org-after-promote-entry-hook
 164                        'org-indent-refresh-section 'local)
 165           (remove-hook 'org-after-demote-entry-hook
 166                        'org-indent-refresh-section 'local)
 167           (and font-lock-mode (org-restart-font-lock))
 168           (redraw-display))))))
 169
 170
 171 (defface org-indent
 172   (org-compatible-face nil nil)
 173   "Face for outline indentation.
 174 The default is to make it look like whitespace.  But you may find it
 175 useful to make it evver so slightly different."
 176   :group 'org-faces)
 177
 178 (defun org-indent-indent-buffer ()
 179   "Add indentation properties for the whole buffer."
 180   (interactive)
 181   (when org-indent-mode
 182     (save-excursion
 183       (save-restriction
 184         (widen)
 185         (org-indent-remove-properties (point-min) (point-max))
 186         (org-indent-add-properties (point-min) (point-max))))))
 187
 188 (defun org-indent-remove-properties (beg end)
 189   "Remove indentations between BEG and END."
 190   (org-unmodified
 191    (remove-text-properties beg end '(line-prefix nil wrap-prefix nil))))
 192
 193 (defun org-indent-remove-properties-from-string (string)
 194   "Remove indentations between BEG and END."
 195   (remove-text-properties 0 (length string)
 196                           '(line-prefix nil wrap-prefix nil) string)
 197   string)
 198
 199 (defvar org-indent-outline-re (concat "^" org-outline-regexp)
 200   "Outline heading regexp.")
 201
 202 (defun org-indent-add-properties (beg end)
 203   "Add indentation properties between BEG and END.
 204 Assumes that BEG is at the beginning of a line."
 205   (when (or t org-indent-mode)
 206     (let (ov b e n level exit nstars)
 207       (org-unmodified
 208        (save-excursion
 209          (goto-char beg)
 210          (while (not exit)
 211            (setq e end)
 212            (if (not (re-search-forward org-indent-outline-re nil t))
 213                (setq e (point-max) exit t)
 214              (setq e (match-beginning 0))
 215              (if (>= e end) (setq exit t))
 216              (setq level (- (match-end 0) (match-beginning 0) 1))
 217              (setq nstars (- (* (1- level) org-indent-indentation-per-level)
 218                              (1- level)))
 219              (add-text-properties
 220               (point-at-bol) (point-at-eol)
 221               (list 'line-prefix
 222                     (aref org-indent-stars nstars)
 223                     'wrap-prefix
 224                     (aref org-indent-strings
 225                           (* level org-indent-indentation-per-level)))))
 226            (when (and b (> e b))
 227              (add-text-properties
 228               b  e (list 'line-prefix (aref org-indent-strings n)
 229                          'wrap-prefix (aref org-indent-strings n))))
 230            (setq b (1+ (point-at-eol))
 231                  n (* level org-indent-indentation-per-level))))))))
 232
 233 (defun org-indent-refresh-section ()
 234   "Refresh indentation properties in the current outline section.
 235 Point is assumed to be at the beginning of a headline."
 236   (interactive)
 237   (when org-indent-mode
 238     (let (beg end)
 239       (save-excursion
 240         (when (ignore-errors (org-back-to-heading))
 241           (setq beg (point))
 242           (setq end (or (save-excursion (or (outline-next-heading) (point)))))
 243           (org-indent-remove-properties beg end)
 244           (org-indent-add-properties beg end))))))
 245
 246 (defun org-indent-refresh-to (limit)
 247   "Refresh indentation properties in the current outline section.
 248 Point is assumed to be at the beginning of a headline."
 249   (interactive)
 250   (when org-indent-mode
 251     (let ((beg (point)) (end limit))
 252       (save-excursion
 253         (and (ignore-errors (org-back-to-heading t))
 254              (setq beg (point))))
 255       (org-indent-remove-properties beg end)
 256       (org-indent-add-properties beg end)))
 257   (goto-char limit))
 258
 259 (defun org-indent-refresh-subtree ()
 260   "Refresh indentation properties in the current outline subtree.
 261 Point is assumed to be at the beginning of a headline."
 262   (interactive)
 263   (when org-indent-mode
 264     (save-excursion
 265       (let (beg end)
 266         (setq beg (point))
 267         (setq end (save-excursion (org-end-of-subtree t t)))
 268         (org-indent-remove-properties beg end)
 269         (org-indent-add-properties beg end)))))
 270
 271 (defun org-indent-refresh-buffer ()
 272   "Refresh indentation properties in the current outline subtree.
 273 Point is assumed to be at the beginning of a headline."
 274   (interactive)
 275   (when org-indent-mode
 276     (org-indent-mode -1)
 277     (org-indent-mode 1)))
 278
 279 (provide 'org-indent)
 280
 281 ;;; org-indent.el ends here
 282
 283