/[emacs]/emacs/lispref/minibuf.texi
ViewVC logotype

Diff of /emacs/lispref/minibuf.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.36.2.1 by miles, Mon Apr 19 07:01:42 2004 UTC revision 1.36.2.2 by miles, Mon Jun 28 07:28:50 2004 UTC
# Line 23  for reading an argument. Line 23  for reading an argument.
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.
# Line 168  the setting of @code{enable-multibyte-ch Line 169  the setting of @code{enable-multibyte-ch
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
# Line 440  symbol @var{variable}.  @code{previous-h Line 425  symbol @var{variable}.  @code{previous-h
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
# Line 506  A history list for arguments that are sh Line 493  A history list for arguments that are sh
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
# Line 797  The argument @var{hist} specifies which Line 823  The argument @var{hist} specifies which
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

Legend:
Removed from v.1.36.2.1  
changed lines
  Added in v.1.36.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26