diff options
Diffstat (limited to 'doc/lispref/minibuf.texi')
| -rw-r--r-- | doc/lispref/minibuf.texi | 71 |
1 files changed, 59 insertions, 12 deletions
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index cf36953098f..e6d6ad001e5 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -102,8 +102,8 @@ the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started. This supports only basic input: -none of the special minibuffer features (history, completion, -password hiding, etc.) are available in batch mode. +none of the special minibuffer features (history, completion, etc.) +are available in batch mode. @node Text from Minibuffer @section Reading Text Strings with the Minibuffer @@ -1738,7 +1738,7 @@ possible match, and ignore the match if the predicate returns @item A flag specifying the type of completion operation to perform. This -is one of the following four values: +flag may be one of the following values. @table @code @item nil @@ -1877,11 +1877,34 @@ next function in @code{completion-at-point-functions} instead of reporting a completion failure. @end table +Supplying a function for @var{collection} is strongly recommended if +generating the list of completions is an expensive operation. Emacs +may internally call functions in @code{completion-at-point-functions} +many times, but care about the value of @var{collection} for only some +of these calls. By supplying a function for @var{collection}, Emacs +can defer generating completions until necessary. You can use +@var{completion-table-dynamic} to create a wrapper function: + +@smallexample +;; Avoid this pattern. +(let ((beg ...) (end ...) (my-completions (my-make-completions))) + (list beg end my-completions)) + +;; Use this instead. +(let ((beg ...) (end ...)) + (list beg + end + (completion-table-dynamic + (lambda (_) + (my-make-completions))))) +@end smallexample + A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. +function instead of a list as described above. In that case, that +returned function is called, with no argument, and it is entirely +responsible for performing the completion. We discourage this usage; +it is intended to help convert old code to using +@code{completion-at-point}. The first function in @code{completion-at-point-functions} to return a non-@code{nil} value is used by @code{completion-at-point}. The @@ -2127,9 +2150,10 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. (Note that in batch mode, the -input is not hidden.) +not echo the password as the user types it; instead, it echoes +@samp{.} for each character in the password. If you want to apply +another character to hide the password, let-bind the variable +@code{read-hide-char} with that character. The optional argument @var{confirm}, if non-@code{nil}, says to read the password twice and insist it must be the same both times. If it isn't @@ -2197,8 +2221,8 @@ contents of the minibuffer before the point. @section Minibuffer Windows @cindex minibuffer windows - These functions access and select minibuffer windows -and test whether they are active. +These functions access and select minibuffer windows, test whether they +are active and control how they get resized. @defun active-minibuffer-window This function returns the currently active minibuffer window, or @@ -2239,6 +2263,29 @@ This function returns non-@code{nil} if @var{window} is the currently active minibuffer window. @end defun +The following two options control whether minibuffer windows are resized +automatically and how large they can get in the process. + +@defopt resize-mini-windows +This option specifies whether minibuffer windows are resized +automatically. The default value is @code{grow-only}, which means that +a minibuffer window by default expands automatically to accommodate the +text it displays and shrinks back to one line as soon as the minibuffer +gets empty. If the value is @code{t}, Emacs will always try to fit the +height of a minibuffer window to the text it displays (with a minimum of +one line). If the value is @code{nil}, a minibuffer window never +changes size automatically. In that case the window resizing commands +(@pxref{Resizing Windows}) can be used to adjust its height. +@end defopt + +@defopt max-mini-window-height +This option provides a maximum height for resizing minibuffer windows +automatically. A floating-point number specifies a fraction of the +frame's height; an integer specifies the maximum number of lines. The +default value is 0.25. +@end defopt + + @node Minibuffer Contents @section Minibuffer Contents @cindex access minibuffer contents |