/[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.29.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.29.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 63  other window, when the minibuffer is not Line 63  other window, when the minibuffer is not
63  just a minibuffer, you can change the minibuffer's size by changing the  just a minibuffer, you can change the minibuffer's size by changing the
64  frame's size.  frame's size.
65    
66      Use of the minibuffer reads input events, and that alters the values
67    of variables such as @code{this-command} and @code{last-command}
68    (@pxref{Command Loop Info}).  Your program should bind them around the
69    code that uses the minibuffer, if you do not want that to change them.
70    
71    If a command uses a minibuffer while there is an active minibuffer,    If a command uses a minibuffer while there is an active minibuffer,
72  this is called a @dfn{recursive minibuffer}.  The first minibuffer is  this is called a @dfn{recursive minibuffer}.  The first minibuffer is
73  named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by  named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
# Line 84  completion commands (@pxref{Completion}) Line 89  completion commands (@pxref{Completion})
89    
90  @item  @item
91  @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits  @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
92  just like @key{RET}.  This is used mainly for Mocklisp compatibility.  just like @key{RET}.
93    
94  @item  @item
95  @code{minibuffer-local-completion-map} is for permissive completion.  @code{minibuffer-local-completion-map} is for permissive completion.
# Line 184  arguments @var{prompt} and @var{initial} Line 189  arguments @var{prompt} and @var{initial}
189  @code{read-from-minibuffer}.  The keymap used is  @code{read-from-minibuffer}.  The keymap used is
190  @code{minibuffer-local-map}.  @code{minibuffer-local-map}.
191    
192  The optional argument @var{history}, if non-nil, specifies a history  The optional argument @var{history}, if non-@code{nil}, specifies a
193  list and optionally the initial position in the list.  The optional  history list and optionally the initial position in the list.  The
194  argument @var{default} specifies a default value to return if the user  optional argument @var{default} specifies a default value to return if
195  enters null input; it should be a string.  The optional argument  the user enters null input; it should be a string.  The optional
196  @var{inherit-input-method} specifies whether to inherit the current  argument @var{inherit-input-method} specifies whether to inherit the
197  buffer's input method.  current buffer's input method.
198    
199  This function is a simplified interface to the  This function is a simplified interface to the
200  @code{read-from-minibuffer} function:  @code{read-from-minibuffer} function:
# Line 520  for reading certain kinds of names with Line 525  for reading certain kinds of names with
525  * High-Level Completion::  Convenient special cases of completion  * High-Level Completion::  Convenient special cases of completion
526                               (reading buffer name, file name, etc.)                               (reading buffer name, file name, etc.)
527  * Reading File Names::     Using completion to read file names.  * Reading File Names::     Using completion to read file names.
528  * Programmed Completion::  Finding the completions for a given file name.  * Programmed Completion::  Writing your own completion-function.
529  @end menu  @end menu
530    
531  @node Basic Completion  @node Basic Completion
532  @subsection Basic Completion Functions  @subsection Basic Completion Functions
533    
534    The two functions @code{try-completion} and @code{all-completions}    The functions @code{try-completion}, @code{all-completions} and
535  have nothing in themselves to do with minibuffers.  We describe them in  @code{test-completion} have nothing in themselves to do with
536  this chapter so as to keep them near the higher-level completion  minibuffers.  We describe them in this chapter so as to keep them near
537  features that do use the minibuffer.  the higher-level completion features that do use the minibuffer.
538    
539  @defun try-completion string collection &optional predicate  @defun try-completion string collection &optional predicate
540  This function returns the longest common substring of all possible  This function returns the longest common substring of all possible
541  completions of @var{string} in @var{collection}.  The value of  completions of @var{string} in @var{collection}.  The value of
542  @var{collection} must be an alist, an obarray, or a function that  @var{collection} must be a list of strings, an alist, an obarray, or a
543  implements a virtual set of strings (see below).  function that implements a virtual set of strings (see below).
544    
545  Completion compares @var{string} against each of the permissible  Completion compares @var{string} against each of the permissible
546  completions specified by @var{collection}; if the beginning of the  completions specified by @var{collection}; if the beginning of the
# Line 559  Note that the only valid way to make a n Line 564  Note that the only valid way to make a n
564  empty and then add symbols to it one by one using @code{intern}.  empty and then add symbols to it one by one using @code{intern}.
565  Also, you cannot intern a given symbol in more than one obarray.  Also, you cannot intern a given symbol in more than one obarray.
566    
 If the argument @var{predicate} is non-@code{nil}, then it must be a  
 function of one argument.  It is used to test each possible match, and  
 the match is accepted only if @var{predicate} returns non-@code{nil}.  
 The argument given to @var{predicate} is either a cons cell from the alist  
 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a  
 symbol name) from the obarray.  
   
