Function: allout-widgets-mode

allout-widgets-mode is an autoloaded, interactive and byte-compiled function defined in allout-widgets.el.gz.

Signature

(allout-widgets-mode &optional ARG)

Documentation

Toggle Allout Widgets mode.

This is a minor mode. If called interactively, toggle the Allout-Widgets mode mode. If the prefix argument is positive, enable the mode, and if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is toggle. Enable the mode if ARG is nil, omitted, or is a positive number. Disable the mode if ARG is a negative number.

To check whether the minor mode is enabled in the current buffer, evaluate allout-widgets-mode(var)/allout-widgets-mode(fun).

The mode's hook is called both when the mode is enabled and when it is disabled.

Allout Widgets mode is an extension of Allout mode that provides graphical decoration of outline structure. It is meant to operate along with allout-mode(var)/allout-mode(fun), via allout-mode-hook.

The graphics include:

- guide lines connecting item bullet-icons with those of their subitems.

- icons for item bullets, varying to indicate whether or not the item
  has subitems, and if so, whether or not the item is expanded.

- cue area between the bullet-icon and the start of the body headline,
  for item numbering, encryption indicator, and distinctive bullets.

The bullet-icon and guide line graphics provide keybindings and mouse bindings for easy outline navigation and exposure control, extending outline hot-spot navigation (see allout-mode(var)/allout-mode(fun)).

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/allout-widgets.el.gz
;;;_  . mode hookup
;;;_   > define-minor-mode allout-widgets-mode (arg)
;;;###autoload
(define-minor-mode allout-widgets-mode
  "Toggle Allout Widgets mode.

Allout Widgets mode is an extension of Allout mode that provides
graphical decoration of outline structure.  It is meant to
operate along with `allout-mode', via `allout-mode-hook'.

The graphics include:

- guide lines connecting item bullet-icons with those of their subitems.

- icons for item bullets, varying to indicate whether or not the item
  has subitems, and if so, whether or not the item is expanded.

- cue area between the bullet-icon and the start of the body headline,
  for item numbering, encryption indicator, and distinctive bullets.

The bullet-icon and guide line graphics provide keybindings and mouse
bindings for easy outline navigation and exposure control, extending
outline hot-spot navigation (see `allout-mode')."

  :lighter nil
  :keymap nil

  ;; define-minor-mode handles any provided argument according to emacs
  ;; minor-mode conventions - '(elisp) Minor Mode Conventions' - and sets
  ;; allout-widgets-mode accordingly *before* running the body code, so we
  ;; cue on that.
  (if allout-widgets-mode
      ;; Activating:
      (progn
        (allout-add-resumptions
         ;; XXX user may need say in line-truncation/hscrolling - an option
         ;;     that abstracts mode.
         ;; truncate text lines to keep guide lines intact:
         '(truncate-lines t)
         ;; and enable autoscrolling to ease view of text
         '(auto-hscroll-mode t)
         '(line-move-ignore-fields t)
         '(widget-push-button-prefix "")
         '(widget-push-button-suffix "")
         ;; allout-escaped-prefix-regexp depends on allout-regexp:
         (list 'allout-escaped-prefix-regexp (concat "\\(\\\\\\)"
                                                     "\\(" allout-regexp "\\)")))
        (allout-add-resumptions
         (list 'allout-widgets-tally allout-widgets-tally)
         (list 'allout-widgets-escapes-sanitization-regexp-pair
               (list (concat "\\(\n\\|\\`\\)"
                             allout-escaped-prefix-regexp
                             )
                     ;; Include everything but the escape symbol.
                     "\\1\\3"))
         )

        (add-hook 'after-change-functions #'allout-widgets-after-change-handler
                  nil t)

        (allout-setup-text-properties)
        (add-to-invisibility-spec '(allout-torso . t))
        (add-to-invisibility-spec 'allout-escapes)

        (let ((as-parent (if (current-local-map)
                             (make-composed-keymap (current-local-map)
                                                   (current-global-map))
                           (current-global-map))))
          (set-keymap-parent allout-item-body-keymap as-parent)
          ;; allout-cue-span-keymap uses allout-item-icon-keymap as parent.
          (set-keymap-parent allout-item-icon-keymap as-parent))

        (add-hook 'allout-exposure-change-functions
                  #'allout-widgets-exposure-change-recorder nil 'local)
        (add-hook 'allout-structure-added-functions
                  #'allout-widgets-additions-recorder nil 'local)
        (add-hook 'allout-structure-deleted-functions
                  #'allout-widgets-deletions-recorder nil 'local)
        (add-hook 'allout-structure-shifted-functions
                  #'allout-widgets-shifts-recorder nil 'local)
        (add-hook 'allout-after-copy-or-kill-hook
                  #'allout-widgets-after-copy-or-kill-function nil 'local)
        (add-hook 'allout-post-undo-hook
                  #'allout-widgets-after-undo-function nil 'local)

        (add-hook 'before-change-functions
                  #'allout-widgets-before-change-handler nil 'local)
        (add-hook 'post-command-hook #'allout-widgets-post-command-business
                  nil 'local)
        (add-hook 'pre-command-hook #'allout-widgets-pre-command-business
                  nil 'local)

        ;; init the widgets tally for debugging:
        (if (not allout-widgets-tally)
            (setq allout-widgets-tally (make-hash-table
                                        :test 'eq :weakness 'key)))
        ;; add tally count display on minor-mode-alist just after
        ;; allout-mode entry.
        ;; (we use ternary condition form to keep condition simple for deletion.)
        (let* ((mode-line-entry '(allout-widgets-mode-inhibit ""
                                                              (:eval (allout-widgets-tally-string))))
               (associated (assoc (car mode-line-entry) minor-mode-alist))
               ;; need location for it only if not already present:
               (after (and (not associated)
                           (memq (assq 'allout-mode minor-mode-alist) minor-mode-alist))))
          (if after
              (rplacd after (cons mode-line-entry (cdr after)))))
        (allout-widgets-prepopulate-buffer)
        t)
    ;; Deactivating:
    (let ((inhibit-read-only t)
          (was-modified (buffer-modified-p)))

      (allout-widgets-undecorate-region (point-min)(point-max))
      (remove-from-invisibility-spec '(allout-torso . t))
      (remove-from-invisibility-spec 'allout-escapes)

      (remove-hook 'after-change-functions
                   #'allout-widgets-after-change-handler 'local)
      (remove-hook 'allout-exposure-change-functions
                   #'allout-widgets-exposure-change-recorder 'local)
      (remove-hook 'allout-structure-added-functions
                   #'allout-widgets-additions-recorder 'local)
      (remove-hook 'allout-structure-deleted-functions
                   #'allout-widgets-deletions-recorder 'local)
      (remove-hook 'allout-structure-shifted-functions
                   #'allout-widgets-shifts-recorder 'local)
      (remove-hook 'allout-after-copy-or-kill-hook
                   #'allout-widgets-after-copy-or-kill-function 'local)
      (remove-hook 'before-change-functions
                   #'allout-widgets-before-change-handler 'local)
      (remove-hook 'post-command-hook
                   #'allout-widgets-post-command-business 'local)
      (remove-hook 'pre-command-hook
                   #'allout-widgets-pre-command-business 'local)
      (assq-delete-all 'allout-widgets-mode-inhibit minor-mode-alist)
      (set-buffer-modified-p was-modified))))