Function: read-char-choice-with-read-key

read-char-choice-with-read-key is a byte-compiled function defined in subr.el.gz.

Signature

(read-char-choice-with-read-key PROMPT CHARS &optional INHIBIT-KEYBOARD-QUIT)

Documentation

Read and return one of the characters in CHARS, prompting with PROMPT.

CHARS should be a list of single characters. Any input that is not one of CHARS is ignored.

If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore keyboard-quit events while waiting for valid input.

If you bind the variable help-form to a non-nil value while calling this function, then pressing help-char causes it to evaluate help-form and display the result.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun read-char-choice-with-read-key (prompt chars &optional inhibit-keyboard-quit)
  "Read and return one of the characters in CHARS, prompting with PROMPT.
CHARS should be a list of single characters.
Any input that is not one of CHARS is ignored.

If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore
`keyboard-quit' events while waiting for valid input.

If you bind the variable `help-form' to a non-nil value
while calling this function, then pressing `help-char'
causes it to evaluate `help-form' and display the result."
  (unless (consp chars)
    (error "Called `read-char-choice' without valid char choices"))
  (let (char done show-help (helpbuf " *Char Help*"))
    (let ((cursor-in-echo-area t)
          (executing-kbd-macro executing-kbd-macro)
	  (esc-flag nil))
      (save-window-excursion	      ; in case we call help-form-show
	(while (not done)
	  (unless (get-text-property 0 'face prompt)
	    (setq prompt (propertize prompt 'face 'minibuffer-prompt)))
          ;; Display the on screen keyboard if it exists.
          (frame-toggle-on-screen-keyboard (selected-frame) nil)
	  (setq char (let ((inhibit-quit inhibit-keyboard-quit))
		       (read-key prompt)))
	  (and show-help (buffer-live-p (get-buffer helpbuf))
	       (kill-buffer helpbuf))
	  (cond
	   ((not (numberp char)))
	   ;; If caller has set help-form, that's enough.
	   ;; They don't explicitly have to add help-char to chars.
	   ((and help-form
		 (eq char help-char)
		 (setq show-help t)
		 (help-form-show)))
	   ((memq char chars)
	    (setq done t))
	   ((not inhibit-keyboard-quit)
	    (cond
	     ((and (null esc-flag) (eq char ?\e))
	      (setq esc-flag t))
	     ((memq char '(?\C-g ?\e))
	      (keyboard-quit))))
	   (t
	    (beep)
	    (message "Please type %s"
		     (substitute-command-keys
		      (mapconcat (lambda (c)
				   (format "\\`%s'"
					   (single-key-description c)))
				 chars ", ")))
	    (sit-for 3))))))
    ;; Display the question with the answer.  But without cursor-in-echo-area.
    (message "%s%s" prompt (char-to-string char))
    char))