[nongnu] elpa/annotate 265ac1a905 7/7: Merge pull request #150 from cage2/hide-annotation-text

[ELPA Syncer]

branch: elpa/annotate
commit 265ac1a9053795be34028c62f43adb09cf585864
Merge: e433ec6803 44349cef8b
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #150 from cage2/hide-annotation-text
    
    Hide annotation text
---
 Changelog   | 22 ++++++++++++++
 NEWS.org    |  7 +++++
 README.org  | 18 ++++++++----
 annotate.el | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++-----------
 4 files changed, 121 insertions(+), 22 deletions(-)

diff --git a/Changelog b/Changelog
index f7d035834b..8612619189 100644
--- a/Changelog
+++ b/Changelog
@@ -1,3 +1,25 @@
+2023-02-22 cage
+
+        * annotate.el:
+
+        - added command 'annotate-toggle-annotation-text';
+        - removed customizable variable 'annotate-hide-annotations-text'.
+        - wrapped raw chain manipulation with 'annotate-chain-last-ring' to
+        get the last segment of a chain.
+        - added missing docstrings.
+        - removed repeated code.
+
+2023-02-15 cage
+
+        * annotate.el:
+
+        - added a new command 'annotate-toggle-annotation-text' (and related
+        functions/variables).
+
+2023-02-03 cage
+
+        Merge pull request #146 from cage2/fix-annotate-shutdown
+
 2023-02-02 cage
 
         * annotate.el:
diff --git a/NEWS.org b/NEWS.org
index 2d70c3d121..6960eb09fa 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,3 +1,10 @@
+- 2023-02-22 v1.9.0 cage ::
+
+  This version added two new commands to hide/show the tannotation's text:
+
+  - annotate-toggle-annotation-text :: shows or hides annotation's text under 
cursor;
+  - annotate-toggle-all-annotations-text :: shows or hides the annotation's 
text in the whole buffer.
+
 - 2022-12-15 v1.8.5 cage ::
 
   This version fixed a regression that prevented to delete annotations
diff --git a/README.org b/README.org
index c461471be0..6a38d69a53 100644
--- a/README.org
+++ b/README.org
@@ -250,13 +250,19 @@ buffer) beyond the current cursor position.
 
 ** annotate-switch-db
 
-This command will ask the user for a new annotation database files,
-load it and refresh all the annotations contained in each buffer where
-annotate minor mode is active.
+   This command will ask the user for a new annotation database files,
+   load it and refresh all the annotations contained in each buffer where
+   annotate minor mode is active.
 
