Function: org-link-preview-region

org-link-preview-region is an interactive and byte-compiled function defined in ol.el.gz.

Signature

(org-link-preview-region &optional INCLUDE-LINKED REFRESH BEG END)

Documentation

Display link previews.

A previewable link type is one that has a :preview link parameter, see org-link-parameters.

By default, a file link or attachment is previewable if it follows either of these conventions:

  1. Its path is a file with an extension matching return value
     from image-file-name-regexp and it has no contents.

  2. Its description consists in a single link of the previous
     type. In this case, that link must be a well-formed plain
     or angle link, i.e., it must have an explicit "file" or
     "attachment" type.

File links are equipped with the keymap image-map.

When optional argument INCLUDE-LINKED is non-nil, links with a text description part will also be inlined. This can be nice for a quick look at those images, but it does not reflect what exported files will look like.

When optional argument REFRESH is non-nil, refresh existing images between BEG and END. This will create new image displays only if necessary.

BEG and END define the considered part. They default to the buffer boundaries with possible narrowing.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/ol.el.gz
(defun org-link-preview-region (&optional include-linked refresh beg end)
  "Display link previews.

A previewable link type is one that has a `:preview' link
parameter, see `org-link-parameters'.

By default, a file link or attachment is previewable if it
follows either of these conventions:

  1. Its path is a file with an extension matching return value
     from `image-file-name-regexp' and it has no contents.

  2. Its description consists in a single link of the previous
     type.  In this case, that link must be a well-formed plain
     or angle link, i.e., it must have an explicit \"file\" or
     \"attachment\" type.

File links are equipped with the keymap `image-map'.

When optional argument INCLUDE-LINKED is non-nil, links with a
text description part will also be inlined.  This can be nice for
a quick look at those images, but it does not reflect what
exported files will look like.

When optional argument REFRESH is non-nil, refresh existing
images between BEG and END.  This will create new image displays
only if necessary.

BEG and END define the considered part.  They default to the
buffer boundaries with possible narrowing."
  (interactive "P")
  (when refresh (org-link-preview-clear beg end))
  (org-with-point-at (or beg (point-min))
    (let ((case-fold-search t)
          preview-queue)
      ;; Collect links to preview
      (while (re-search-forward org-link-any-re end t)
        (forward-char -1)               ;ensure we are on the link
        (when-let*
            ((link (org-element-lineage (org-element-context) 'link t))
             (path (or
                    ;; Link without description or link with description
                    ;; that is requested to be previewed anyway.
                    (and (or include-linked
                             (not (org-element-contents-begin link)))
                         (org-element-property :path link))
                    ;; Special case: link with description where
                    ;; description is itself a sole link
                    (and (org-element-contents-begin link)
                         (setq link
                               (org-with-point-at (org-element-contents-begin link)
                                 (org-element-put-property
                                  (org-element-link-parser) :parent link)))
                         (org-element-type-p link 'link)
                         (equal (org-element-end link)
                                (org-element-contents-end
                                 (org-element-parent link)))
                         (org-element-property :path link))))
             (linktype (org-element-property :type link))
             (preview-func (org-link-get-parameter linktype :preview)))
          ;; Create an overlay to hold the preview
          (let ((ov (or (cdr-safe (get-char-property-and-overlay
                                   (org-element-begin link) 'org-image-overlay))
                        (make-overlay
                         (org-element-begin link)
                         (progn
                           (goto-char
                            (org-element-end link))
                           (unless (eolp) (skip-chars-backward " \t"))
                           (point))))))
            (overlay-put ov 'modification-hooks
                         (list 'org-link-preview--remove-overlay))
            (push ov org-link-preview-overlays)
            (push (list preview-func ov path link) preview-queue))))
      ;; Collect previews in buffer-local LIFO preview queue
      (setq org-link-preview--queue
            (nconc (nreverse preview-queue) org-link-preview--queue))
      ;; Run preview possibly asynchronously
      (when org-link-preview--queue
        (org-link-preview--process-queue (current-buffer))))))