[elpa] externals/mct 3ce6a66da3 1/2: Add mct-completion-window-size user option

[ELPA Syncer]

branch: externals/mct
commit 3ce6a66da3790ee358a56897813beac77ddf614f
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add mct-completion-window-size user option
    
    This is an attempt to let users fix the potential problem with the
    "bouncing window" of the Completions during live completion.
    
    Thanks to Daniel Mendler for the feedback in issue 14:
    <https://gitlab.com/protesilaos/mct/-/issues/14>.
---
 README.org | 15 +++++++++++++++
 mct.el     | 45 ++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/README.org b/README.org
index 5c0bff9c52..448ab83076 100644
--- a/README.org
+++ b/README.org
@@ -130,6 +130,20 @@ the Completions' buffer:
   both the automatic display and live updating of the Completions'
   buffer.
 
+#+vindex: mct-completion-window-size
+The size of the window where the =*Completions*= buffer is displayed is
+controlled by the user option ~mct-completion-window-size~.  It accepts a
+cons cell in the form of =(max-height . min-height)= where each value is
+either a natural number or a function which returns such a number.
+
+The default maximum height of the window is calculated by the function
+~mct--frame-height-fraction~, which finds the closest round number to 1/3
+of the frame's height.  While the default minimum height is 1.  This
+means that during live completions the Completions' window will shrink
+or grow to show candidates within the specified boundaries.  To disable
+this bouncing effect, set both max-height and min-height to the same
+number.
+
 Other customizations:
 
   #+vindex: mct-hide-completion-mode-line
@@ -531,6 +545,7 @@ And with more options:
 #+begin_src emacs-lisp
 (require 'mct)
 
+(setq mct-completion-window-size (cons #'mct--frame-height-fraction 1))
 (setq mct-remove-shadowed-file-names t) ; works when `file-name-shadow-mode' 
is enabled
 (setq mct-hide-completion-mode-line t)
 (setq mct-show-completion-line-numbers nil)
diff --git a/mct.el b/mct.el
index bf45009ea6..b932873aa7 100644
--- a/mct.el
+++ b/mct.el
@@ -45,6 +45,27 @@ Used by `mct--get-completion-window'."
   :type 'string
   :group 'mct)
 
+(defcustom mct-completion-window-size (cons #'mct--frame-height-fraction 1)
+  "Set the maximum and minimum height of the Completions' buffer.
+
+The value is a cons cell in the form of (max-height . min-height)
+where each value is either a natural number or a function which
+returns such a number.
+
+The default maximum height of the window is calculated by the
+function `mct--frame-height-fraction', which finds the closest
+round number to 1/3 of the frame's height.  While the default
+minimum height is 1.  This means that during live completions the
+Completions' window will shrink or grow to show candidates within
+the specified boundaries.  To disable this bouncing effect, set
+both max-height and min-height to the same number."
+  :type '(cons
+          (choice (function :tag "Function to determine maximum height")
+                  (natnum :tag "Maximum height in number of lines"))
+          (choice (function :tag "Function to determine minimum height")
+                  (natnum :tag "Minimum height in number of lines")))
+  :group 'mct)
+
 (defcustom mct-remove-shadowed-file-names nil
   "Delete shadowed parts of file names.
 
@@ -256,12 +277,30 @@ See `completions-format' for possible values."
                                  (goto-char prev))))))
         (put-text-property (point-min) (point) 'invisible t)))))
 
+(defun mct--frame-height-fraction ()
+  "Return round number of 1/3 of `frame-height'.
+Can be used in `mct-completion-window-size'."
+  (floor (frame-height) 3))
+
+(defun mct--height (param)
+  "Return height of PARAM in number of lines."
+  (cond
+   ((natnump param) param)
+   ((functionp param) (funcall param))
+   ;; There is no compelling reason to fall back to 5.  It just feels
+   ;; like a reasonable small value...
+   (t 5)))
+
 (defun mct--fit-completions-window (&rest _args)
   "Fit Completions' buffer to its window."
   (when-let ((window (mct--get-completion-window)))
-    (with-current-buffer (window-buffer window)
-      (setq-local window-resize-pixelwise t))
-    (fit-window-to-buffer window (floor (frame-height) 2) 1)))
+    ;; TODO 2022-01-28: Do we need the pixelwise adjustment?
+    ;; (with-current-buffer (window-buffer window)
+    ;;   (setq-local window-resize-pixelwise t))
+    (let* ((size mct-completion-window-size)
+           (max (car size))
+           (min (cdr size)))
+      (fit-window-to-buffer window (mct--height max) (mct--height min)))))
 
 (defun mct--minimum-input ()
   "Test for minimum requisite input for live completions.