-See the docstring for more information and
-[[https://github.com/bastibe/annotate.el/issues/68][this thread]]
-for a possible workflow where this command could be useful.
+   See the docstring for more information and
+   [[https://github.com/bastibe/annotate.el/issues/68][this thread]]
+   for a possible workflow where this command could be useful.
+
+** annotate-toggle-annotation-text
+   Shows or hides annotation's text under cursor.
+
+** annotate-toggle-all-annotations-text
+   Shows or hides the annotation's text in the whole buffer.
 
 * More documentation
 
diff --git a/annotate.el b/annotate.el
index 6709f4df90..5115de718e 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.8.5
+;; Version: 1.9.0
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -58,7 +58,7 @@
 ;;;###autoload
 (defgroup annotate nil
   "Annotate files without changing them."
-  :version "1.8.5"
+  :version "1.9.0"
   :group 'text)
 
 (defvar annotate-mode-map
@@ -131,7 +131,8 @@ that Emacs passes to the diff program."
   :type 'boolean)
 
 (defcustom annotate-popup-warning-indirect-buffer t
-  "Whether an information popup message is shown when killing an annotated 
indirect buffer."
+  "Whether an information popup message is shown when killing an
+annotated indirect buffer."
   :type 'boolean)
 
 (defcustom annotate-integrate-marker " ANNOTATION: "
@@ -213,7 +214,7 @@ annotate-use-echo-area must be non nil"
 
 (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"
+annotate-print-annotation-under-cursor is non nil"
   :type 'string)
 
 (defcustom annotate-print-annotation-under-cursor-delay 0.5
@@ -240,6 +241,14 @@ annotate the whole line before (or after if the line is 
composed
 by the newline character only) instead."
   :type 'boolean)
 
+(defcustom annotate-search-region-lines-delta 2
+ "When the annotated file is out of sync with its annotation
+database the software looks for annotated text in the region with
+delta equals to the value of this variable. Units are in number
+of lines. The center of the region is the position of the
+annotation as defined in the database."
+  :type 'number)
+
 (defconst annotate-prop-chain-position
   'position)
 
@@ -289,14 +298,6 @@ summary window because does not exist or is in an 
unsupported
   '(".info" ".info.gz" ".gz")
  "The valid extension for files that contains info document.")
 
-(defcustom annotate-search-region-lines-delta 2
- "When the annotated file is out of sync with its annotation
-database the software looks for annotated text in the region with
-delta equals to the value of this variable. Units are in number
-of lines. The center of the region is the position of the
-annotation as defined in the database."
-  :type 'number)
-
 (defconst annotate-summary-list-prefix "    "
   "The string used as prefix for each text annotation item in summary window.")
 
@@ -331,7 +332,7 @@ annotation as defined in the database."
   "Prompt to be shown when asking for annotation deletion confirm.")
 
 (defconst annotate-message-annotation-loaded "Annotations loaded."
-  "The message shown when annotations has been loaded")
+  "The message shown when annotations has been loaded.")
 
 (defconst annotate-message-annotations-not-found "No annotations found."
   "The message shown when no annotations has been loaded from the database.")
@@ -339,7 +340,8 @@ annotation as defined in 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")
+  "The buffer local variable bound to a timer that is in charge to print
+the annotation under cursor on the echo area.")
 
 ;;;; custom errors
 
@@ -432,6 +434,10 @@ annotated text?
 See: `ANNOTATE-ANNOTATION-POSITION-POLICY'."
   (overlay-get annotation 'force-newline-policy))
 
+(defun annotate-chain-last-ring (chain)
+  "Get the last ring of `CHAIN'."
+  (car (last chain)))
+
 (defun annotate--remap-chain-pos (annotations)
   "Remap `ANNOTATIONS' as an annotation 'chain'.
 
@@ -522,6 +528,11 @@ local version (i.e. a different database for each 
annotated file"
       (setq-local annotate-file db-name))))
 
 (defun annotate-timer-print-annotation-function ()
+  "Print annotation under point in the minibuffer.
+Used by the timer set in `annotate--maybe-make-timer-print-annotation'.
+
+See also the customizable variables: `annotate-echo-annotation-timer' and
+`annotate-print-annotation-under-cursor'."
   (with-current-buffer (current-buffer)
     (when annotate-mode
       (when-let ((annotation (annotate-annotation-at (point))))
@@ -530,10 +541,14 @@ local version (i.e. a different database for each 
annotated file"
                  (overlay-get annotation 'annotation))))))
 
 (defun annotate-print-annotation-under-cursor-p ()
+  "Non nil if the user configured the package to print
+annotation's text in the minibuffer."
   (and annotate-use-echo-area
        annotate-print-annotation-under-cursor))
 
 (defun annotate--maybe-make-timer-print-annotation ()
+  "Set the timer to print the annotation's text in the minibuffer.
+Used when the mode is activated."
   (when (annotate-print-annotation-under-cursor-p)
     (setf annotate-echo-annotation-timer
           (run-with-idle-timer annotate-print-annotation-under-cursor-delay
@@ -541,6 +556,8 @@ local version (i.e. a different database for each annotated 
file"
                                #'annotate-timer-print-annotation-function))))
 
 (defun annotate--maybe-cancel-timer-print-annotation ()
+  "Cancel the timer to print the annotation's' text in the minibuffer.
+Used when the mode is deactivated."
   (when (and (annotate-print-annotation-under-cursor-p)
              annotate-echo-annotation-timer
              (timerp annotate-echo-annotation-timer))
@@ -823,6 +840,26 @@ specified by `FROM' and `TO'."
                         (goto-char (annotate-end-of-line-pos))
                         (annotate-annotate)))))))))))))))
 
