org.el: Support auto display inline images when cycling

* lisp/org.el (org-toggle-inline-images): Support region.
(org-display-inline-images): Fix refresh argument logic.
(org-remove-inline-images): Support region.

* lisp/org-keys.el (org-toggle-inline-images): Update arguments.

* lisp/org-cycle.el (org-cycle-inline-images-display): Add new option to
control whether auto display inline images when cycling.
(org-cycle-display-inline-images): Add new hook function to auto display
inline images when cycling.
(org-cycle-hook): Add `org-cycle-display-inline-images' into cycling
hook by default.

* doc/org-manual.org (Exporting):
* etc/ORG-NEWS: Document the new option.

doc/org-manual.org

@@ -11489,6 +11489,12 @@ command:
   - When set to nil, try to get the width from an =#+ATTR.*= keyword
     and fall back on the original width if none is found.
 
+
+#+vindex: org-cycle-inline-images-display
+Inline images can also be displayed when cycling the folding state.
+When custom option ~org-cycle-inline-images-display~ is set, the
+visible inline images under subtree will be displayed automatically.
+
 ** Captions
 :PROPERTIES:
 :DESCRIPTION: Describe tables, images...

etc/ORG-NEWS

@@ -307,6 +307,13 @@ to pass the contents of a named code block as a string argument.
 The new property =ORG-IMAGE-ACTUAL-WIDTH= can override the global
 variable ~org-image-actual-width~ value for inline images display width.
 
+*** Outline cycling can now include inline image visibility
+
+New ~org-cycle-hook~ function ~org-cycle-display-inline-images~ for
+auto-displaying inline images in the visible parts of the subtree.
+This behavior is controlled by new custom option
+~org-cycle-inline-images-display~.
+
 *** New ~org-babel-tangle-finished-hook~ hook run at the very end of ~org-babel-tangle~
 
 This provides a proper counterpart to ~org-babel-pre-tangle-hook~, as

lisp/org-cycle.el

@@ -208,8 +208,9 @@ the values `folded', `children', or `subtree'."
   :type 'hook)
 
 (defcustom org-cycle-hook '(org-cycle-hide-archived-subtrees
-		   org-cycle-show-empty-lines
-		   org-cycle-optimize-window-after-visibility-change)
+                            org-cycle-show-empty-lines
+                            org-cycle-optimize-window-after-visibility-change
+                            org-cycle-display-inline-images)
   "Hook that is run after `org-cycle' has changed the buffer visibility.
 The function(s) in this hook must accept a single argument which indicates
 the new state that was set by the most recent `org-cycle' command.  The
@@ -229,6 +230,13 @@ normal outline commands like `show-all', but not with the cycling commands."
   :group 'org-cycle
   :type 'boolean)
 
+(defcustom org-cycle-inline-images-display nil
+  "Non-nil means auto display inline images under subtree when cycling."
+  :group 'org-startup
+  :group 'org-cycle
+  :package-version '(Org . "9.6")
+  :type 'boolean)
+
 (defvar org-cycle-tab-first-hook nil
   "Hook for functions to attach themselves to TAB.
 See `org-ctrl-c-ctrl-c-hook' for more information.
@@ -775,6 +783,32 @@ STATE should be one of the symbols listed in the docstring of
 		       "Subtree is archived and stays closed.  Use \
 `\\[org-cycle-force-archived]' to cycle it anyway."))))))
 
+(defun org-cycle-display-inline-images (state)
+  "Auto display inline images under subtree when cycling.
+It works when `org-cycle-inline-images-display' is non-nil."
+  (when org-cycle-inline-images-display
+    (pcase state
+      ('children
+       (org-with-wide-buffer
+        (org-narrow-to-subtree)
+        ;; If has nested headlines, beg,end only from parent headline
+        ;; to first child headline which reference to upper
+        ;; let-binding `org-next-visible-heading'.
+        (org-display-inline-images
+         nil nil
+         (point-min) (progn (org-next-visible-heading 1) (point)))))
+      ('subtree
+       (org-with-wide-buffer
+        (org-narrow-to-subtree)
+        ;; If has nested headlines, also inline display images under all sub-headlines.
+        (org-display-inline-images nil nil (point-min) (point-max))))
+      ('folded
+       (org-with-wide-buffer
+        (org-narrow-to-subtree)
+        (if (numberp (point-max))
+            (org-remove-inline-images (point-min) (point-max))
+          (ignore)))))))
+
 (provide 'org-cycle)
 
 ;;; org-cycle.el ends here

lisp/org-keys.el

@@ -204,7 +204,7 @@
 (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))
+(declare-function org-toggle-inline-images "org" (&optional include-linked 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" ())

lisp/org.el

@@ -16099,16 +16099,16 @@ SNIPPETS-P indicates if this is run to create snippet images for HTML."
 
 (defvar-local org-inline-image-overlays nil)
 
-(defun org-toggle-inline-images (&optional include-linked)
+(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'."
   (interactive "P")
   (if org-inline-image-overlays
       (progn
-	(org-remove-inline-images)
+	(org-remove-inline-images beg end)
 	(when (called-interactively-p 'interactive)
 	  (message "Inline image display turned off")))
-    (org-display-inline-images include-linked)
+    (org-display-inline-images include-linked nil beg end)
     (when (called-interactively-p 'interactive)
       (message (if org-inline-image-overlays
 		   (format "%d images displayed inline"
@@ -16198,8 +16198,8 @@ BEG and END define the considered part.  They default to the
 buffer boundaries with possible narrowing."
   (interactive "P")
   (when (display-graphic-p)
-    (unless refresh
-      (org-remove-inline-images)
+    (when refresh
+      (org-remove-inline-images beg end)
       (when (fboundp 'clear-image-cache) (clear-image-cache)))
     (let ((end (or end (point-max))))
       (org-with-point-at (or beg (point-min))
@@ -16349,11 +16349,16 @@ buffer boundaries with possible narrowing."
     (delete ov org-inline-image-overlays)
     (delete-overlay ov)))
 
-(defun org-remove-inline-images ()
+(defun org-remove-inline-images (&optional beg end)
   "Remove inline display of images."
   (interactive)
-  (mapc #'delete-overlay org-inline-image-overlays)
-  (setq org-inline-image-overlays nil))
+  (let* ((beg (or beg (point-min)))
+         (end (or end (point-max)))
+         (overlays (overlays-in beg end)))
+    (dolist (ov overlays)
+      (when (memq ov org-inline-image-overlays)
+        (setq org-inline-image-overlays (delq ov org-inline-image-overlays))
+        (delete-overlay ov)))))
 
 (defvar org-self-insert-command-undo-counter 0)
 (defvar org-speed-command nil)