Improve options for showing menu during minibuffer use

- Use the `window-preserve-size' window properly instead of the
  more aggressive `window-size-fixed' variable, as recommended in
  the documentation.

- Delay fixing the size until the window is actually being displayed.

- Add a new option `transient-show-during-minibuffer-read', replacing
  `transient-hide-during-minibuffer-read'.  This is necessary because
  there are now multiple values that show the menu, but in different
  ways, which can only be expressed using distinct non-nil values.

- When the user chose that the size should be `fixed', but we know that
  won't fly because the menu window uses the full frame height, then
  override that choice.  This is necessary because it will soon become
  possible for an individual prefix to use a different display action,
  which may have different needs from the global value the user
  optimized for.

- Allow displaying the fixed menu if possible, while also falling back
  to not displaying it either at all or while potentially resizing it,
  if that is not possible.

Closes #330.

2 files changed, 67 insertions, 7 deletions

diff --git a/docs/transient.org b/docs/transient.org
index 1b4d1b8..ccdecac 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -623,10 +623,40 @@ Also see [[* Common Suffix Commands]].
   from the user.  If ~nil~, there is no initial input and the first
   element has to be accessed the same way as the older elements.
 
-- User Option: transient-hide-during-minibuffer-read ::
-
-  This option controls whether the transient buffer is hidden while
-  user input is being read in the minibuffer.
+- User Option: transient-show-during-minibuffer-read ::
+
+  This option controls whether the transient menu continues to be
+  displayed while the minibuffer is used to read user input.
+
+  This is only relevant to commands that do not close the menu, such as
+  commands that set infix arguments.  If a command exits the menu, and
+  uses the minibuffer, then the menu is always closed before the
+  minibuffer is entered, irrespective of the value of this option.
+
+  When ~nil~ (the default), hide the menu while the minibuffer is in use.
+  When ~t~, keep showing the menu, but allow for the menu window to be
+  resized to ensure that completion candidates can be displayed.
+
+  When ~fixed~, keep showing the menu and prevent it from being resized,
+  which may make it impossible to display the completion candidates.  If
+  that ever happens for you, consider using ~t~ or an integer, as described
+  below.
+
+  If the value is ~fixed~ and the menu window uses the full height of its
+  frame, then the former is ignored and resizing is allowed anyway.  This
+  is necessary because individual menus may use unusal display actions
+  different from what ~transient-display-buffer-action~ specifies (likely
+  to display that menu in a side-window).
+
+  When using a third-party mode, which automatically resizes windows
+  (e.g., by calling ~balance-windows~ on ~post-command-hook~), then
+  ~fixed~ (or ~nil~) is likely a better choice than ~t~.
+
+  The value can also be an integer, in which case the behavior depends on
+  whether at least that many lines are left to display windows other than
+  the menu window.  If that is the case, display the menu and preserve the
+  size of that window.  Otherwise, allow resizing the menu window if the
+  number is positive, or hide the menu if it is negative.
 
 - User Option: transient-align-variable-pitch ::
 
diff --git a/docs/transient.texi b/docs/transient.texi
index 9522af6..32f2aa7 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -782,9 +782,39 @@ from the user.  If @code{nil}, there is no initial input and the first
 element has to be accessed the same way as the older elements.
 @end defopt
 
-@defopt transient-hide-during-minibuffer-read
-This option controls whether the transient buffer is hidden while
-user input is being read in the minibuffer.
+@defopt transient-show-during-minibuffer-read
+This option controls whether the transient menu continues to be
+displayed while the minibuffer is used to read user input.
+
+This is only relevant to commands that do not close the menu, such as
+commands that set infix arguments.  If a command exits the menu, and
+uses the minibuffer, then the menu is always closed before the
+minibuffer is entered, irrespective of the value of this option.
+
+When @code{nil} (the default), hide the menu while the minibuffer is in use.
+When @code{t}, keep showing the menu, but allow for the menu window to be
+resized to ensure that completion candidates can be displayed.
+
+When @code{fixed}, keep showing the menu and prevent it from being resized,
+which may make it impossible to display the completion candidates.  If
+that ever happens for you, consider using @code{t} or an integer, as described
+below.
+
+If the value is @code{fixed} and the menu window uses the full height of its
+frame, then the former is ignored and resizing is allowed anyway.  This
+is necessary because individual menus may use unusal display actions
+different from what @code{transient-display-buffer-action} specifies (likely
+to display that menu in a side-window).
+
+When using a third-party mode, which automatically resizes windows
+(e.g., by calling @code{balance-windows} on @code{post-command-hook}), then
+@code{fixed} (or @code{nil}) is likely a better choice than @code{t}.
+
+The value can also be an integer, in which case the behavior depends on
+whether at least that many lines are left to display windows other than
+the menu window.  If that is the case, display the menu and preserve the
+size of that window.  Otherwise, allow resizing the menu window if the
+number is positive, or hide the menu if it is negative.
 @end defopt
 
 @defopt transient-align-variable-pitch