+(defun annotate-toggle-annotation-text ()
+  "Hide annotation's text at current cursor's point, if such annotation 
exists."
+  (interactive)
+  (when-let* ((chain     (annotate-chain-at (point)))
+              (last-ring (annotate-chain-last-ring chain)))
+    (if (annotate-tail-overlay-hide-text-p last-ring)
+        (annotate-chain-show-text chain)
+      (annotate-chain-hide-text chain))
+    (font-lock-flush)))
+
+(defun annotate-toggle-all-annotations-text ()
+"Hide annototation's text in the whole buffer."
+  (interactive)
+  (let ((chains (annotate-annotations-chain-in-range 0 (buffer-size))))
+    (dolist (chain chains)
+      (if (annotate-tail-overlay-hide-text-p (annotate-chain-last-ring chain))
+          (annotate-chain-show-text chain)
+        (annotate-chain-hide-text chain))))
+  (font-lock-flush))
+
 (cl-defun annotate-goto-next-annotation (&key (startingp t))
   "Move point to the next annotation."
   (interactive)
@@ -1247,7 +1284,8 @@ a        a**"
             (eol                (progn (end-of-line) (point)))
             (annotation-text    "")
             (overlays           nil)
-            (annotation-counter 1))
+            (annotation-counter 1)
+            (hidden-text        nil))
         ;; include previous line if point is at bol:
         (when (null (overlays-in bol eol))
           (setq bol (1- bol)))
@@ -1299,7 +1337,11 @@ a        a**"
                                                   (length overlays))
                                                "\n"
                                              "")
-                                         "\n")))
+                                         "\n"))
+                 (last-ring-p          (annotate-chain-last-p ov))
+                 (tail-hidden-text-p   (and last-ring-p
+                                            (annotate-tail-overlay-hide-text-p 
ov))))
+            (setf hidden-text tail-hidden-text-p)
             (cl-incf annotation-counter)
             (overlay-put ov 'face face-highlight)
             (overlay-put ov 'annotation-face face)
@@ -1309,6 +1351,7 @@ a        a**"
                              'face
                              (overlay-get first-in-chain 'face))))
             (when (and (not annotate-use-echo-area)
+                       (not hidden-text)
                        (annotate-chain-last-p ov))
                 (when position-new-line-p
                   (setf prefix-first " \n"))
@@ -2011,6 +2054,27 @@ in a chain of annotations as last."
   "Find all annotation that are parts of the chain that overlaps at `POS'."
   (annotate-find-chain (annotate-annotation-at pos)))
 
+(defun annotate-chain-hide-text (chain)
+  "Sets an overlay properties of the last ring of `CHAIN' so that
+the annotation's text will not be rendered."
+  (let ((last-ring (annotate-chain-last-ring chain)))
+    (overlay-put last-ring 'hide-text t)))
+
+(defun annotate-chain-show-text (chain)
+  "Sets an overlay properties of the last ring of `CHAIN' so that
+the annotation's text will be rendered."
+  (let ((last-ring (annotate-chain-last-ring chain)))
+    (overlay-put last-ring 'hide-text nil)))
+
+(defun annotate-chain-hide-text-p (chain)
+"Non nil if the annotation's text must not be rendered."
+  (let ((last-ring (annotate-chain-last (cl-first chain))))
+    (annotate-tail-overlay-hide-text-p last-ring)))
+
+(defun annotate-tail-overlay-hide-text-p (overlay)
+  "Get the property for hiding the annotation text from `overlay'."
+  (overlay-get overlay 'hide-text))
+
 (defun annotate-create-annotation (start end annotation-text annotated-text)
   "Create a new annotation for selected region (from `START' to  `END'.