@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/minibuf
-@node Minibuffers, Command Loop, Read and Print, Top
+@node Minibuffers
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
* 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.
+* Minibuffer Contents:: How such commands access the minibuffer text.
* Recursive Mini:: Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
@code{forward-sentence}, and @code{forward-paragraph}, stop at the
boundary between the prompt and the actual text.
+@c See http://debbugs.gnu.org/11276
The minibuffer's window is normally a single line; it grows
-automatically if the contents require more space. You can explicitly
-@c FIXME? Works in 23.4, not 24.0.95. (Bug#11276)
-resize it temporarily with the window sizing commands; it reverts to
-its normal size when the minibuffer is exited. You can resize it
-@c FIXME? Doesn't work in any version of Emacs?
+automatically if the contents require more space. Whilst it is
+active, you can explicitly resize it temporarily with the window
+sizing commands; it reverts to its normal size when the minibuffer is
+exited. When the minibuffer is not active, you can resize it
permanently by using the window sizing commands in the frame's other
-window, when the minibuffer is not active. If the frame contains just
-a minibuffer, you can change the minibuffer's size by changing the
-frame's size.
+window, or dragging the mode line with the mouse. (Due to details of
+the current implementation, for this to work @code{resize-mini-windows}
+must be @code{nil}.) If the frame contains just a minibuffer, you can
+change the minibuffer's size by changing the frame's size.
Use of the minibuffer reads input events, and that alters the values
of variables such as @code{this-command} and @code{last-command}
minibuffer local maps. @xref{Completion Commands}, for the minibuffer
local maps for completion.
-@findex minibuffer-inactive-mode
-@vindex minibuffer-inactive-mode-map
@cindex inactive minibuffer
- When a minibuffer is inactive, it's major mode is
+ When a minibuffer is inactive, its major mode is
@code{minibuffer-inactive-mode}, with keymap
@code{minibuffer-inactive-mode-map}. This is only really useful if
the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
@end smallexample
@end defun
-@defun read-regexp prompt &optional default
+@defun read-regexp prompt &optional default history
This function reads a regular expression as a string from the
minibuffer and returns it. The argument @var{prompt} is used as in
-@code{read-from-minibuffer}. The keymap used is
-@code{minibuffer-local-map}, and @code{regexp-history} is used as the
-history list (@pxref{Minibuffer History, regexp-history}).
+@code{read-from-minibuffer}.
The optional argument @var{default} specifies a default value to
return if the user enters null input; it should be a string, or
@code{nil}, which is equivalent to an empty string.
-In addition, @code{read-regexp} collects a few useful candidates for
-input and passes them to @code{read-from-minibuffer}, to make them
-available to the user as the ``future minibuffer history list''
-(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
-Manual}). These candidates are:
+The optional argument @var{history}, if non-@code{nil}, is a symbol
+specifying a minibuffer history list to use (@pxref{Minibuffer
+History}). If it is omitted or @code{nil}, the history list defaults
+to @code{regexp-history}.
+
+@code{read-regexp} also collects a few useful candidates for input and
+passes them to @code{read-from-minibuffer}, to make them available to
+the user as the ``future minibuffer history list'' (@pxref{Minibuffer
+History, future list,, emacs, The GNU Emacs Manual}). These
+candidates are:
@itemize @minus
@item
@end defun
@defun edit-and-eval-command prompt form
-This function reads a Lisp expression in the minibuffer, and then
-evaluates it. The difference between this command and
+This function reads a Lisp expression in the minibuffer, evaluates it,
+then returns the result. The difference between this command and
@code{eval-minibuffer} is that here the initial @var{form} is not
optional and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text. It is printed with
@code{prin1}, so if it is a string, double-quote characters (@samp{"})
appear in the initial text. @xref{Output Functions}.
-The first thing @code{edit-and-eval-command} does is to activate the
-minibuffer with @var{prompt} as the prompt. Then it inserts the printed
-representation of @var{form} in the minibuffer, and lets the user edit it.
-When the user exits the minibuffer, the edited text is read with
-@code{read} and then evaluated. The resulting value becomes the value
-of @code{edit-and-eval-command}.
-
In the following example, we offer the user an expression with initial
-text which is a valid form already:
+text that is already a valid form:
@smallexample
@group
@noindent
Typing @key{RET} right away would exit the minibuffer and evaluate the
expression, thus moving point forward one word.
-@code{edit-and-eval-command} returns @code{nil} in this example.
@end defun
@node Minibuffer History
If the value of this variable is @code{nil}, standard functions that
read from the minibuffer don't add new elements to the history list.
This lets Lisp programs explicitly manage input history by using
-@code{add-to-history}. By default, @code{history-add-new-input} is
-set to a non-@code{nil} value.
+@code{add-to-history}. The default value is @code{t}.
@end defvar
@defopt history-length
The value of this variable specifies the maximum length for all
history lists that don't specify their own maximum lengths. If the
value is @code{t}, that means there is no maximum (don't delete old
-elements). The value of @code{history-length} property of the history
-list variable's symbol, if set, overrides this variable for that
+elements). If a history list variable's symbol has a non-@code{nil}
+@code{history-length} property, it overrides this variable for that
particular history list.
@end defopt
A history list for arguments that are Lisp expressions to evaluate.
@end defvar
+@defvar face-name-history
+A history list for arguments that are faces.
+@end defvar
+
+@c Less common: coding-system-history, input-method-history,
+@c command-history, grep-history, grep-find-history,
+@c read-envvar-name-history, setenv-history, yes-or-no-p-history.
+
@node Initial Input
@section Initial Input
of 0 means the beginning of the string, 1 means after the first
character, etc. In @code{read-minibuffer}, and the other
non-completion minibuffer input functions that support this argument,
-1 means the beginning of the string 2 means after the first character,
+1 means the beginning of the string, 2 means after the first character,
etc.
-Use of a cons cell as the value for @var{initial} arguments is
-deprecated in user code.
+Use of a cons cell as the value for @var{initial} arguments is deprecated.
@node Completion
@section Completion
user's input against a list of valid names and determining how much of
the name is determined uniquely by what the user has typed. For
example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+@c "This is the sort of English up with which I will not put."
type the first few letters of the name of the buffer to which you wish
to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
extends the name as far as it can.
* Minibuffer Completion:: Invoking the minibuffer with completion.
* Completion Commands:: Minibuffer commands that do completion.
* High-Level Completion:: Convenient special cases of completion
- (reading buffer name, file name, etc.).
+ (reading buffer names, variable names, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
* Completion Variables:: Variables controlling completion behavior.
completions of @var{string} in @var{collection}.
@cindex completion table
-The @var{collection} argument is called the @dfn{completion table}.
-Its value must be a list of strings, an alist whose keys are strings
-or symbols, an obarray, a hash table, or a completion function.
-
-Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}. If no permissible
-completions match, @code{try-completion} returns @code{nil}. If there
-is just one matching completion, and the match is exact, it returns
+@var{collection} is called the @dfn{completion table}. Its value must
+be a list of strings or cons cells, an obarray, a hash table, or a
+completion function.
+
+@code{try-completion} compares @var{string} against each of the
+permissible completions specified by the completion table. If no
+permissible completions match, it returns @code{nil}. If there is
+just one matching completion, and the match is exact, it returns
@code{t}. Otherwise, it returns the longest initial sequence common
to all possible matching completions.
-If @var{collection} is an alist (@pxref{Association Lists}), the
-permissible completions are the elements of the alist that are either
-strings, or conses whose @sc{car} is a string or symbol.
-Symbols are converted to strings using @code{symbol-name}. Other
-elements of the alist are ignored. (Remember that in Emacs Lisp, the
-elements of alists do not @emph{have} to be conses.) In particular, a
-list of strings is allowed, even though we usually do not
-think of such lists as alists.
+If @var{collection} is an list, the permissible completions are
+specified by the elements of the list, each of which should be either
+a string, or a cons cell whose @sc{car} is either a string or a symbol
+(a symbol is converted to a string using @code{symbol-name}). If the
+list contains elements of any other type, those are ignored.
@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
-of all symbols in the obarray form the set of permissible completions. The
-global variable @code{obarray} holds an obarray containing the names of
-all interned Lisp symbols.
-
-Note that the only valid way to make a new obarray is to create it
-empty and then add symbols to it one by one using @code{intern}.
-Also, you cannot intern a given symbol in more than one obarray.
+of all symbols in the obarray form the set of permissible completions.
If @var{collection} is a hash table, then the keys that are strings
are the possible completions. Other keys are ignored.
solely responsible for performing completion; @code{try-completion}
returns whatever this function returns. The function is called with
three arguments: @var{string}, @var{predicate} and @code{nil} (the
-reason for the third argument is so that the same function can be used
+third argument is so that the same function can be used
in @code{all-completions} and do the appropriate thing in either
case). @xref{Programmed Completion}.
In the first of the following examples, the string @samp{foo} is
matched by three of the alist @sc{car}s. All of the matches begin with
the characters @samp{fooba}, so that is the result. In the second
-example, there is only one possible match, and it is exact, so the value
-is @code{t}.
+example, there is only one possible match, and it is exact, so the
+return value is @code{t}.
@smallexample
@group
@end smallexample
@end defun
-@defun all-completions string collection &optional predicate nospace
+@c Removed obsolete argument nospace.
+@defun all-completions string collection &optional predicate
This function returns a list of all possible completions of
-@var{string}. The arguments to this function (aside from
-@var{nospace}) are the same as those of @code{try-completion}. Also,
-this function uses @code{completion-regexp-list} in the same way that
+@var{string}. The arguments to this function
+@c (aside from @var{nospace})
+are the same as those of @code{try-completion}, and it
+uses @code{completion-regexp-list} in the same way that
@code{try-completion} does.
+@ignore
The optional argument @var{nospace} is obsolete. If it is
non-@code{nil}, completions that start with a space are ignored unless
@var{string} starts with a space.
+@end ignore
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
@end defun
If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a non-@code{nil}
+variable as ``risky'' by giving it a non-@code{nil}
@code{risky-local-variable} property. @xref{File Local Variables}.
@defvar completion-ignore-case
It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here is a usage example:
+Here is an example:
@smallexample
(defvar foo (lazy-completion-table foo make-my-alist))
@end smallexample
@end defmac
+@c FIXME? completion-table-with-context?
+@findex completion-table-case-fold
+@findex completion-table-in-turn
+@findex completion-table-subvert
+@findex completion-table-with-quoting
+@findex completion-table-with-predicate
+@findex completion-table-with-terminator
+@cindex completion table, modifying
+@cindex completion tables, combining
+There are several functions that take an existing completion table and
+return a modified version. @code{completion-table-case-fold} returns
+a case-insensitive table. @code{completion-table-in-turn} combines
+multiple input tables. @code{completion-table-subvert} alters a table
+to use a different initial prefix. @code{completion-table-with-quoting}
+returns a table suitable for operating on quoted text.
+@code{completion-table-with-predicate} filters a table with a
+predicate function. @code{completion-table-with-terminator} adds a
+terminating string.
+
+
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
-If the built-in variable @code{completion-ignore-case} is
+If the variable @code{completion-ignore-case} is
non-@code{nil}, completion ignores case when comparing the input
against the possible matches. @xref{Basic Completion}. In this mode
of operation, @var{predicate} must also ignore case, or you will get
feedback. This is not needed in the minibuffer; for minibuffer
completion, you can pass @code{nil}.
-This function is called by @code{minibuffer-completion-help}. The
-most common way to use it is together with
+This function is called by @code{minibuffer-completion-help}. A
+common way to use it is together with
@code{with-output-to-temp-buffer}, like this:
@example
@end table
@noindent
-with other characters bound as in @code{minibuffer-local-map}
+and uses @code{minibuffer-local-map} as its parent keymap
(@pxref{Definition of minibuffer-local-map}).
@end defvar
bindings:
@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@end table
@noindent
-with other characters bound as in @code{minibuffer-local-map}.
+and uses @code{minibuffer-local-completion-map} as its parent keymap.
@end defvar
@defvar minibuffer-local-filename-completion-map
-This is like @code{minibuffer-local-completion-map}
-except that it does not bind @key{SPC}. This keymap is used by the
-function @code{read-file-name}.
+This is a sparse keymap that simply unbinds @key{SPC}; because
+filenames can contain spaces. The function @code{read-file-name}
+combines this keymap with either @code{minibuffer-local-completion-map}
+or @code{minibuffer-local-must-match-map}.
@end defvar
-@defvar minibuffer-local-filename-must-match-map
-This is like @code{minibuffer-local-must-match-map}
-except that it does not bind @key{SPC}. This keymap is used by the
-function @code{read-file-name}.
-@end defvar
@node High-Level Completion
@subsection High-Level Completion Functions
- This section describes the higher-level convenient functions for
+ This section describes the higher-level convenience functions for
reading certain sorts of names with completion.
In most cases, you should not call these functions in the middle of a
@end defun
@defopt read-buffer-function
-This variable specifies how to read buffer names. The function is
-called with the arguments passed to @code{read-buffer}. For example,
-if you set this variable to @code{iswitchb-read-buffer}, all Emacs
-commands that call @code{read-buffer} to read a buffer name will
-actually use the @code{iswitchb} package to read it.
+This variable, if non-@code{nil}, specifies a function for reading
+buffer names. @code{read-buffer} calls this function instead of doing
+its usual work, with the same arguments passed to @code{read-buffer}.
@end defopt
@defopt read-buffer-completion-ignore-case
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol, a string or a list of strings. If it
is a string, @code{read-command} interns it before returning it.
-If it is a list, @code{read-command} returns the first element of this list.
+If it is a list, @code{read-command} interns the first element of this list.
If @var{default} is @code{nil}, that means no default has been
specified; then if the user enters null input, the return value is
@code{(intern "")}, that is, a symbol whose name is an empty string.
@defun read-variable prompt &optional default
@anchor{Definition of read-variable}
-This function reads the name of a user variable and returns it as a
-symbol.
-
-The argument @var{default} specifies the default value to return if
-the user enters null input. It can be a symbol, a string, or a list
-of strings. If it is a string, @code{read-variable} interns it to
-make the default value. If it is a list, @code{read-variable} interns
-the first element. If @var{default} is @code{nil}, that means no
-default has been specified; then if the user enters null input, the
-return value is @code{(intern "")}.
-
-@example
-@group
-(read-variable "Variable name? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
-;; @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Variable name? @point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
-returns @code{fill-prefix}.
-
-In general, @code{read-variable} is similar to @code{read-command},
-but uses the predicate @code{user-variable-p} instead of
-@code{commandp}:
-
-@cindex @code{user-variable-p} example
-@example
-@group
-(read-variable @var{prompt})
-@equiv{}
-(intern
- (completing-read @var{prompt} obarray
- 'user-variable-p t nil))
-@end group
-@end example
+This function reads the name of a customizable variable and returns it
+as a symbol. Its arguments have the same form as those of
+@code{read-command}. It behaves just like @code{read-command}, except
+that it uses the predicate @code{custom-variable-p} instead of
+@code{commandp}.
@end defun
@deffn Command read-color &optional prompt convert allow-empty display
argument @var{convert} is non-@code{nil}, it converts any input color
name into the corresponding RGB value string and instead returns that.
This function requires a valid color specification to be input.
-Empty color names are allowed when @code{allow-empty} is
+Empty color names are allowed when @var{allow-empty} is
non-@code{nil} and the user enters null input.
Interactively, or when @var{display} is non-@code{nil}, the return
The high-level completion functions @code{read-file-name},
@code{read-directory-name}, and @code{read-shell-command} are designed
-to read file names, directory names, and shell commands respectively.
+to read file names, directory names, and shell commands, respectively.
They provide special features, including automatic insertion of the
default directory.
providing completion.
As an exception, this function reads a file name using a graphical
-file dialog instead of the minibuffer, if (i) it is invoked via a
-mouse command, and (ii) the selected frame is on a graphical display
-supporting such dialogs, and (iii) the variable @code{use-dialog-box}
-is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
-Emacs Manual}), and (iv) the @var{directory} argument, described
-below, does not specify a remote file (@pxref{Remote Files,, Remote
-Files, emacs, The GNU Emacs Manual}). The exact behavior when using a
-graphical file dialog is platform-dependent. Here, we simply document
-the behavior when using the minibuffer.
+file dialog instead of the minibuffer, if all of the following are
+true:
+
+@enumerate
+@item
+It is invoked via a mouse command.
+
+@item
+The selected frame is on a graphical display supporting such dialogs.
+
+@item
+The variable @code{use-dialog-box} is non-@code{nil}.
+@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
+
+@item
+The @var{directory} argument, described below, does not specify a
+remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
+@end enumerate
+
+@noindent
+The exact behavior when using a graphical file dialog is
+platform-dependent. Here, we simply document the behavior when using
+the minibuffer.
@code{read-file-name} does not automatically expand the returned file
name. You must call @code{expand-file-name} yourself if an absolute
The argument @var{directory} specifies the directory to use for
completing relative file names. It should be an absolute directory
-name. If @code{insert-default-directory} is non-@code{nil},
+name. If the variable @code{insert-default-directory} is non-@code{nil},
@var{directory} is also inserted in the minibuffer as initial input.
It defaults to the current buffer's value of @code{default-directory}.
in the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
-@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please
-note:} we recommend using @var{default} rather than @var{initial} in
-most cases.
+@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
+a file. @strong{Please note:} we recommend using @var{default} rather
+than @var{initial} in most cases.
If @var{default} is non-@code{nil}, then the function returns
@var{default} if the user exits the minibuffer with the same non-empty
If the user types @key{RET} in an empty minibuffer, this function
returns an empty string, regardless of the value of
@var{require-match}. This is, for instance, how the user can make the
-current buffer visit no file using @code{M-x set-visited-file-name}.
+current buffer visit no file using @kbd{M-x set-visited-file-name}.
If @var{predicate} is non-@code{nil}, it specifies a function of one
argument that decides which file names are acceptable completion
@xref{Interactive Codes,, Code Characters for interactive}.) Its
value controls whether @code{read-file-name} starts by placing the
name of the default directory in the minibuffer, plus the initial file
-name if any. If the value of this variable is @code{nil}, then
+name, if any. If the value of this variable is @code{nil}, then
@code{read-file-name} does not place any initial input in the
minibuffer (unless you specify initial input with the @var{initial}
argument). In that case, the default directory is still used for
@defvar minibuffer-local-shell-command-map
This keymap is used by @code{read-shell-command} for completing
-command and file names that are part of a shell command.
+command and file names that are part of a shell command. It uses
+@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
+to @code{completion-at-point}.
@end defvar
@node Completion Variables
@subsection Completion Variables
- Here are some variables which can be used to alter the default
+ Here are some variables that can be used to alter the default
completion behavior.
@cindex completion styles
@defopt completion-styles
The value of this variable is a list of completion style (symbols) to
use for performing completion. A @dfn{completion style} is a set of
-rules for generating completions. Each symbol in occurring this list
+rules for generating completions. Each symbol occurring this list
must have a corresponding entry in @code{completion-styles-alist}.
@end defopt
@code{try-completion} (@pxref{Basic Completion}), and the @var{point}
argument is the position of point within @var{string}. Each function
should return a non-@code{nil} value if it performed its job, and
-@code{nil} if it did not (e.g.@: if there is no way to complete
+@code{nil} if it did not (e.g., if there is no way to complete
@var{string} according to the completion style).
When the user calls a completion command like
@defopt completion-category-overrides
This variable specifies special completion styles and other completion
behaviors to use when completing certain types of text. Its value
-should be a list of the form @code{(@var{category} . @var{alist})}.
-@var{category} is a symbol describing what is being completed;
-currently, the @code{buffer} and @code{file} categories are defined,
-but others can be defined via specialized completion functions
-(@pxref{Programmed Completion}). @var{alist} is an association list
-describing how completion should behave for the corresponding
-category. The following alist keys are supported:
+should be an alist with elements of the form @code{(@var{category}
+. @var{alist})}. @var{category} is a symbol describing what is being
+completed; currently, the @code{buffer}, @code{file}, and
+@code{unicode-name} categories are defined, but others can be defined
+via specialized completion functions (@pxref{Programmed Completion}).
+@var{alist} is an association list describing how completion should
+behave for the corresponding category. The following alist keys are
+supported:
@table @code
@item styles
The value should be a function to run after performing completion.
The function should accept two arguments, @var{string} and
@var{status}, where @var{string} is the text to which the field was
-completed and @var{status} indicates what kind of operation happened:
+completed, and @var{status} indicates what kind of operation happened:
@code{finished} if text is now complete, @code{sole} if the text
cannot be further completed but completion is not finished, or
@code{exact} if the text is a valid completion but may be further
@item metadata
This specifies a request for information about the state of the
-current completion. The function should return an alist, as described
-below. The alist may contain any number of elements.
+current completion. The return value should have the form
+@code{(metadata . @var{alist})}, where @var{alist} is an alist whose
+elements are described below.
@end table
@noindent
@defun completion-table-dynamic function
This function is a convenient way to write a function that can act as
-programmed completion function. The argument @var{function} should be
+a programmed completion function. The argument @var{function} should be
a function that takes one argument, a string, and returns an alist of
possible completions of it. You can think of
@code{completion-table-dynamic} as a transducer between that interface
@item :exclusive
If the value is @code{no}, then if the completion table fails to match
-the text at point, then @code{completion-at-point} moves on to the
+the text at point, @code{completion-at-point} moves on to the
next function in @code{completion-at-point-functions} instead of
reporting a completion failure.
@end table
The first function in @code{completion-at-point-functions} to return a
non-@code{nil} value is used by @code{completion-at-point}. The
remaining functions are not called. The exception to this is when
-there is a @code{:exclusive} specification, as described above.
+there is an @code{:exclusive} specification, as described above.
@end defvar
The following function provides a convenient way to perform
using the mouse---more precisely, if @code{last-nonmenu-event}
(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
uses a dialog box or pop-up menu to ask the question. Otherwise, it
-uses keyboard input. You can force use of the mouse or use of keyboard
+uses keyboard input. You can force use either of the mouse or of keyboard
input by binding @code{last-nonmenu-event} to a suitable value around
the call.
cursor moves to the echo area while the question is being asked.
The answers and their meanings, even @samp{y} and @samp{n}, are not
-hardwired. The keymap @code{query-replace-map} specifies them.
-@xref{Search and Replace}.
-
-In the following example, the user first types @kbd{q}, which is
-invalid. At the next prompt the user types @kbd{y}.
-
-@smallexample
-@group
-(y-or-n-p "Do you need a lift? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears in the echo area:}
-@end group
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{If the user then types @kbd{q}, the following appears:}
-
-@group
----------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{When the user types a valid answer,}
-;; @r{it is displayed after the question:}
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n) y
----------- Echo area ----------
-@end group
-@end smallexample
+hardwired, and are specified by the keymap @code{query-replace-map}
+(@pxref{Search and Replace}). In particular, if the user enters the
+special responses @code{recenter}, @code{scroll-up},
+@code{scroll-down}, @code{scroll-other-window}, or
+@code{scroll-other-window-down} (respectively bound to @kbd{C-l},
+@kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in
+@code{query-replace-map}), this function performs the specified window
+recentering or scrolling operation, and poses the question again.
@noindent
We show successive lines of echo area messages, but only one actually
The value of @var{list} specifies the objects to ask questions about.
It should be either a list of objects or a generator function. If it is
a function, it should expect no arguments, and should return either the
-next object to ask about, or @code{nil} meaning stop asking questions.
+next object to ask about, or @code{nil}, meaning to stop asking questions.
The argument @var{prompter} specifies how to ask each question. If
@var{prompter} is a string, the question text is computed like this:
If not a string, @var{prompter} should be a function of one argument
(the next object to ask about) and should return the question text. If
the value is a string, that is the question to ask the user. The
-function can also return @code{t} meaning do act on this object (and
-don't ask the user), or @code{nil} meaning ignore this object (and don't
+function can also return @code{t}, meaning do act on this object (and
+don't ask the user), or @code{nil}, meaning ignore this object (and don't
ask the user).
The argument @var{actor} says how to act on the answers that the user
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a list---then it uses a dialog box
or pop-up menu to ask the question. In this case, it does not use
-keyboard input or the echo area. You can force use of the mouse or use
+keyboard input or the echo area. You can force use either of the mouse or
of keyboard input by binding @code{last-nonmenu-event} to a suitable
value around the call.
The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun
+@c FIXME An example of this would be more useful than all the
+@c preceding examples of simple things.
@node Reading a Password
@section Reading a Password
regular expression).
@end deffn
+@deffn Command previous-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+@deffn Command next-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+
@node Minibuffer Windows
@section Minibuffer Windows
@cindex minibuffer windows
@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
-@code{nil} if none is currently active.
+@code{nil} if there is none.
@end defun
@defun minibuffer-window &optional frame
frame.
@defun minibuffer-window-active-p window
-This function returns non-@code{nil} if @var{window}, assumed to be
-a minibuffer window, is currently active.
+This function returns non-@code{nil} if @var{window} is the currently
+active minibuffer window.
@end defun
@node Minibuffer Contents
@end defvar
@defun minibuffer-selected-window
-This function returns the window which was selected when the
+This function returns the window that was selected when the
minibuffer was entered. If selected window is not a minibuffer
window, it returns @code{nil}.
@end defun
frame. If an integer, it specifies a number of lines.
@end defopt
+@vindex minibuffer-message-timeout
@defun minibuffer-message string &rest args
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. If @var{args} is non-@code{nil}, the
-actual message is obtained by passing @var{string} and @var{args}
-through @code{format}. @xref{Formatting Strings}.
+minibuffer text, for a few seconds, or until the next input event
+arrives, whichever comes first. The variable
+@code{minibuffer-message-timeout} specifies the number of seconds to
+wait in the absence of input. It defaults to 2. If @var{args} is
+non-@code{nil}, the actual message is obtained by passing @var{string}
+and @var{args} through @code{format}. @xref{Formatting Strings}.
@end defun
+
+@deffn Command minibuffer-inactive-mode
+This is the major mode used in inactive minibuffers. It uses
+keymap @code{minibuffer-inactive-mode-map}. This can be useful
+if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
+@end deffn
HCoop / bpt / emacs.git / blobdiff