From 6fc221b4395555fe6ff9ae96a07972bfadee17e4 Mon Sep 17 00:00:00 2001 From: Karthik Chikmagalur Date: Sat, 15 Apr 2023 23:15:41 -0700 Subject: [PATCH] org-latex-preview: Add hooks for customization * lisp/org-latex-preview.el (org-latex-preview-process-finish-functions, org-latex-preview-update-overlay-hook, org-latex-preview-close-hook, org-latex-preview-open-hook, org-latex-preview--create-image-async, org-latex-preview-auto--handle-post-cursor, org-latex-preview--run-finish-functions): Add four hooks for better control of the LaTeX preview process. `org-latex-preview-process-finish-functions': Runs after the image conversion process. This is an abnormal hook: each hook function accepts the same arguments as other `org-async' callbacks for this process. `org-latex-preview-close-hook' and `org-latex-preview-open-hook': Run after a preview is closed (text hidden to reveal image) or opened (image hidden to reveal text) respectively. `org-latex-preview-update-overlay-functions': Run after a LaTeX preview overlay is updated with a new image. This is an abnormal hook: each hook function accepts one argument, the overlay that was updated. The "live" preview system introduced in the following commits uses these hooks, along with the facilities provided by `org-latex-preview-auto-mode'. In addition, these hooks will prove useful when writing code that reuse the API afforded by `org-latex-preview-place' to provide LaTeX previews for other major modes. --- lisp/org-latex-preview.el | 69 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/lisp/org-latex-preview.el b/lisp/org-latex-preview.el index 6ce36db95..a845d224a 100644 --- a/lisp/org-latex-preview.el +++ b/lisp/org-latex-preview.el @@ -248,6 +248,54 @@ be revealed when using `org-latex-preview-auto-mode'." :package-version '(Org . "9.7") :group 'org-latex-preview) +(defcustom org-latex-preview-process-finish-functions nil + "Abnormal hook run after preview generation. + +Each function in this hook is called with three arguments: + +- The exit-code of the preview generation process. More + specifically, this is the exit-code of the image-converter, the + final process in the chain of processes that generates a LaTeX + preview image. + +- The process buffer. + +- The processing-info plist, containing the state of the LaTeX + preview process. See `org-latex-preview--create-image-async' + for details. + +This hook can be used for introspection of or additional +processing after the LaTeX preview process." + :group 'org-latex-preview + :type 'hook) + +(defcustom org-latex-preview-update-overlay-functions nil + "Abnormal hook run after a preview-overlay is updated. + +Each function in this hook is called with one argument, the +overlay that was updated." + :group 'org-latex-preview + :type 'hook) + +(defcustom org-latex-preview-close-hook nil + "Hook run after placing a LaTeX preview image. + +This hook typically runs when the cursor is moved out of a LaTeX +fragment or environment with `org-latex-preview-auto-mode' +active, causing the display of text contents to be replaced by +the corresponding preview image." + :group 'org-latex-preview + :type 'hook) +(defcustom org-latex-preview-open-hook nil + "Hook run after hiding a LaTeX preview image. + +This hook typically runs when the cursor is moved into a LaTeX +fragment or environment with `org-latex-preview-auto-mode' +active, causing the display of the preview image to be replaced +by the corresponding LaTeX fragment text." + :group 'org-latex-preview + :type 'hook) + (defface org-latex-preview-processing-face '((t :inherit shadow)) "Face applied to LaTeX fragments for which a preview is being generated. @@ -441,7 +489,8 @@ overlay face is set to `org-latex-preview-processing-face'." (overlay-put ov 'before-string (propertize "!" 'display - `(left-fringe exclamation-mark error))))))) + `(left-fringe exclamation-mark error)))))) + (run-hook-with-args 'org-latex-preview-update-overlay-functions ov)) (defun org-latex-preview--face-around (start end) "Return the relevant face symbol around the region START to END. @@ -674,7 +723,8 @@ image and display its text." (overlay-put ov 'hidden-face f) (overlay-put ov 'face nil)) (org-latex-preview-auto--move-into ov) - (setq org-latex-preview-auto--from-overlay nil)))) + (setq org-latex-preview-auto--from-overlay nil) + (run-hooks 'org-latex-preview-open-hook)))) (defun org-latex-preview-auto--close-previous-overlay () "Close Org latex preview image overlays. @@ -697,7 +747,8 @@ image. The preview image is regenerated if necessary." (unless (eq f 'org-latex-preview-processing-face) (overlay-put ov 'face f)) (overlay-put ov 'hidden-face nil)) - (overlay-put ov 'display (overlay-get ov 'preview-image)))))) + (overlay-put ov 'display (overlay-get ov 'preview-image))) + (run-hooks 'org-latex-preview-close-hook)))) (defun org-latex-preview-auto--regenerate-overlay (ov) "Regenerate the LaTeX fragment under overlay OV." @@ -1301,6 +1352,12 @@ Returns a list of async tasks started." (format "Creating LaTeX preview images failed (exit code %%d). Please see %s for details" (propertize org-latex-preview--image-log 'face 'warning)) #'org-latex-preview--cleanup-callback)) + (when org-latex-preview-process-finish-functions + ;; Extra callbacks to run after image generation + (push #'org-latex-preview--run-finish-functions + (plist-get (cddr img-extract-async) :success)) + (push #'org-latex-preview--run-finish-functions + (plist-get (cddr img-extract-async) :failure))) (pcase processing-type ('dvipng (plist-put (cddr img-extract-async) :filter @@ -1322,6 +1379,12 @@ Returns a list of async tasks started." (plist-put (cddr tex-compile-async) :failure img-extract-async) (list (org-async-call tex-compile-async)))))) +(defun org-latex-preview--run-finish-functions (&rest args) + "Run hooks after preview image generation, with arguments ARGS." + (apply #'run-hook-with-args + 'org-latex-preview-process-finish-functions + args)) + (defun org-latex-preview--failure-callback (_exit _buf extended-info) "Clear overlays corresponding to previews that failed to generate.