23 |
* Object from Minibuffer:: How to read a Lisp object or expression. |
* Object from Minibuffer:: How to read a Lisp object or expression. |
24 |
* Minibuffer History:: Recording previous minibuffer inputs |
* Minibuffer History:: Recording previous minibuffer inputs |
25 |
so the user can reuse them. |
so the user can reuse them. |
26 |
|
* Initial Input:: Specifying initial contents for the minibuffer. |
27 |
* Completion:: How to invoke and customize completion. |
* Completion:: How to invoke and customize completion. |
28 |
* Yes-or-No Queries:: Asking a question with a simple answer. |
* Yes-or-No Queries:: Asking a question with a simple answer. |
29 |
* Multiple Queries:: Asking a series of similar questions. |
* Multiple Queries:: Asking a series of similar questions. |
169 |
Representations}) from whichever buffer was current before entering the |
Representations}) from whichever buffer was current before entering the |
170 |
minibuffer. |
minibuffer. |
171 |
|
|
172 |
If @var{initial-contents} is a string, @code{read-from-minibuffer} |
Use of @var{initial-contents} is mostly deprecated; we recommend using |
173 |
inserts it into the minibuffer, leaving point at the end, before the |
a non-@code{nil} value only in conjunction with specifying a cons cell |
174 |
user starts to edit the text. The minibuffer appears with this text as |
for @var{hist}. @xref{Initial Input}. |
|
its initial contents. |
|
|
|
|
|
Alternatively, @var{initial-contents} can be a cons cell of the form |
|
|
@code{(@var{string} . @var{position})}. This means to insert |
|
|
@var{string} in the minibuffer but put point at @emph{one-indexed} |
|
|
@var{position} in the minibuffer, rather than at the end. Any integer |
|
|
value less or equal to one puts point at the beginning of the string. |
|
|
|
|
|
@strong{Usage note:} The @var{initial-contents} argument and the |
|
|
@var{default} argument are two alternative features for more or less the |
|
|
same job. It does not make sense to use both features in a single call |
|
|
to @code{read-from-minibuffer}. In general, we recommend using |
|
|
@var{default}, since this permits the user to insert the default value |
|
|
when it is wanted, but does not burden the user with deleting it from |
|
|
the minibuffer on other occasions. For an exception to this rule, |
|
|
see @ref{Minibuffer History}. |
|
175 |
@end defun |
@end defun |
176 |
|
|
177 |
@defun read-string prompt &optional initial history default inherit-input-method |
@defun read-string prompt &optional initial history default inherit-input-method |
425 |
the most recent element of the history list in the minibuffer. If you |
the most recent element of the history list in the minibuffer. If you |
426 |
specify a positive @var{startpos}, the minibuffer history functions |
specify a positive @var{startpos}, the minibuffer history functions |
427 |
behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the |
behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the |
428 |
history element currently shown in the minibuffer. For consistency, |
history element currently shown in the minibuffer. |
429 |
you should also specify that element of the history as the initial |
|
430 |
minibuffer contents. |
For consistency, you should also specify that element of the history |
431 |
|
as the initial minibuffer contents, using the @var{initial} argument |
432 |
|
to the minibuffer input function (@pxref{Initial Input}). |
433 |
@end table |
@end table |
434 |
|
|
435 |
If you don't specify @var{hist}, then the default history list |
If you don't specify @var{hist}, then the default history list |
493 |
A history list for arguments that are Lisp expressions to evaluate. |
A history list for arguments that are Lisp expressions to evaluate. |
494 |
@end defvar |
@end defvar |
495 |
|
|
496 |
|
@node Initial Input |
497 |
|
@section Initial Input |
498 |
|
|
499 |
|
Several of the functions for minibuffer input have an argument called |
500 |
|
@var{initial} or @var{initial-contents}. This is a mostly-deprecated |
501 |
|
feature for specifiying that the minibuffer should start out with |
502 |
|
certain text, instead of empty as usual. |
503 |
|
|
504 |
|
If @var{initial} is a string, the minibuffer starts out containing the |
505 |
|
text of the string, with point at the end, when the user starts to |
506 |
|
edit the text. If the user simply types @key{RET} to exit the |
507 |
|
minibuffer, it will use the initial input string to determine the |
508 |
|
value to return. |
509 |
|
|
510 |
|
@strong{We discourage use of a non-@code{nil} value for |
511 |
|
@var{initial}}, because initial input is an intrusive interface. |
512 |
|
History lists and default values provide a much more convenient method |
513 |
|
to offer useful default inputs to the user. |
514 |
|
|
515 |
|
There is just one situation where you should specify a string for an |
516 |
|
@var{initial} argument. This is when you specify a cons cell for the |
517 |
|
@var{hist} or @var{history} argument. @xref{Minibuffer History}. |
518 |
|
|
519 |
|
@var{initial} can also be a cons cell of the form @code{(@var{string} |
520 |
|
. @var{position})}. This means to insert @var{string} in the |
521 |
|
minibuffer but put point at @var{position} within the string's text. |
522 |
|
|
523 |
|
As a historical accident, @var{position} was implemented |
524 |
|
inconsistently in different functions. In @code{completing-read}, |
525 |
|
@var{position}'s value is interpreted as origin-zero; that is, a value |
526 |
|
of 0 means the beginning of the string, 1 means after the first |
527 |
|
character, etc. In @code{read-minibuffer}, and the other |
528 |
|
non-completion minibuffer input functions that support this argument, |
529 |
|
1 means the beginning of the string 2 means after the first character, |
530 |
|
etc. |
531 |
|
|
532 |
|
Use of a cons cell as the value for @var{initial} arguments is |
533 |
|
deprecated in user code. |
534 |
|
|
535 |
@node Completion |
@node Completion |
536 |
@section Completion |
@section Completion |
537 |
@cindex completion |
@cindex completion |
823 |
saving the input and for minibuffer history commands. It defaults to |
saving the input and for minibuffer history commands. It defaults to |
824 |
@code{minibuffer-history}. @xref{Minibuffer History}. |
@code{minibuffer-history}. @xref{Minibuffer History}. |
825 |
|
|
826 |
If @var{initial} is non-@code{nil}, @code{completing-read} inserts it |
The argument @var{initial} is mostly deprecated; we recommend using a |
827 |
into the minibuffer as part of the input, with point at the end. Then |
non-@code{nil} value only in conjunction with specifying a cons cell |
828 |
it allows the user to edit the input, providing several commands to |
for @var{hist}. @xref{Initial Input}. For default input, use |
829 |
attempt completion. @var{initial} can also be a cons cell of the form |
@var{default} instead. |
|
@code{(@var{string} . @var{position})}. In that case, point is put at |
|
|
@emph{zero-indexed} position @var{position} in @var{string}. Note |
|
|
that this is different from @code{read-from-minibuffer} and related |
|
|
functions, which use a one-indexed position. In most cases, we |
|
|
recommend using @var{default}, and not @var{initial}. |
|
|
|
|
|
@strong{We discourage use of a non-@code{nil} value for |
|
|
@var{initial}}, because it is an intrusive interface. The history |
|
|
list feature (which did not exist when we introduced @var{initial}) |
|
|
offers a far more convenient and general way for the user to get the |
|
|
default and edit it, and it is always available. For an exception to |
|
|
this rule, see @ref{Minibuffer History}. |
|
830 |
|
|
831 |
If the argument @var{inherit-input-method} is non-@code{nil}, then the |
If the argument @var{inherit-input-method} is non-@code{nil}, then the |
832 |
minibuffer inherits the current input method (@pxref{Input |
minibuffer inherits the current input method (@pxref{Input |