[nongnu] elpa/annotate c210a75a25 3/6: - added a customizable variable to switch on and off the printing of

[ELPA Syncer]

branch: elpa/annotate
commit c210a75a2582bfd8e28f177747d3a9ec89fc2f3e
Author: cage <cage@invalid>
Commit: cage <cage@invalid>

    - added a customizable  variable to switch on and off  the printing of
      annotations in the minibuffer;
    - updated version number;
    - updated NEWS.org;
    - updated README.org.
---
 NEWS.org    | 11 +++++++++++
 README.org  |  8 ++++++++
 annotate.el | 56 +++++++++++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 64 insertions(+), 11 deletions(-)

diff --git a/NEWS.org b/NEWS.org
index fde5f0d69a..80eafc0d51 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,3 +1,14 @@
+- 2022-09-21 v1.8.0 cage ::
+
+  This version  allows printing  of the  annotation in  the minibuffer
+  when the cursor is placed over an annotated text region.
+
+  To  activate this  feature set  to non  nil the  values of  these two
+  customizable variables:
+
+  - ~annotate-use-echo-area~
+  - ~annotate-print-annotation-under-cursor~
+
 - 2022-08-02 v1.7.2 cage ::
 
   This version  removed an error  signalled when closing  an annotated
diff --git a/README.org b/README.org
index 707608b678..250960f06e 100644
--- a/README.org
+++ b/README.org
@@ -226,6 +226,11 @@ system's setup (see
 [[https://github.com/bastibe/annotate.el/pull/81][this pull request]]
 for a couple of examples.
 
+Moreover if ~annotate-use-echo-area~ and 
~annotate-print-annotation-under-cursor~
+value *both* non null, placing the cursor over an annotated text region will 
print
+the annotation's text in the minibuffer prefixed by the value of customizable 
variable
+~annotate-print-annotation-under-cursor-prefix~.
+
 Another alternative way to show annotations is provided by the command:
 ~annotate-summary-of-file-from-current-pos~.
 
@@ -235,6 +240,9 @@ buffer) beyond the current cursor position.
 
 **** related customizable variable
      - ~annotate-use-echo-area~
+     - ~annotate-print-annotation-under-cursor~
+     - ~annotate-print-annotation-under-cursor-prefix~
+     - ~annotate-summary-of-file-from-current-pos~.
 
 * Other commands
 
diff --git a/annotate.el b/annotate.el
index 27717d70d1..70ce49413a 100644
--- a/annotate.el
+++ b/annotate.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Bastian Bechtold <bastibe.dev@mailbox.org>, cage 
<cage-dev@twistfold.it>
 ;; URL: https://github.com/bastibe/annotate.el
 ;; Created: 2015-06-10
-;; Version: 1.7.2
+;; Version: 1.8.0
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -58,7 +58,7 @@
 ;;;###autoload
 (defgroup annotate nil
   "Annotate files without changing them."
-  :version "1.7.2"
+  :version "1.8.0"
   :group 'text)
 
 (defvar annotate-mode-map
@@ -70,15 +70,6 @@
     (define-key map (kbd "C-c [")   #'annotate-goto-previous-annotation)
     map))
 
-(defun annotate-timer-print-annotation ()
-  (with-current-buffer (current-buffer)
-    (when annotate-mode
-      (when-let ((annotation (annotate-annotation-at (point))))
-        (message (overlay-get annotation 'annotation))))))
-
-(defvar-local annotate-echo-annotation-timer
-  (run-with-idle-timer 0.1 t #'annotate-timer-print-annotation))
-
 ;;;###autoload
 (define-minor-mode annotate-mode
   "Toggle Annotate mode.
@@ -210,8 +201,21 @@ otherwise."
  "Whether annotation text should appear in the echo area only when mouse
 id positioned over the annotated text instead of positioning them in
 the the buffer (the default)."
+ :type 'boolean)
+
+(defcustom annotate-print-annotation-under-cursor nil
+  "Whether annotation text should appear in the minibuffer when
+the cursor is positioned over an annotated text (default: nil).
+
+Important note: for this changes to take effect also
+annotate-use-echo-area must be non nil"
   :type 'boolean)
 
+(defcustom annotate-print-annotation-under-cursor-prefix "ANNOTATION: "
+  "Prefix that is printed before annotation in the minibuffer when
+   annotate-print-annotation-under-cursor is non nil"
+  :type 'string)
+
 (defcustom annotate-warn-if-hash-mismatch t
  "Whether a warning message should be printed if a mismatch
 occurs, for an annotated file, between the hash stored in the
@@ -325,6 +329,11 @@ annotation as defined in the database."
 (defconst annotate-message-annotations-not-found "No annotations found."
   "The message shown when no annotations has been loaded from the database.")
 
+;;;; buffer locals variables
+
+(defvar-local annotate-echo-annotation-timer nil
+  "The buffer local variable bound to a timer that is in charge to print the 
annotation under cursor on the echo area")
+
 ;;;; custom errors
 
 (define-error 'annotate-error "Annotation error")
@@ -501,9 +510,33 @@ local version (i.e. a different database for each 
annotated file"
                 (db-name (annotate--filepath->local-database-name 
buffer-file-path)))
       (setq-local annotate-file db-name))))
 
+(defun annotate-timer-print-annotation-function ()
+  (with-current-buffer (current-buffer)
+    (when annotate-mode
+      (when-let ((annotation (annotate-annotation-at (point))))
+        (message "%s%s"
+                 annotate-print-annotation-under-cursor-prefix
+                 (overlay-get annotation 'annotation))))))
+
+(defun annotate-print-annotation-under-cursor-p ()
+  (and annotate-use-echo-area
+       annotate-print-annotation-under-cursor))
+
+(defun annotate--maybe-make-timer-print-annotation ()
+  (when (annotate-print-annotation-under-cursor-p)
+    (setf annotate-echo-annotation-timer
+          (run-with-idle-timer 0.1 t 
#'annotate-timer-print-annotation-function))))
+
+(defun annotate--maybe-cancel-timer-print-annotation ()
+  (when (and (annotate-print-annotation-under-cursor-p)
+             annotate-echo-annotation-timer
+             (timerp annotate-echo-annotation-timer))
+    (cancel-timer annotate-echo-annotation-timer)))
+
 (defun annotate-initialize ()
   "Load annotations and set up save and display hooks."
   (annotate--maybe-database-set-buffer-local)
+  (annotate--maybe-make-timer-print-annotation)
   (annotate-load-annotations)
   (add-hook 'kill-buffer-hook                 #'annotate-save-annotations t t)
   (add-hook 'kill-emacs-hook                  
#'annotate-save-all-annotated-buffers t nil)
@@ -524,6 +557,7 @@ local version (i.e. a different database for each annotated 
file"
 (defun annotate-shutdown ()
   "Clear annotations and remove save and display hooks."
   (annotate-clear-annotations)
+  (annotate--maybe-cancel-timer-print-annotation)
   (remove-hook 'kill-buffer-hook                 #'annotate-save-annotations t)
   (remove-hook 'kill-emacs-hook                  
#'annotate-save-all-annotated-buffers nil)
   (remove-hook 'window-size-change-functions     #'on-window-size-change t)