Re: [PATCH v4.0] Re: [PATCH] add a function to only refresh inline images under current headline instead of global buffer

[Ihor Radchenko]

"Christopher M. Miles" <numbchild@gmail.com> writes:

>> What about the following treatment of ARG:
>>
>> 1. No argument, no region selected :: toggle (display or hide dwim) images 
>> in current section 
>> 2. No argument, region selected: toggle images in region
>> 3. C-u argument :: toggle images in the whole buffer
>> 4. C-u C-u argument, no region selected :: unconditionally hide images in 
>> the buffer
>> 5. M-1 argument, no region selected :: display images in current section 
>> with INCLUDE-LINKED
>> 6. M-1 argument, region selected :: ... in region ...
>> 7. M-11 argument :: ... in the whole buffer ...
>> 8. Any other argument :: treat as INCLUDE-LINKED = t
>>
>> And please document all the new arguments in the manual and etc/ORG-NEWS 
>> file.
>
> I followed you upper 8 conditions to re-write my patch.
> Except the 8. condition I'm not sure I understand correctly.
> And I extend 1. condition to support the inline image link at point toggle 
> displaying.
> ...

I do not like the code repetitions in the patch and relying upon
`use-region-p' even for non-interactive use.

I am attaching a complete rewrite of your idea.
Please let me know if my patch does everything you want to include into
the command.

Note that I went with a new idea of introducing a branch new function
instead of changing `org-toggle-inline-images'.  This way, existing
users of `org-toggle-inline-images' will not be affected at all.  We are
just changing the default C-c C-x C-v binding.  This way, the breakage
is a little as possible.

>From 0a7b2a8850013be3ca916f4e5c67ac68b94feb25 Mon Sep 17 00:00:00 2001
Message-ID: 
<0a7b2a8850013be3ca916f4e5c67ac68b94feb25.1723457647.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Mon, 12 Aug 2024 12:11:17 +0200
Subject: [PATCH] org-toggle-inline-images-command: New command for C-c C-x C-v
 binding

* lisp/org.el (org-toggle-inline-images-command): New command to
toggle images.  Unlike the old `org-toggle-inline-image', it is more
flexible and default to toggling images at point/current entry.
* lisp/org-keys.el (org-mode-map): Bind C-c C-x C-v to the new
command.
* doc/org-manual.org (Images): Update the manual describing the new
command behaviour.
* etc/ORG-NEWS (=C-c C-x C-v= command toggling inline image display
has been reworked): Document the breaking change.

Link: https://list.orgmode.org/6461a84b.a70a0220.b6d36.5d00@mx.google.com/
---
 doc/org-manual.org | 17 +++++++---
 etc/ORG-NEWS       | 31 ++++++++++++++++++
 lisp/org-keys.el   |  4 +--
 lisp/org.el        | 82 +++++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 126 insertions(+), 8 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebcac..9365c66b10 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11806,14 +11806,21 @@ ** Images
 Such images can be displayed within the buffer with the following
 command:
 
-- {{{kbd(C-c C-x C-v)}}} (~org-toggle-inline-images~) ::
+- {{{kbd(C-c C-x C-v)}}} (~org-toggle-inline-images-command~) ::
 
   #+kindex: C-c C-x C-v
-  #+findex: org-toggle-inline-images
+  #+findex: org-toggle-inline-images-command
+  Toggle the inline display of linked images in current section or at
+  point.  With a prefix argument, toggle inline images in the whole
+  buffer.  With double prefix argument, hide all the images in buffer.
+
+  By default, only the image links without description are displayed.
+  You can force displaying all the images using numeric argument to
+  toggle all the images in current section (~1~ argument) or the whole
+  buffer (~11~ argument).
+
   #+vindex: org-startup-with-inline-images
