comparison lispref/minibuf.texi @ 64843:6c4d2fa924e4

(Minibuffer Misc): Node split up. (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) (Recursive Mini): New nodes split out from Minibuffer Misc. (Minibuffer Misc): Document max-mini-window-height.

64842:0021965e29a2

@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
@cindex minibuffer

  A @dfn{minibuffer} is a special buffer that Emacs commands use to read
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
frame, in the same place as the echo area, but only while it is in use
for reading an argument.

@menu
* Intro to Minibuffers::      Basic information about minibuffers.
* Text from Minibuffer::      How to read a straight text string.
* Object from Minibuffer::    How to read a Lisp object or expression.

* Initial Input::             Specifying initial contents for the minibuffer.
* Completion::                How to invoke and customize completion.
* Yes-or-No Queries::         Asking a question with a simple answer.
* Multiple Queries::	      Asking a series of similar questions.
* Reading a Password::	      Reading a password from the terminal.
* Minibuffer Misc::           Various customization hooks and variables.
@end menu

@node Intro to Minibuffers
@section Introduction to Minibuffers

The optional argument @var{default} specifies the default password to
return if the user enters empty input.  If @var{default} is @code{nil},
then @code{read-passwd} returns the null string in that case.
@end defun

@node Minibuffer Misc
@section Minibuffer Miscellany

  This section describes some basic functions and variables related to
minibuffers.

@deffn Command exit-minibuffer
This command exits the active minibuffer.  It is normally bound to
keys in minibuffer local keymaps.
@end deffn

This command replaces the minibuffer contents with the value of the
@var{n}th next (newer) history element that matches @var{pattern} (a
regular expression).
@end deffn

@defun minibuffer-prompt
This function returns the prompt string of the currently active
minibuffer.  If no minibuffer is active, it returns @code{nil}.
@end defun

@defun minibuffer-prompt-end
@tindex minibuffer-prompt-end
This function returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current.  Otherwise, it returns the minimum valid buffer position.
@end defun

@defun minibuffer-contents
@tindex minibuffer-contents
This function returns the editable
contents of the minibuffer (that is, everything except the prompt) as
a string, if a minibuffer is current.  Otherwise, it returns the
entire contents of the current buffer.
@end defun

@defun minibuffer-contents-no-properties
@tindex minibuffer-contents-no-properties
This is like @code{minibuffer-contents}, except that it does not copy text
properties, just the characters themselves.  @xref{Text Properties}.
@end defun

@defun delete-minibuffer-contents
@tindex delete-minibuffer-contents
This function erases the editable
contents of the minibuffer (that is, everything except the prompt), if
a minibuffer is current.  Otherwise, it erases the entire buffer.
@end defun

@defun minibuffer-prompt-width
This function returns the current display-width of the minibuffer
prompt, if a minibuffer is current.  Otherwise, it returns zero.
@end defun

@defvar minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered.
@xref{Hooks}.
@end defvar

@defvar minibuffer-exit-hook
This is a normal hook that is run whenever the minibuffer is exited.
@xref{Hooks}.
@end defvar

@defvar minibuffer-help-form
@anchor{Definition of minibuffer-help-form}
The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar

@defun minibufferp &optional buffer-or-name
This function returns non-@code{nil} if @var{buffer-or-name} is a
minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
buffer.
@end defun

@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
@code{nil} if none is currently active.
@end defun

@defun minibuffer-window-active-p window
This function returns non-@code{nil} if @var{window}, assumed to be
a minibuffer window, is currently active.
@end defun

@defvar minibuffer-scroll-window
@anchor{Definition of minibuffer-scroll-window}
If the value of this variable is non-@code{nil}, it should be a window
object.  When the function @code{scroll-other-window} is called in the
minibuffer, it scrolls this window.
@end defvar

@defun minibuffer-selected-window
This function returns the window which was selected when the
minibuffer was entered.  If selected window is not a minibuffer
window, it returns @code{nil}.
@end defun

Finally, some functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):

@defun minibuffer-depth
This function returns the current depth of activations of the
minibuffer, a nonnegative integer.  If no minibuffers are active, it

also achieve this by binding @code{enable-recursive-minibuffers}
to @code{t} in the interactive declaration (@pxref{Using Interactive}).
The minibuffer command @code{next-matching-history-element} (normally
@kbd{M-s} in the minibuffer) does the latter.

@defun minibuffer-message string
This function displays @var{string} temporarily at the end of the
minibuffer text, for two seconds, or until the next input event
arrives, whichever comes first.
@end defun

64843:6c4d2fa924e4

@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
@cindex minibuffer

  A @dfn{minibuffer} is a special buffer that Emacs commands use to
read arguments more complicated than the single numeric prefix
argument.  These arguments include file names, buffer names, and
command names (as in @kbd{M-x}).  The minibuffer is displayed on the
bottom line of the frame, in the same place as the echo area
(@pxref{The Echo Area}), but only while it is in use for reading an
argument.

