命令输入的最低层级函数为 read-event、read-char 和 read-char-exclusive。
若需使用迷你缓冲区读取字符,可使用 read-char-from-minibuffer(see 提出多选问题)。
该函数读取并返回下一个命令输入事件,必要时会等待直至有事件可用。
返回的事件可能直接来自用户,也可能来自键盘宏。它不会经过键盘输入编码系统解码(详见 see Terminal I/O Encoding)。
若可选参数 prompt 非 nil,则应为字符串,会显示在回显区作为提示。若 prompt 为
nil 或字符串 ‘""’,read-event 不会显示任何提示信息表明正在等待输入;
而是通过回显方式提示:显示导致当前命令执行或被当前命令读取的事件描述。See The Echo Area。
若 inherit-input-method 非 nil,则会启用当前输入法(若有),允许输入非
ASCII 字符。否则,读取此事件时禁用输入法处理。
若 cursor-in-echo-area 非 nil,则 read-event 会将光标临时移至回显区,
置于已显示消息的末尾。否则 read-event 不会移动光标。
若 seconds 非 nil,则应为数字,指定等待输入的最长时间(以秒为单位)。若在该时间内
无输入到达,read-event 会停止等待并返回 nil。浮点数类型的 seconds 表示等待
小数秒数。部分系统仅支持整数秒数,此类系统会将 seconds 向下取整。若 seconds 为
nil,read-event 会一直等待直至有输入到达。
若 seconds 为 nil,则 Emacs 在等待用户输入期间会被视为空闲状态。空闲计时器——即
通过 run-with-idle-timer 创建的计时器(see Idle Timers)——可在此期间运行。
但如果 seconds 非 nil,则空闲状态保持不变:若调用 read-event 时 Emacs 处于
非空闲状态,则在 read-event 执行期间始终保持非空闲;若 Emacs 处于空闲状态(例如调用发生
在空闲计时器内部),则始终保持空闲。
若 read-event 接收到被定义为帮助字符的事件,则在某些情况下会直接处理该事件而不返回。
See 帮助函数。某些其他事件(称为 特殊事件(special events))也会在 read-event 内部
直接处理(see 特殊事件)。
以下示例展示调用 read-event 后按下右箭头功能键的结果:
(read-event)
⇒ right
该函数读取并返回一个字符输入事件。若用户生成的事件非字符(如鼠标点击或功能键事件),
read-char 会抛出错误。参数用法与 read-event 相同。
若事件带有修饰符,Emacs 会尝试解析并返回对应字符的编码。例如,用户按下 C-a 时,函数返回 1,
即 ‘C-a’ 字符的 ASCII 编码。若部分修饰符无法体现在字符编码中,read-char 会
在返回的事件中保留未解析的修饰位。例如,用户按下 C-M-a 时,函数返回 134217729(十六进制
为 8000001)——即带有 Meta 修饰位的 ‘C-a’。此值并非有效的字符编码:无法通过
characterp 测试(see Character Codes)。可使用 event-basic-type
(see 事件分类)提取去除修饰位后的字符编码;使用 event-modifiers
测试 read-char 返回的字符事件中的修饰符。
以下第一个示例中,用户按下字符 1(ASCII 编码 49)。第二个示例展示一个键盘宏定义,
该宏通过 eval-expression 从迷你缓冲区调用 read-char。read-char 读取键盘宏
的下一个字符(即 1),随后 eval-expression 在回显区显示其返回值。
(read-char)
⇒ 49
;; 假设此处使用 M-: 执行这段代码。
(symbol-function 'foo)
⇒ "^[:(read-char)^M1"
(execute-kbd-macro 'foo)
⊣ 49
⇒ nil
该函数读取并返回一个字符输入事件。若用户生成的事件非字符事件,read-char-exclusive 会
忽略该事件并继续读取下一个事件,直至获取到字符。参数用法与 read-event 相同。返回值可能
包含修饰位,与 read-char 一致。
上述函数均不抑制退出操作。
此变量存储从终端接收的输入事件总数——不计入键盘宏生成的事件。
需要强调的是,与 read-key-sequence 不同,read-event、read-char 和
read-char-exclusive 不会执行 事件序列翻译键盘映射 中描述的转换操作。若你希望读取
单个按键并考虑这些转换(例如,在终端中读取 功能键,或从 xterm-mouse-mode
读取 鼠标事件),可使用函数 read-key:
该函数读取单个按键。它介于 read-key-sequence 和 read-event 之间:与前者不同,
它仅读取单个按键而非按键序列;与后者不同,它不会返回原始事件,而是根据
input-decode-map、local-function-key-map 和 key-translation-map
(see 事件序列翻译键盘映射)对用户输入进行解码和转换。
参数 prompt 可为字符串(会显示在回显区作为提示),或 nil(表示不显示提示)。
若参数 disable-fallbacks 非 nil,则不应用 read-key-sequence 中针对未绑定
按键的常规回退逻辑。这意味着不会丢弃鼠标按下按钮事件和多点击事件,且不会应用
local-function-key-map 和 key-translation-map。若为 nil 或未指定,
仅禁用最后一个事件的小写转换这一回退逻辑。
该函数使用 read-from-minibuffer 读取并返回 chars 中的单个字符(chars 应为
单个字符组成的列表)。它会丢弃所有非 chars 成员的输入字符,并显示相应提示信息。
可选参数 inhibit-quit 默认被忽略,但如果变量 read-char-choice-use-read-key 非
nil,此函数会使用 read-key 而非 read-from-minibuffer,此时若
inhibit-quit 非 nil,表示在等待有效输入期间忽略键盘退出事件。此外,若
read-char-choice-use-read-key 非 nil,调用此函数时将 help-form
(see 帮助函数)绑定为非 nil 值,会在用户按下 help-char 时计算
help-form 并显示结果;随后继续等待有效输入字符或键盘退出事件。
向用户提出一道多项选择题。prompt 应为字符串,作为提示显示。
choices 为关联列表(alist),每个条目包含:第一个元素为需输入的字符,第二个元素为提示时 显示的条目短名称(若空间不足可能被缩短),第三个可选元素为详细说明(用户请求更多帮助时会 显示在帮助缓冲区中)。
若可选参数 help-string 非 nil,则应为字符串,包含所有选项的详细描述。用户按下
? 时,会在帮助缓冲区显示此字符串,而非默认自动生成的描述。
若可选参数 show-help 非 nil,则会立即显示帮助缓冲区(在用户输入前)。若为字符串,
则将其用作帮助缓冲区的名称。
若可选参数 long-form 非 nil,用户需输入长格式答案(使用 completing-read),
而非按下单个按键。答案必须是 choices 列表中条目的第二个元素。
返回值为 choices 中匹配的条目。
(read-multiple-choice "Continue connecting?" '((?a "always" "Accept certificate for this and future sessions.") (?s "session only" "Accept certificate this session only.") (?n "no" "Refuse to use certificate, close connection.")))
在图形终端中,read-multiple-choice-face 面(face)用于高亮名称字符串中的匹配字符。