branch: externals/mct
commit 57cd47d6dcafc01e38194e737ccf0b7049637474
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Expand mct-live-update; update documentation
---
README.org | 33 ++++++++++++++++++++++-----
mct.el | 75 ++++++++++++++++++++++++++++++++++++++++++++------------------
2 files changed, 80 insertions(+), 28 deletions(-)
diff --git a/README.org b/README.org
index 433dbc3..bb30f17 100644
--- a/README.org
+++ b/README.org
@@ -90,18 +90,39 @@ a blocklist and a passlist for commands are on offer:
#+vindex: mct-completion-blocklist
+ The blocklist (~mct-completion-blocklist~) disables the live-updating
- functionality for the commands specified therein.
+ functionality for the functions specified therein.
#+vindex: mct-completion-passlist
+ The passlist (~mct-completion-passlist~) always shows the Completions'
- buffer for the designated command without accounting for the minimum
+ buffer for the designated function without accounting for the minimum
input threshold.
#+vindex: mct-live-completion
-To inhibit live completion in the first place, ~mct-live-completion~
-can be set to nil. Given this customization, the Completions' buffern
-is only displayed when requested manually. ~mct-completion-passlist~
-takes precedence over this option.
+The user option ~mct-live-completion~ controls the overall behaviour of
+the Completions' buffer:
+
++ When nil, the user has to manually request completions, using the
+ regular activating commands. The Completions' buffer is never updated
+ live to match user input. Updating has to be handled manually. This
+ is like the out-of-the-box minibuffer completion experience.
+
++ When set to the value =visible=, the Completions' buffer is live
+ updated only if it is visible. The actual display of the completions
+ is still handled manually. For this reason, the =visible= style does
+ not read the ~mct-minimum-input~, meaning that it will always try to
+ live update the visible completions, regardless of input length.
+
++ When non-nil (the default), the Completions' buffer is automatically
+ displayed once the ~mct-minimum-input~ is met and is hidden once the
+ input drops below that threshold. While visible, the buffer is
+ updated live to match the user input.
+
++ Note that every function in the ~mct-completion-passlist~ ignores this
+ option altogether. This means that every such command will always
+ show the Completions' buffer automatically and will always update its
+ contents live. Same principle for every function declared in the
+ ~mct-completion-blocklist~, which will always disable both the automatic
+ display and live updating of the Completions' buffer.
Other customisations:
diff --git a/mct.el b/mct.el
index 7fde3cb..ea89f9b 100644
--- a/mct.el
+++ b/mct.el
@@ -72,15 +72,37 @@ Only works when variable `file-name-shadow-mode' is
non-nil."
:group 'mct)
(defcustom mct-live-completion t
- "Automatically display the Completions buffer.
-
-When disabled, the user has to manually request completions,
-using the regular activating commands. Note that
-`mct-completion-passlist' overrides this option, while taking
-precedence over `mct-completion-blocklist'.
-
-Live updating is subject to `mct-minimum-input'."
- :type 'boolean
+ "Control auto-display and live-update of Completions' buffer.
+
+When nil, the user has to manually request completions, using the
+regular activating commands. The Completions' buffer is never
+updated live to match user input. Updating has to be handled
+manually. This is like the out-of-the-box minibuffer completion
+experience.
+
+When set to the value `visible', the Completions' buffer is live
+updated only if it is visible. The actual display of the
+completions is still handled manually. For this reason, the
+`visible' style does not read the `mct-minimum-input', meaning
+that it will always try to live update the visible completions,
+regardless of input length.
+
+When non-nil (the default), the Completions' buffer is
+automatically displayed once the `mct-minimum-input' is met and
+is hidden once the input drops below that threshold. While
+visible, the buffer is updated live to match the user input.
+
+Note that every function in the `mct-completion-passlist' ignores
+this option altogether. This means that every such command will
+always show the Completions' buffer automatically and will always
+update its contents live. Same principle for every function
+declared in the `mct-completion-blocklist', which will always
+disable both the automatic display and live updating of the
+Completions' buffer."
+ :type '(choice
+ (const :tag "Disable live-updating" nil)
+ (const :tag "Enable live-updating" t)
+ (const :tag "Live update only visible Completions" 'visible))
:group 'mct)
(defcustom mct-minimum-input 3
@@ -99,24 +121,25 @@ Set this to 0 to disable the delay."
:group 'mct)
(defcustom mct-completion-blocklist nil
- "Commands that do not do live updating of completions.
-
-A less drastic measure is to set `mct-minimum-input'
-to an appropriate value.
+ "Functions that disable live completions.
+This means that they ignore `mct-live-completion'. They do not
+automatically display the Completions' buffer, nor do they update
+it to match user input.
The Completions' buffer can still be accessed with commands that
place it in a window (such as `mct-list-completions-toggle',
-`mct-switch-to-completions-top')."
+`mct-switch-to-completions-top').
+
+A less drastic measure is to set `mct-minimum-input' to an
+appropriate value."
:type '(repeat symbol)
:group 'mct)
(defcustom mct-completion-passlist nil
- "Commands that do live updating of completions from the start.
-
-This means that they ignore `mct-minimum-input' and
-the inherent constraint of updating the Completions' buffer only
-upon user input. Furthermore, they also bypass any possible
-delay introduced by `mct-live-update-delay'."
+ "Functions that do live updating of completions from the start.
+This means that they ignore the value of `mct-live-completion'
+and the `mct-minimum-input'. They also bypass any possible delay
+introduced by `mct-live-update-delay'."
:type '(repeat symbol)
:group 'mct)
@@ -281,7 +304,8 @@ Meant to be added to `after-change-functions'."
(when (minibufferp) ; skip if we've exited already
(let ((while-no-input-ignore-events '(selection-request)))
(while-no-input
- (if (mct--minimum-input)
+ (if (or (mct--minimum-input)
+ (eq mct-live-completion 'visible))
(condition-case nil
(save-match-data
(save-excursion
@@ -300,6 +324,11 @@ Meant to be added to `after-change-functions'."
(when (>= delay 0)
(run-with-idle-timer delay nil #'mct--live-completions))))
+(defun mct--live-completions-visible-timer (&rest _)
+ "Update visible Completions' buffer."
+ (when (window-live-p (mct--get-completion-window))
+ (mct--live-completions-timer)))
+
(defun mct--setup-completions ()
"Set up the completions' buffer."
(cond
@@ -310,7 +339,9 @@ Meant to be added to `after-change-functions'."
(add-hook 'after-change-functions #'mct--live-completions nil t))
((null mct-live-completion))
((not (memq this-command mct-completion-blocklist))
- (add-hook 'after-change-functions #'mct--live-completions-timer nil t))))
+ (if (eq mct-live-completion 'visible)
+ (add-hook 'after-change-functions
#'mct--live-completions-visible-timer nil t)
+ (add-hook 'after-change-functions #'mct--live-completions-timer nil
t)))))
;;;;; Alternating backgrounds (else "stripes")