-  Toggle the inline display of linked images.  When called with a
-  prefix argument, also display images that do have a link
-  description.  You can ask for inline images to be displayed at
+  You can ask for inline images to be displayed at
   startup by configuring the variable
   ~org-startup-with-inline-images~[fn:: The variable
   ~org-startup-with-inline-images~ can be set within a buffer with the
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 6f858f3ca7..533965311a 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -18,6 +18,37 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 # require user action for most Org mode users.
 # Sorted from most important to least important.
 
+*** =C-c C-x C-v= command toggling inline image display has been reworked
+
+Previously, =C-c C-x C-v= always toggled image display in the whole
+buffer (or narrowed part of the buffer).  With prefix argument, it
+also forced displaying image links with description.
+
+Now, =C-c C-x C-v= is bound to a new command
+~org-toggle-inline-images-command~, which uses different defaults:
+
+1. By default, it toggles image at point or, if there is no image at
+   point, images in current entry
+
+2. When region is active, it is honored
+
+3. =C-u= argument changed its meaning.  Now, it forces toggling images
+   in the whole buffer
+
+4. =C-u C-u= argument unconditionally hides all the images in buffer
+
+5. Displaying images over links with description can be forced using
+   numeric argument:
+   - ~C-u 1~ for toggling all images at point/current entry
+   - ~C-u 11~ for toggling all images in buffer
+
+The old ~org-toggle-inline-images~ command is still available.  You
+can bind it back to =C-c C-x C-v= by adding the following to you config:
+#+begin_src emacs-lisp
+(eval-after-load 'org-keys
+  (org-defkey org-mode-map (kbd "C-c C-x C-v") #'org-toggle-inline-images))
+#+end_src
+
 *** Org mode may throw an error when attempting to include remote unsafe 
resource noninteractively
 
 Previously, when ~org-resource-download-policy~ is ~ask~ (default),
diff --git a/lisp/org-keys.el b/lisp/org-keys.el
index edd4059fc6..1daedaae8c 100644
--- a/lisp/org-keys.el
+++ b/lisp/org-keys.el
@@ -218,7 +218,7 @@ (declare-function org-toggle-checkbox "org" (&optional 
toggle-presence))
 (declare-function org-toggle-radio-button "org" (&optional arg))
 (declare-function org-toggle-comment "org" ())
 (declare-function org-toggle-fixed-width "org" ())
-(declare-function org-toggle-inline-images "org" (&optional include-linked beg 
end))
+(declare-function org-toggle-inline-images-command "org" (&optional arg beg 
end))
 (declare-function org-latex-preview "org" (&optional arg))
 (declare-function org-toggle-narrow-to-subtree "org" ())
 (declare-function org-toggle-ordered-property "org" ())
@@ -618,7 +618,7 @@ (org-defkey org-mode-map (kbd "C-c C-x C-d") 
#'org-clock-display)
 (org-defkey org-mode-map (kbd "C-c C-x x") #'org-dynamic-block-insert-dblock)
 (org-defkey org-mode-map (kbd "C-c C-x C-u") #'org-dblock-update)
 (org-defkey org-mode-map (kbd "C-c C-x C-l") #'org-latex-preview)
-(org-defkey org-mode-map (kbd "C-c C-x C-v") #'org-toggle-inline-images)
+(org-defkey org-mode-map (kbd "C-c C-x C-v") 
#'org-toggle-inline-images-command)
 (org-defkey org-mode-map (kbd "C-c C-x C-M-v") #'org-redisplay-inline-images)
 (org-defkey org-mode-map (kbd "C-c C-x \\") #'org-toggle-pretty-entities)
 (org-defkey org-mode-map (kbd "C-c C-x C-b") #'org-toggle-checkbox)
diff --git a/lisp/org.el b/lisp/org.el
index bcab7ca860..39167c656f 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -16654,7 +16654,8 @@ (defun org-normalize-color (value)
 (defvar-local org-inline-image-overlays nil)
 ;; Preserve when switching modes or when restarting Org.
 ;; If we clear the overlay list and later enable Or mode, the existing
-;; image overlays will never be cleared by `org-toggle-inline-images'.
+;; image overlays will never be cleared by `org-toggle-inline-images'
+;; and `org-toggle-inline-images-command'.
 (put 'org-inline-image-overlays 'permanent-local t)
 
 (defun org--inline-image-overlays (&optional beg end)
@@ -16667,6 +16668,85 @@ (defun org--inline-image-overlays (&optional beg end)
       (when (memq ov org-inline-image-overlays)
         (push ov result)))))
 
+(defun org-toggle-inline-images-command (&optional arg beg end)
+  "Toggle display of inline images without description at point.
+
+When point is at an image link, toggle displaying that image.
+Otherwise, toggle displaying images in current entry.
+
+When region BEG..END is active, toggle displaying images in the
+region.
+
+With numeric prefix ARG 1, display images with description as well.
+
+With prefix ARG `\\[universal-argument]', toggle displaying images in
+the accessible portion of the buffer.  With numeric prefix ARG 11, do
+the same, but include images with description.
+
+With prefix ARG `\\[universal-argument] \\[universal-argument]', hide
+all the images in accessible portion of the buffer.
+
+This command is designed for interactive use.  From Elisp, you can
+also use `org-toggle-inline-images'."
+  (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-images
+          (lambda (&optional beg end scope force-remove)
+            (let* ((beg (or beg (point-min)))
+                   (end (or end (point-max)))
+                   (old (org--inline-image-overlays beg end))
+                   (scope (or scope (format "%d:%d" beg end))))
+              (if (or old force-remove)
+                  (progn
+                    (org-remove-inline-images beg end)
+                    (when interactive?
+                      (message
+                       "[%s] Inline image display turned off (removed %d 
images)"
+                       scope (length old))))
+               (org-display-inline-images include-linked t beg end)
+                (when interactive?
+                  (let ((new (org--inline-image-overlays beg end)))
+                    (message
+                     (if new
+                        (format "[%s] %d images displayed inline %s"
+                                scope (length new)
+                                 (if include-linked "(including images with 
description)"
+                                   ""))
+                      (format "[%s] No images to display inline" 
scope))))))))))
+    (cond
+     ((not (display-graphic-p))
+      (message "Your Emacs does not support displaying images!"))
+     ;; Region selected :: toggle images in region.
+     ((and beg end) (funcall toggle-images beg end "region"))
+     ;; C-u or C-11 argument :: toggle images in the whole buffer.
+     ((member arg '(11 (4))) (funcall toggle-images nil nil "buffer"))
+     ;; C-u C-u argument :: unconditionally hide images in the buffer.
+     ((equal arg '(16)) (funcall toggle-images nil nil "buffer" 'remove))
+     ;; Argument nil or 1, no region selected :: toggle (display or hide
+     ;; dwim) 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)
+            (funcall toggle-images
+                     (org-element-begin context)
+                     (org-element-end context)
+                     "image at point")
+          (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-images beg end "current section")))))
+     ;; Any other non-nil argument.
+     ((not (null arg)) (funcall toggle-images beg end "region")))))
+
 (defun org-toggle-inline-images (&optional include-linked beg end)
   "Toggle the display of inline images.
 INCLUDE-LINKED is passed to `org-display-inline-images'."
-- 
2.45.2

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>