Function: org-link-preview

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

Signature

(org-link-preview &optional ARG BEG END)

Documentation

Toggle display of link previews in the buffer.

When region BEG..END is active, preview links in the region.

When point is at a link, display a preview for that link only. Otherwise, display previews for links in current entry.

With numeric prefix ARG 1, also preview links with description in the active region, at point or in the current section.

With prefix ARG C-u (universal-argument), clear link previews at point or in the current entry.

With prefix ARG C-u (universal-argument) C-u (universal-argument),
 display link previews in the accessible portion of the
 buffer. With numeric prefix ARG 11, do the same, but include
 links with descriptions.

With prefix ARG C-u (universal-argument) C-u (universal-argument) C-u (universal-argument), hide all link previews in the accessible portion of the buffer.

This command is designed for interactive use. From Elisp, you can also use org-link-preview-region.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/ol.el.gz
;;;###autoload
(defun org-link-preview (&optional arg beg end)
  "Toggle display of link previews in the buffer.

When region BEG..END is active, preview links in the
region.

When point is at a link, display a preview for that link only.
Otherwise, display previews for links in current entry.

With numeric prefix ARG 1, also preview links with description in
the active region, at point or in the current section.

With prefix ARG `\\[universal-argument]', clear link previews at
point or in the current entry.

With prefix ARG `\\[universal-argument] \\[universal-argument]',
 display link previews in the accessible portion of the
 buffer.  With numeric prefix ARG 11, do the same, but include
 links with descriptions.

With prefix ARG `\\[universal-argument] \\[universal-argument] \\[universal-argument]',
hide all link previews in the accessible portion of the buffer.

This command is designed for interactive use.  From Elisp, you can
also use `org-link-preview-region'."
  (interactive (cons current-prefix-arg
                     (when (use-region-p)
                       (list (region-beginning) (region-end)))))
  (let* ((include-linked
          (cond
           ((member arg '(nil (4) (16)) ) nil)
           ((member arg '(1 11)) 'include-linked)
           (t 'include-linked)))
         (interactive? (called-interactively-p 'any))
         (toggle-previews
          (lambda (&optional beg end scope remove)
            (let* ((beg (or beg (point-min)))
                   (end (or end (point-max)))
                   (old (org-link-preview--get-overlays beg end))
                   (scope (or scope (format "%d:%d" beg end))))
              (if remove
                  (progn
                    (org-link-preview-clear beg end)
                    (when interactive?
                      (message
                       "[%s] Inline link previews turned off (removed %d images)"
                       scope (length old))))
                (org-link-preview-region include-linked t beg end)
                (when interactive?
                  (let ((new (org-link-preview--get-overlays beg end)))
                    (message
                     (if new
                         (format "[%s] Displaying %d images inline %s"
                                 scope (length new)
                                 (if include-linked "(including images with description)"
                                   ""))
                       (if (equal scope "buffer")
                           (format "[%s] No images to display inline" scope)
                         (format
                          (substitute-command-keys
                           "[%s] No images to display inline.  Use `\\[universal-argument] \\[universal-argument]' or 11 argument to preview the whole buffer")
                          scope)))))))))))
    (cond
     ;; Region selected :: display previews in region.
     ((and beg end)
      (funcall toggle-previews beg end "region"
               (and (equal arg '(4)) 'remove)))
     ;; C-u argument: clear image at point or in entry
     ((equal arg '(4))
      (if-let* ((ov (cdr (get-char-property-and-overlay
                         (point) 'org-image-overlay))))
          ;; clear link preview at point
          (funcall toggle-previews
                   (overlay-start ov) (overlay-end ov)
                   "preview at point" 'remove)
        ;; Clear link previews in entry
        (funcall toggle-previews
                 (if (org-before-first-heading-p) (point-min)
                   (save-excursion
                     (org-with-limited-levels (org-back-to-heading t) (point))))
                 (org-with-limited-levels (org-entry-end-position))
                 "current section" 'remove)))
     ;; C-u C-u or C-11 argument :: display images in the whole buffer.
     ((member arg '(11 (16))) (funcall toggle-previews nil nil "buffer"))
     ;; C-u C-u C-u argument :: unconditionally hide images in the buffer.
     ((equal arg '(64)) (funcall toggle-previews nil nil "buffer" 'remove))
     ;; Argument nil or 1, no region selected :: display images in
     ;; current section or image link at point.
     ((and (member arg '(nil 1)) (null beg) (null end))
      (let ((context (org-element-context)))
        ;; toggle display of inline image link at point.
        (if (org-element-type-p context 'link)
            (let* ((ov (cdr-safe (get-char-property-and-overlay
                                  (point) 'org-image-overlay)))
                   (remove? (and ov (memq ov org-link-preview-overlays)
                                 'remove)))
              (funcall toggle-previews
                       (org-element-begin context)
                       (org-element-end context)
                       "image at point" remove?))
          (let ((beg (if (org-before-first-heading-p) (point-min)
                       (save-excursion
                         (org-with-limited-levels (org-back-to-heading t) (point)))))
                (end (org-with-limited-levels (org-entry-end-position))))
            (funcall toggle-previews beg end "current section")))))
     ;; Any other non-nil argument.
     ((not (null arg)) (funcall toggle-previews beg end "region")))))