[elpa] externals/which-key 42a2505 14/51: Rework implementation of manual updating

[Stefan Monnier]

branch: externals/which-key
commit 42a25055163141165aa0269dbca69735e704825c
Author: Justin Burkett <justin@burkett.cc>
Commit: Justin Burkett <justin@burkett.cc>

    Rework implementation of manual updating
    
    Instead of having people mess with prefix-help-command, use a new variable
    which-key-show-early-on-C-h and control everything through
    which-key-C-h-dispatch.
---
 README.org   |  14 +++----
 which-key.el | 120 +++++++++++++++++++++++++++++++----------------------------
 2 files changed, 70 insertions(+), 64 deletions(-)

diff --git a/README.org b/README.org
index ee57388..b21711f 100644
--- a/README.org
+++ b/README.org
@@ -3,7 +3,7 @@
 
 ** Recent Changes
 
-*** 2019-07-31: Added =which-key-manual-update=
+*** 2019-08-01: Added =which-key-show-early-on-C-h=
     Allows one to trigger =which-key= on demand, rather than automatically. See
     the docstring and [[#manual-activation][Manual Activation]].
 
@@ -28,7 +28,7 @@
 ** Table of Contents                                                  :TOC_3:
 - [[#which-key][which-key]]
   - [[#recent-changes][Recent Changes]]
-    - [[#2019-07-31-added-which-key-manual-update][2019-07-31: Added 
=which-key-manual-update=]]
+    - [[#2019-08-01-added-which-key-show-early-on-c-h][2019-08-01: Added 
=which-key-show-early-on-C-h=]]
     - [[#2017-12-13-added-which-key-enable-extended-define-key][2017-12-13: 
Added =which-key-enable-extended-define-key=]]
     - [[#2017-11-13-added-which-key-show-major-mode][2017-11-13: Added 
=which-key-show-major-mode=]]
   - [[#introduction][Introduction]]
@@ -142,13 +142,13 @@
    along the following lines
 
    #+BEGIN_SRC emacs-lisp
-     ;; make sure which-key doesn't show normally
-     (setq which-key-idle-delay 1000)
-     ;; which-key-manual-update uses this variable to control refreshing the
-     ;; which-key buffer after new keypresses
+     ;; Allow C-h to trigger which-key before it is done automatically
+     (setq which-key-show-early-on-C-h t)
+     ;; make sure which-key doesn't show normally but refreshes quickly after 
it is
+     ;; triggered.
+     (setq which-key-idle-delay 10000)
      (setq which-key-idle-secondary-delay 0.05)
      (which-key-mode)
-     (setq prefix-help-command 'which-key-manual-update)
    #+END_SRC
 
    This will prevent which-key from showing automatically, and allow you to use
diff --git a/which-key.el b/which-key.el
index 8937436..7a495ec 100644
--- a/which-key.el
+++ b/which-key.el
@@ -412,6 +412,21 @@ prefixes in `which-key-paging-prefixes'"
   :group 'which-key
   :type 'boolean)
 
+(defcustom which-key-show-early-on-C-h nil
+  "Show the which-key buffer before if C-h is pressed in the
+middle of a prefix before the which-key buffer would normally be
+triggered through the idle delay. If combined with the following
+settings, which-key will effectively only show when triggered
+\"manually\" using C-h.
+
+\(setq `which-key-idle-delay' 10000)
+\(setq `which-key-idle-secondary-delay' 0.05)
+
+Note that `which-key-idle-delay' should be set before turning on
+`which-key-mode'. "
+  :group 'which-key
+  :type 'boolean)
+
 (defcustom which-key-is-verbose nil
   "Whether to warn about potential mistakes in configuration."
   :group 'which-key
@@ -791,7 +806,8 @@ problems at github. If DISABLE is non-nil disable support."
           (which-key--setup-echo-keystrokes))
         (unless (member prefix-help-command which-key--paging-functions)
           (setq which-key--prefix-help-cmd-backup prefix-help-command))
-        (when which-key-use-C-h-commands
+        (when (or which-key-use-C-h-commands
+                  which-key-show-early-on-C-h)
           (setq prefix-help-command #'which-key-C-h-dispatch))
         (when which-key-show-remaining-keys
           (add-hook 'pre-command-hook #'which-key--lighter-restore))
@@ -2345,40 +2361,52 @@ PREFIX should be a string suitable for `kbd'."
 `which-key-C-h-map'. This command is always accessible (from any
 prefix) if `which-key-use-C-h-commands' is non nil."
   (interactive)
-  (if (not (which-key--popup-showing-p))
-      (which-key-show-standard-help)
-    (let* ((prefix-keys (which-key--current-key-string))
-           (full-prefix (which-key--full-prefix prefix-keys current-prefix-arg 
t))
-           (prompt (concat (when (string-equal prefix-keys "")
-                             (which-key--propertize
-                              (concat " "
-                                      (which-key--pages-prefix-title
-                                       which-key--pages-obj))
-                              'face 'which-key-note-face))
-                           full-prefix
-                           (which-key--propertize
-                            (substitute-command-keys
-                             (concat
-                              " \\<which-key-C-h-map>"
-                              " \\[which-key-show-next-page-cycle]"
-                              which-key-separator "next-page,"
-                              " \\[which-key-show-previous-page-cycle]"
-                              which-key-separator "previous-page,"
-                              " \\[which-key-undo-key]"
-                              which-key-separator "undo-key,"
-                              " \\[which-key-toggle-docstrings]"
-                              which-key-separator "toggle-docstrings,"
-                              " \\[which-key-show-standard-help]"
-                              which-key-separator "help,"
-                              " \\[which-key-abort]"
-                              which-key-separator "abort"
-                              " 1..9"
-                              which-key-separator "digit-arg"))
-                            'face 'which-key-note-face)))
-           (key (string (read-key prompt)))
-           (cmd (lookup-key which-key-C-h-map key))
-           (which-key-inhibit t))
-      (if cmd (funcall cmd key) (which-key-turn-page 0)))))
+  (cond ((and (not (which-key--popup-showing-p))
+              which-key-show-early-on-C-h)
+         (let* ((current-prefix
+                 (butlast
+                  (listify-key-sequence (which-key--this-command-keys)))))
+           (which-key-reload-key-sequence current-prefix)
+           (if which-key-idle-secondary-delay
+               (which-key--start-timer which-key-idle-secondary-delay t)
+             (which-key--start-timer 0.05 t))))
+        ((not (which-key--popup-showing-p))
+         (which-key-show-standard-help))
+        (t
+         (if (not (which-key--popup-showing-p))
+             (which-key-show-standard-help)
+           (let* ((prefix-keys (which-key--current-key-string))
+                  (full-prefix (which-key--full-prefix prefix-keys 
current-prefix-arg t))
+                  (prompt (concat (when (string-equal prefix-keys "")
+                                    (which-key--propertize
+                                     (concat " "
+                                             (which-key--pages-prefix-title
+                                              which-key--pages-obj))
+                                     'face 'which-key-note-face))
+                                  full-prefix
+                                  (which-key--propertize
+                                   (substitute-command-keys
+                                    (concat
+                                     " \\<which-key-C-h-map>"
+                                     " \\[which-key-show-next-page-cycle]"
+                                     which-key-separator "next-page,"
+                                     " \\[which-key-show-previous-page-cycle]"
+                                     which-key-separator "previous-page,"
+                                     " \\[which-key-undo-key]"
+                                     which-key-separator "undo-key,"
+                                     " \\[which-key-toggle-docstrings]"
+                                     which-key-separator "toggle-docstrings,"
+                                     " \\[which-key-show-standard-help]"
+                                     which-key-separator "help,"
+                                     " \\[which-key-abort]"
+                                     which-key-separator "abort"
+                                     " 1..9"
+                                     which-key-separator "digit-arg"))
+                                   'face 'which-key-note-face)))
+                  (key (string (read-key prompt)))
+                  (cmd (lookup-key which-key-C-h-map key))
+                  (which-key-inhibit t))
+             (if cmd (funcall cmd key) (which-key-turn-page 0)))))))
 
 ;;; Update
 
@@ -2584,28 +2612,6 @@ Finally, show the buffer."
                           (kbd which-key--god-mode-key-string))))
     this-command-keys))
 
-;;;###autoload
-(defun which-key-manual-update ()
-  "Force which-key update.
-
-This command is intended to be used for `prefix-help-command'. An
-example configuration for using this command is the following.
-
-\(setq which-key-idle-delay 1000)
-\(setq which-key-idle-secondary-delay 0.05)
-\(which-key-mode)
-\(setq prefix-help-command 'which-key-manual-update)"
-  (interactive)
-  (if (which-key--popup-showing-p)
-      (which-key-C-h-dispatch)
-    (let* ((current-prefix
-            (butlast
-             (listify-key-sequence (which-key--this-command-keys)))))
-      (which-key-reload-key-sequence current-prefix)
-      (if which-key-idle-secondary-delay
-          (which-key--start-timer which-key-idle-secondary-delay t)
-        (which-key--start-timer 0.05 t)))))
-
 (defun which-key--update ()
   "Function run by timer to possibly trigger
 `which-key--create-buffer-and-show'."