diff lispref/commands.texi @ 24951:7451b1458af1

*** empty log message ***

--- a/lispref/commands.texi	Sat Jul 17 00:49:00 1999 +0000
+++ b/lispref/commands.texi	Sat Jul 17 02:15:13 1999 +0000
@@ -727,6 +727,14 @@
 of storing input events in a string (@pxref{Strings of Events}).
 @end defun
 
+@tindex clear-this-command-keys
+@defun clear-this-command-keys
+This function empties out the table of events for
+@code{this-command-keys} to return.  This is useful after reading a
+password, to prevent the password from echoing inadvertently as part of
+the next command in certain cases.
+@end defun
+
 @defvar last-nonmenu-event
 This variable holds the last input event read as part of a key sequence,
 not counting events resulting from mouse menus.
@@ -1737,6 +1745,7 @@
 @menu
 * Key Sequence Input::		How to read one key sequence.
 * Reading One Event::		How to read just one event.
+* Invoking the Input Method::   How reading an event uses the input method.
 * Quoted Character Input::	Asking the user to specify a character.
 * Event Input Misc::    	How to reread or throw away input events.
 @end menu
@@ -1846,21 +1855,22 @@
   The lowest level functions for command input are those that read a
 single event.
 
-@defun read-event &optional prompt suppress-input-method
+@defun read-event &optional prompt inherit-input-method
 This function reads and returns the next event of command input, waiting
 if necessary until an event is available.  Events can come directly from
 the user or from a keyboard macro.
 
-If @var{prompt} is non-@code{nil}, it should be a string to display in
-the echo area as a prompt.  Otherwise, @code{read-event} does not
-display any message to indicate it is waiting for input; instead, it
-prompts by echoing: it displays descriptions of the events that led to
-or were read by the current command.  @xref{The Echo Area}.
-
-If @var{suppress-input-method} is non-@code{nil}, then the current input
-method is disabled for reading this event.  If you want to read an event
-without input-method processing, always do it this way; don't try binding
-@code{input-method-function} (see below).
+If the optional argument @var{prompt} is non-@code{nil}, it should be a
+string to display in the echo area as a prompt.  Otherwise,
+@code{read-event} does not display any message to indicate it is waiting
+for input; instead, it prompts by echoing: it displays descriptions of
+the events that led to or were read by the current command.  @xref{The
+Echo Area}.
+
+If @var{inherit-input-method} is non-@code{nil}, then the current input
+method (if any) is employed to make it possible to enter a
+non-@sc{ASCII} character.  Otherwise, input method handling is disabled
+for reading this event.
 
 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
 moves the cursor temporarily to the echo area, to the end of any message
@@ -1883,9 +1893,11 @@
 @end example
 @end defun
 
-@defun read-char
-This function reads and returns a character of command input.  It
-discards any events that are not characters, until it gets a character.
+@defun read-char &optional prompt inherit-input-method
+This function reads and returns a character of command input.  If the
+user generates an event which is not a character (i.e. a mouse click or
+function key event), @code{read-char} signals an error.  The arguments
+work as in @code{read-event}.
 
 In the first example, the user types the character @kbd{1} (@sc{ASCII}
 code 49).  The second example shows a keyboard macro definition that
@@ -1913,11 +1925,21 @@
 @end example
 @end defun
 
-  @code{read-event} also invokes the current input method, if any.  If
-the value of @code{input-method-function} is non-@code{nil}, it should
-be a function; when @code{read-event} reads a printing character
-(including @key{SPC}) with no modifier bits, it calls that function,
-passing the event as an argument.
+@defun read-char-exclusive &optional prompt inherit-input-method
+This function reads and returns a character of command input.  If the
+user generates an event which is not a character,
+@code{read-char-exclusive} ignores it and reads another event, until it
+gets a character.  The arguments work as in @code{read-event}.
+@end defun
+
+@node Invoking the Input Method
+@subsection Invoking the Input Method
+
+  The event-reading functions invoke the current input method, if any
+(@pxref{Input Methods}).  If the value of @code{input-method-function}
+is non-@code{nil}, it should be a function; when @code{read-event} reads
+a printing character (including @key{SPC}) with no modifier bits, it
+calls that function, passing the character as an argument.
 
 @defvar input-method-function
 If this is non-@code{nil}, its value specifies the current input method
@@ -1943,13 +1965,12 @@
 @code{nil} first, to prevent recursion.
 
   The input method function is not called when reading the second and
-subsequent event of a key sequence.  Thus, these characters are not
-subject to input method processing.  It is usually a good idea for the
-input method processing to test the values of
-@code{overriding-local-map} and @code{overriding-terminal-local-map}; if
-either of these variables is non-@code{nil}, the input method should put
-its argument into a list and return that list with no further
-processing.
+subsequent events of a key sequence.  Thus, these characters are not
+subject to input method processing.  The input method function should
+test the values of @code{overriding-local-map} and
+@code{overriding-terminal-local-map}; if either of these variables is
+non-@code{nil}, the input method should put its argument into a list and
+return that list with no further processing.
 
 @node Quoted Character Input
 @subsection Quoted Character Input