Info Catalog elisp: Key Sequence Input elisp: Reading Input elisp: Event Mod

elisp: Reading One Event

 
 20.8.2 Reading One Event
 ------------------------
 
 The lowest level functions for command input are ‘read-event’,
 ‘read-char’, and ‘read-char-exclusive’.
 
  -- Function: read-event &optional prompt inherit-input-method seconds
      This function reads and returns the next event of command input,
      waiting if necessary until an event is available.
 
      The returned event may come directly from the user, or from a
      keyboard macro.  It is not decoded by the keyboard’s input coding
      system (Terminal I/O Encoding).
 
      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.  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 SECONDS is non-‘nil’, it should be a number specifying the
      maximum time to wait for input, in seconds.  If no input arrives
      within that time, ‘read-event’ stops waiting and returns ‘nil’.  A
      floating point SECONDS means to wait for a fractional number of
      seconds.  Some systems support only a whole number of seconds; on
      these systems, SECONDS is rounded down.  If SECONDS is ‘nil’,
      ‘read-event’ waits as long as necessary for input to arrive.
 
      If SECONDS is ‘nil’, Emacs is considered idle while waiting for
      user input to arrive.  Idle timers—those created with
      ‘run-with-idle-timer’ (Idle Timers)—can run during this
      period.  However, if SECONDS is non-‘nil’, the state of idleness
      remains unchanged.  If Emacs is non-idle when ‘read-event’ is
      called, it remains non-idle throughout the operation of
      ‘read-event’; if Emacs is idle (which can happen if the call
      happens inside an idle timer), it remains idle.
 
      If ‘read-event’ gets an event that is defined as a help character,
      then in some cases ‘read-event’ processes the event directly
      without returning.  Help Functions.  Certain other events,
      called “special events”, are also processed directly within
      ‘read-event’ (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 seconds
      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
           seconds
      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’.
 
    None of the above functions suppress quitting.
 
  -- Variable: num-nonmacro-input-events
      This variable holds the total number of input events received so
      far from the terminal—not counting those generated by keyboard
      macros.
 
    We emphasize that, unlike ‘read-key-sequence’, the functions
 ‘read-event’, ‘read-char’, and ‘read-char-exclusive’ do not perform the
 translations described in Translation Keymaps.  If you wish to
 read a single key taking these translations into account, use the
 function ‘read-key’:
 
  -- Function: read-key &optional prompt
      This function reads a single key.  It is intermediate between
      ‘read-key-sequence’ and ‘read-event’.  Unlike the former, it reads
      a single key, not a key sequence.  Unlike the latter, it does not
      return a raw event, but decodes and translates the user input
      according to ‘input-decode-map’, ‘local-function-key-map’, and
      ‘key-translation-map’ (Translation Keymaps).
 
      The argument PROMPT is either a string to be displayed in the echo
      area as a prompt, or ‘nil’, meaning not to display a prompt.
 
  -- Function: read-char-choice prompt chars &optional inhibit-quit
      This function uses ‘read-key’ to read and return a single
      character.  It ignores any input that is not a member of CHARS, a
      list of accepted characters.  Optionally, it will also ignore
      keyboard-quit events while it is waiting for valid input.  If you
      bind ‘help-form’ (Help Functions) to a non-‘nil’ value
      while calling ‘read-char-choice’, then pressing ‘help-char’ causes
      it to evaluate ‘help-form’ and display the result.  It then
      continues to wait for a valid input character, or keyboard-quit.
 

Info Catalog elisp: Key Sequence Input elisp: Reading Input elisp: Event Mod