567  You can also use a symbol that is a function as @var{collection}.  Then  You can also use a symbol that is a function as @var{collection}.  Then
568  the function is solely responsible for performing completion;  the function is solely responsible for performing completion;
569  @code{try-completion} returns whatever this function returns.  The  @code{try-completion} returns whatever this function returns.  The
# Line 574  and @code{nil}.  (The reason for the thi Line 572  and @code{nil}.  (The reason for the thi
572  function can be used in @code{all-completions} and do the appropriate  function can be used in @code{all-completions} and do the appropriate
573  thing in either case.)  @xref{Programmed Completion}.  thing in either case.)  @xref{Programmed Completion}.
574    
575    If the argument @var{predicate} is non-@code{nil}, then it must be a
576    function of one argument.  It is used to test each possible match, and
577    the match is accepted only if @var{predicate} returns non-@code{nil}.
578    The argument given to @var{predicate} is either a string from the
579    list, a cons cell from the alist (the @sc{car} of which is a string)
580    or a symbol (@emph{not} a symbol name) from the obarray.
581    
582  In the first of the following examples, the string @samp{foo} is  In the first of the following examples, the string @samp{foo} is
583  matched by three of the alist @sc{car}s.  All of the matches begin with  matched by three of the alist @sc{car}s.  All of the matches begin with
584  the characters @samp{fooba}, so that is the result.  In the second  the characters @samp{fooba}, so that is the result.  In the second
# Line 657  example for @code{try-completion}: Line 662  example for @code{try-completion}:
662  @end smallexample  @end smallexample
663  @end defun  @end defun
664    
665    @defun test-completion string collection &optional predicate
666    This function returns non-@code{nil} if @var{string} is a valid
667    completion possibility specified by @var{collection} and
668    @var{predicate}.  The other arguments are the same as in
669    @code{try-completion}.  For instance, if @var{collection} is a list,
670    this is true if @var{string} appears in the list and @var{predicate}
671    is satisfied.
672    
673    If @var{collection} is a function, it is called with three arguments,
674    the values @var{string}, @var{predicate} and @code{lambda}; whatever
675    it returns, @code{test-completion} returns in turn.
676    @end defun
677    
678  @defvar completion-ignore-case  @defvar completion-ignore-case
679  If the value of this variable is  If the value of this variable is non-@code{nil}, Emacs does not
680  non-@code{nil}, Emacs does not consider case significant in completion.  consider case significant in completion.
681  @end defvar  @end defvar
682    
683    @defmac lazy-completion-table var fun &rest args
684    This macro provides a way to initialize the variable @var{var} as a
685    collection for completion in a lazy way, not computing its actual
686    contents until they are first needed.  You use this macro to produce a
687    value that you store in @var{var}.  The actual computation of the
688    proper value is done the first time you do completion using @var{var}.
689    It is done by calling @var{fun} with the arguments @var{args}.  The
690    value @var{fun} returns becomes the permanent value of @var{var}.
691    
692    Here are two examples of use:
693    
694    @example
695    (defvar foo (lazy-completion-table foo make-my-alist 'global))
696    
697    (make-local-variable 'bar)
698    (setq bar (lazy-completion-table foo make-my-alist 'local)
699    @end example
700    @end defmac
701    
702  @node Minibuffer Completion  @node Minibuffer Completion
703  @subsection Completion and the Minibuffer  @subsection Completion and the Minibuffer
704    
# Line 1051  predicate @code{user-variable-p} instead Line 1088  predicate @code{user-variable-p} instead
1088  file name.  It provides special features including automatic insertion  file name.  It provides special features including automatic insertion
1089  of the default directory.  of the default directory.
1090    
1091  @defun read-file-name prompt &optional directory default existing initial  @defun read-file-name prompt &optional directory default existing initial predicate
1092  This function reads a file name in the minibuffer, prompting with  This function reads a file name in the minibuffer, prompting with
1093  @var{prompt} and providing completion.  If @var{default} is  @var{prompt} and providing completion.  If @var{default} is
1094  non-@code{nil}, then the function returns @var{default} if the user just  non-@code{nil}, then the function returns @var{default} if the user just
# Line 1073  initial input.  It defaults to the curre Line 1110  initial input.  It defaults to the curre
1110  @code{default-directory}.  @code{default-directory}.
1111    
1112  @c Emacs 19 feature  @c Emacs 19 feature
1113  If you specify @var{initial}, that is an initial file name to insert in  If you specify @var{initial}, that is an initial file name to insert
1114  the buffer (after @var{directory}, if that is inserted).  In this  in the buffer (after @var{directory}, if that is inserted).  In this
1115  case, point goes at the beginning of @var{initial}.  The default for  case, point goes at the beginning of @var{initial}.  The default for
1116  @var{initial} is @code{nil}---don't insert any file name.  To see what  @var{initial} is @code{nil}---don't insert any file name.  To see what
1117  @var{initial} does, try the command @kbd{C-x C-v}.  @strong{Note:} we  @var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
1118  recommend using @var{default} rather than @var{initial} in most cases.  note:} we recommend using @var{default} rather than @var{initial} in
1119    most cases.
1120    
1121    If @var{predicate} is non-@code{nil}, it specifies a function of one
1122    argument that decides which file names are acceptable completion
1123    possibilities.  A file name is an acceptable value if @var{predicate}
1124    returns non-@code{nil} for it.
1125    
1126  Here is an example:  Here is an example:
1127    
# Line 1114  If the user types @key{RET}, @code{read- Line 1157  If the user types @key{RET}, @code{read-
1157  as the string @code{"/gp/gnu/elisp/manual.texi"}.  as the string @code{"/gp/gnu/elisp/manual.texi"}.
1158  @end defun  @end defun
1159    
1160    @defun read-directory-name prompt &optional directory default existing initial
1161    This function is like @code{read-file-name} but allows only directory
1162    names as completion possibilities.
1163    @end defun
1164    
1165  @defopt insert-default-directory  @defopt insert-default-directory
1166  This variable is used by @code{read-file-name}.  Its value controls  This variable is used by @code{read-file-name}.  Its value controls
1167  whether @code{read-file-name} starts by placing the name of the default  whether @code{read-file-name} starts by placing the name of the default
# Line 1203  should return a list of all possible com Line 1251  should return a list of all possible com
1251  string.  string.
1252    
1253  @item  @item
1254  @code{lambda} specifies a test for an exact match.  The completion  @code{lambda} specifies @code{test-completion}.  The completion
1255  function should return @code{t} if the specified string is an exact  function should return @code{t} if the specified string is an exact
1256  match for some possibility; @code{nil} otherwise.  match for some possibility; @code{nil} otherwise.
1257  @end itemize  @end itemize
# Line 1211  match for some possibility; @code{nil} o Line 1259  match for some possibility; @code{nil} o
1259    It would be consistent and clean for completion functions to allow    It would be consistent and clean for completion functions to allow
1260  lambda expressions (lists that are functions) as well as function  lambda expressions (lists that are functions) as well as function
1261  symbols as @var{collection}, but this is impossible.  Lists as  symbols as @var{collection}, but this is impossible.  Lists as
1262  completion tables are already assigned another meaning---as alists.  It  completion tables already have other meanings, and it would be
1263  would be unreliable to fail to handle an alist normally because it is  unreliable to treat one differently just because it is also a possible
1264  also a possible function.  So you must arrange for any function you wish  function.  So you must arrange for any function you wish to use for
1265  to use for completion to be encapsulated in a symbol.  completion to be encapsulated in a symbol.
1266    
1267    Emacs uses programmed completion when completing file names.    Emacs uses programmed completion when completing file names.
1268  @xref{File Name Completion}.  @xref{File Name Completion}.
1269    
1270    @defmac dynamic-completion-table function
1271    This macro is a convenient way to write a function that can act as
1272    programmed completion function.  The argument @var{function} should be
1273    a function that takes one argument, a string, and returns an alist of
1274    possible completions of it.  You can think of
1275    @code{dynamic-completion-table} as a transducer between that interface
1276    and the interface for programmed completion functions.
1277    @end defmac
1278    
1279  @node Yes-or-No Queries  @node Yes-or-No Queries
1280  @section Yes-or-No Queries  @section Yes-or-No Queries
1281  @cindex asking the user questions  @cindex asking the user questions
# Line 1570  The current value of this variable is us Line 1627  The current value of this variable is us
1627  locally inside the minibuffer (@pxref{Help Functions}).  locally inside the minibuffer (@pxref{Help Functions}).
1628  @end defvar  @end defvar
1629    
1630    @defun minibufferp &optional buffer
1631    This function returns non-@code{nil} if @var{buffer} is a minibuffer.
1632    If @var{buffer} is omitted, it tests the current buffer.
1633    @end defun
1634    
1635  @defun active-minibuffer-window  @defun active-minibuffer-window
1636  This function returns the currently active minibuffer window, or  This function returns the currently active minibuffer window, or
1637  @code{nil} if none is currently active.  @code{nil} if none is currently active.
# Line 1604  object.  When the function @code{scroll- Line 1666  object.  When the function @code{scroll-
1666  minibuffer, it scrolls this window.  minibuffer, it scrolls this window.
1667  @end defvar  @end defvar
1668    
1669    @defun minibuffer-selected-window
1670    This function returns the window which was selected when the
1671    minibuffer was entered.  If selected window is not a minibuffer
1672    window, it returns @code{nil}.
1673    @end defun
1674    
1675  Finally, some functions and variables deal with recursive minibuffers  Finally, some functions and variables deal with recursive minibuffers
1676  (@pxref{Recursive Editing}):  (@pxref{Recursive Editing}):
1677    
# Line 1631  that is non-@code{nil}, then the command Line 1699  that is non-@code{nil}, then the command
1699  arguments even if it is invoked from the minibuffer.  The minibuffer  arguments even if it is invoked from the minibuffer.  The minibuffer
1700  command @code{next-matching-history-element} (normally @kbd{M-s} in the  command @code{next-matching-history-element} (normally @kbd{M-s} in the
1701  minibuffer) uses this feature.  minibuffer) uses this feature.
1702    
1703    @defun minibuffer-message string &optional timeout
1704    This function displays @var{string} temporarily at the end of the
1705    minibuffer text, for @var{timeout} seconds.  (The default is 2
1706    seconds.)
1707    @end defun
1708    
1709    @ignore
1710       arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
1711    @end ignore

Legend:
Removed from v.1.29.2.1  
changed lines
  Added in v.1.29.2.2

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