GNU Info

(elisp)Reading One Event

---

Next: Invoking the Input Method Prev: Key Sequence Input Up: Reading Input

---

Enter node , (file) or (file)node

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.  Note: 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.  Note: Help Functions.  Certain other events, called
     "special events", are also processed directly within `read-event'
     (Note: 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'.