@menu
* Intro to Minibuffers::      Basic information about minibuffers.
* Text from Minibuffer::      How to read a straight text string.
* Object from Minibuffer::    How to read a Lisp object or expression.

* Initial Input::             Specifying initial contents for the minibuffer.
* Completion::                How to invoke and customize completion.
* Yes-or-No Queries::         Asking a question with a simple answer.
* Multiple Queries::	      Asking a series of similar questions.
* Reading a Password::	      Reading a password from the terminal.
* Minibuffer Commands::       Commands used as key bindings in minibuffers.
* Minibuffer Contents::       How such commands access the minibuffer text.
* Minibuffer Windows::        Operating on the special minibuffer windows.
* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc::           Various customization hooks and variables.
@end menu

@node Intro to Minibuffers
@section Introduction to Minibuffers

The optional argument @var{default} specifies the default password to
return if the user enters empty input.  If @var{default} is @code{nil},
then @code{read-passwd} returns the null string in that case.
@end defun

@node Minibuffer Commands
@section Minibuffer Commands

  This section describes some commands meant for use in the
minibuffer.

@deffn Command exit-minibuffer
This command exits the active minibuffer.  It is normally bound to
keys in minibuffer local keymaps.
@end deffn

This command replaces the minibuffer contents with the value of the
@var{n}th next (newer) history element that matches @var{pattern} (a
regular expression).
@end deffn

@node Minibuffer Windows
@section Minibuffer Windows

  These functions access and select minibuffer windows
and test whether they are active.

@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
@code{nil} if none is currently active.
@end defun

@defun minibuffer-window-active-p window
This function returns non-@code{nil} if @var{window}, assumed to be
a minibuffer window, is currently active.
@end defun

@node Minibuffer Contents
@section Minibuffer Contents

  These functions access the minibuffer prompt and contents.

@defun minibuffer-prompt
This function returns the prompt string of the currently active
minibuffer.  If no minibuffer is active, it returns @code{nil}.
@end defun

@defun minibuffer-prompt-end
@tindex minibuffer-prompt-end
This function returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current.  Otherwise, it returns the minimum valid buffer position.
@end defun

@defun minibuffer-prompt-width
This function returns the current display-width of the minibuffer
prompt, if a minibuffer is current.  Otherwise, it returns zero.
@end defun

@defun minibuffer-contents
@tindex minibuffer-contents
This function returns the editable
contents of the minibuffer (that is, everything except the prompt) as
a string, if a minibuffer is current.  Otherwise, it returns the
entire contents of the current buffer.
@end defun

@defun minibuffer-contents-no-properties
@tindex minibuffer-contents-no-properties
This is like @code{minibuffer-contents}, except that it does not copy text
properties, just the characters themselves.  @xref{Text Properties}.
@end defun

@defun delete-minibuffer-contents
@tindex delete-minibuffer-contents
This function erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current.  Otherwise,
it erases the entire current buffer.
@end defun

@node Recursive Mini
@section Recursive Minibuffers

  These functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):

@defun minibuffer-depth
This function returns the current depth of activations of the
minibuffer, a nonnegative integer.  If no minibuffers are active, it

also achieve this by binding @code{enable-recursive-minibuffers}
to @code{t} in the interactive declaration (@pxref{Using Interactive}).
The minibuffer command @code{next-matching-history-element} (normally
@kbd{M-s} in the minibuffer) does the latter.

@node Minibuffer Misc
@section Minibuffer Miscellany

@defun minibufferp &optional buffer-or-name
This function returns non-@code{nil} if @var{buffer-or-name} is a
minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
buffer.
@end defun

@defvar minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered.
@xref{Hooks}.
@end defvar

@defvar minibuffer-exit-hook
This is a normal hook that is run whenever the minibuffer is exited.
@xref{Hooks}.
@end defvar

@defvar minibuffer-help-form
@anchor{Definition of minibuffer-help-form}
The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar

@defvar minibuffer-scroll-window
@anchor{Definition of minibuffer-scroll-window}
If the value of this variable is non-@code{nil}, it should be a window
object.  When the function @code{scroll-other-window} is called in the
minibuffer, it scrolls this window.
@end defvar

@defun minibuffer-selected-window
This function returns the window which was selected when the
minibuffer was entered.  If selected window is not a minibuffer
window, it returns @code{nil}.
@end defun

@defopt max-mini-window-height
This variable specifies the maximum height for resizing minibuffer
windows.  If a float, it specifies a fraction of the height of the
frame.  If an integer, it specifies a number of lines.
@end defopt

@defun minibuffer-message string
This function displays @var{string} temporarily at the end of the
minibuffer text, for two seconds, or until the next input event
arrives, whichever comes first.
@end defun