[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

21.7.2 Reading One Event

The lowest level functions for command input are those that read a single event.

Function: 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 the optional argument prompt is non-nil, it should be a string to display in the echo area as a prompt. Otherwise, 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. See section 38.4 The Echo Area.

If inherit-input-method is non-nil, then the current input method (if any) is employed to make it possible to enter a non-ASCII character. Otherwise, input method handling is disabled for reading this event.

If cursor-in-echo-area is non-nil, then read-event moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise read-event does not move the cursor.

If read-event gets an event that is defined as a help character, in some cases read-event processes the event directly without returning. See section 24.5 Help Functions. Certain other events, called special events, are also processed directly within read-event (see section 21.8 Special Events).

Here is what happens if you call read-event and then press the right-arrow function key:

 
(read-event)
     => right

Function: 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), read-char signals an error. The arguments work as in read-event.

In the first example, the user types the character 1 (ASCII code 49). The second example shows a keyboard macro definition that calls read-char from the minibuffer using eval-expression. read-char reads the keyboard macro's very next character, which is 1. Then eval-expression displays its return value in the echo area.

 
(read-char)
     => 49

;; We assume here you use M-: to evaluate this.
(symbol-function 'foo)
     => "^[:(read-char)^M1"
(execute-kbd-macro 'foo)
     -| 49
     => nil

Function: 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, read-char-exclusive ignores it and reads another event, until it gets a character. The arguments work as in read-event.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on May 2, 2002 using texi2html