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