[nongnu] elpa/annotate 0c3342bd55 6/6: Merge pull request #137 from cage2/print-message-annotate-under-point

[ELPA Syncer]

branch: elpa/annotate
commit 0c3342bd55c827b8e4529fd5ee2aa40053a334f6
Merge: f166cca70b 3882a87839
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #137 from cage2/print-message-annotate-under-point
    
    Print message annotate under point
---
 Changelog   | 26 ++++++++++++++++++++++++++
 NEWS.org    | 11 +++++++++++
 README.org  | 10 ++++++++++
 annotate.el | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 101 insertions(+), 2 deletions(-)

diff --git a/Changelog b/Changelog
index 2216f61d62..7bf9626208 100644
--- a/Changelog
+++ b/Changelog
@@ -1,11 +1,37 @@
+2022-09-21 cage
+
+        * NEWS.org,
+        * README.org,
+        * annotate.el:
+
+        - 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.
+
+2022-09-16 cage
+
+
+        Merge pull request #135 from cage2/fix-closing-indirect-buffer
+        Merge branch 'master' into print-message-annotate-under-point
+
+2022-09-08 cage
+
+        * annotate.el:
+
+        - added idle timer to print annotation under point.
+
 2022-08-31 cage
 
+        * Changelog,
         * NEWS.org,
         * annotate.el:
 
         - updated, and added if missing, docstrings.
         - updated NEWS.org.
         - removed a duplicated label using a constant.
+        - updated changelog.
 
 2022-08-25 cage
 
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..c461471be0 100644
--- a/README.org
+++ b/README.org
@@ -226,6 +226,12 @@ 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~, after a delay (in seconds)
+defined by the variable ~annotate-print-annotation-under-cursor-delay~.
+
 Another alternative way to show annotations is provided by the command:
 ~annotate-summary-of-file-from-current-pos~.
 
@@ -235,6 +241,10 @@ 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-print-annotation-under-cursor-delay~
+     - ~annotate-summary-of-file-from-current-pos~.
 
 * Other commands
 
diff --git a/annotate.el b/annotate.el
index 121dc59be7..49a40b6168 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
@@ -201,8 +201,28 @@ 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-print-annotation-under-cursor-delay 0.5
+ "The delay (in seconds) after an annotation id printed in the
+minibuffer, when the pursor is placed over an annotated text.
+
+This variable works only if `annotate-print-annotation-under-cursor' is non 
nil"
+  :type 'float)
+
 (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
@@ -316,6 +336,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")
@@ -492,9 +517,35 @@ 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 annotate-print-annotation-under-cursor-delay
+                               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)
@@ -515,6 +566,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)