lisp/org-indent.el

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