Function: allout-decorate-item-and-context

allout-decorate-item-and-context is a byte-compiled function defined in allout-widgets.el.gz.

Signature

(allout-decorate-item-and-context ITEM-WIDGET &optional REDECORATE BLANK-CONTAINER PARENT)

Documentation

Create or adjust widget decorations for ITEM-WIDGET and neighbors at point.

The neighbors include its siblings and parent.

ITEM-WIDGET can be a created or converted allout-item-widget.

If you're only trying to get or create a widget for an item, use allout-get-or-create-item-widget. If you have the item-widget, applying
:redecorate will do the right thing.

Optional BLANK-CONTAINER is for internal use. It is used to fabricate a container widget for an empty-bodied container, in the course of decorating a proper (non-container) item which starts at the beginning of the file.

Optional REDECORATE causes redecoration of the item-widget and its siblings, even if already decorated in this cycle of the command loop.

Optional PARENT, when provided, bypasses some navigation and computation necessary to obtain the parent of the items being processed.

We return the item-widget corresponding to the item at point.

Source Code

;; Defined in /usr/src/emacs/lisp/allout-widgets.el.gz
;;;_  : Item decoration
;;;_   > allout-decorate-item-and-context (item-widget &optional redecorate
;;;                                                   blank-container parent)
(defun allout-decorate-item-and-context (item-widget &optional redecorate
                                                     blank-container _parent)
  "Create or adjust widget decorations for ITEM-WIDGET and neighbors at point.

The neighbors include its siblings and parent.

ITEM-WIDGET can be a created or converted `allout-item-widget'.

If you're only trying to get or create a widget for an item, use
`allout-get-or-create-item-widget'.  If you have the item-widget, applying
:redecorate will do the right thing.

Optional BLANK-CONTAINER is for internal use.  It is used to fabricate a
container widget for an empty-bodied container, in the course of decorating
a proper (non-container) item which starts at the beginning of the file.

Optional REDECORATE causes redecoration of the item-widget and
its siblings, even if already decorated in this cycle of the command loop.

Optional PARENT, when provided, bypasses some navigation and computation
necessary to obtain the parent of the items being processed.

We return the item-widget corresponding to the item at point."

  (when (or redecorate
            (not (equal (widget-get item-widget :last-decorated-tick)
                        allout-command-counter)))
    (let* ((allout-inhibit-body-modification-hook t)
           (was-modified (buffer-modified-p))
           (was-point (point))
           prefix-start
           (is-container (or blank-container
                             (not (setq prefix-start (allout-goto-prefix)))
                             (< was-point prefix-start)))
           ;; steady-point (set in two steps) is reliable across parent
           ;; widget-creation.
           (steady-point (progn (if is-container (goto-char 1))
                                (point-marker)))
           (steady-point (progn (set-marker-insertion-type steady-point t)
                                steady-point))
           (parent (and (not is-container)
                        (allout-get-or-create-parent-widget)))
           successor-sibling
           doing-item
           reverse-siblings-chart
           (buffer-undo-list t))

      ;; At this point the parent is decorated and parent-flags indicate
      ;; its guide lines.  We will iterate over the siblings according to a
      ;; chart we create at the start, and going from last to first so we
      ;; don't have to worry about text displacement caused by widgetizing.

      (if is-container
          (progn (widget-put item-widget :is-container t)
                 (setq reverse-siblings-chart (list 1)))
        (let ((parent-position (widget-apply parent
                                             :actual-position :from)))
          (when parent-position
            (goto-char parent-position)))
        (if (widget-get parent :is-container)
            ;; `allout-goto-prefix' will go to first non-container item:
            (allout-goto-prefix)
          (allout-next-heading))
        (setq reverse-siblings-chart (list allout-recent-prefix-beginning))
        (while (allout-next-sibling)
          (push allout-recent-prefix-beginning reverse-siblings-chart)))

      (dolist (doing-at reverse-siblings-chart)
        (goto-char doing-at)
        (when allout-widgets-track-decoration
          (sit-for 0))

        (setq doing-item (if (= doing-at steady-point)
                             item-widget
                           (or (allout-get-item-widget)
                               (allout-new-item-widget))))

        (when (or redecorate (not (equal (widget-get doing-item
                                                     :last-decorated-tick)
                                         allout-command-counter)))
          (widget-apply doing-item :parse-item t blank-container)
          (widget-apply doing-item :decorate-item-span)

          (widget-apply doing-item :decorate-guides
                        parent (and successor-sibling t))
          (widget-apply doing-item :decorate-icon)
          (widget-apply doing-item :decorate-cue)
          (widget-apply doing-item :decorate-body)

          (widget-put doing-item :last-decorated-tick allout-command-counter))

        (setq successor-sibling doing-at))

      (set-buffer-modified-p was-modified)
      (goto-char steady-point)
      ;; must null the marker or the buffer gets clogged with impedance:
      (set-marker steady-point nil)

      item-widget)))