42.4.1 在回显区显示信息

本节介绍用于在回显区显示信息的标准函数。

Function: message format-string &rest arguments

该函数在回显区显示一条信息。format-string 是格式化字符串,arguments 是对应格式说明的对象,用法与 format-message 函数一致(see 格式化字符串)。格式化后的字符串会显示在回显区;若其中包含 face 文本属性,则会按指定字体显示(see 文本的视觉样式(Faces))。该字符串同时会被添加到 *Messages* 缓冲区,但不包含文本属性(see *Messages* 中记录信息)。

通常格式化字符串中的反引号和撇号会转换为对应的弯引号,例如 "Missing `%s'" 可能显示为 "Missing ‘foo’"。如需控制或禁止该转换,可参考 See 文本引用样式

在批处理模式下,信息会被打印到标准错误流并追加换行符。

inhibit-message 为非 nil 时,信息不会显示在回显区,仅会记录到 ‘*Messages*’。

format-stringnil 或空字符串,message 会清空回显区;若回显区曾被自动扩展,此操作会将其恢复为正常高度。若小缓冲区处于激活状态,此操作会立即将小缓冲区内容重新显示在屏幕上。

(message "Reverting `%s'..." (buffer-name))
 ⊣ Reverting ‘subr.el’...
⇒ "Reverting ‘subr.el’..."

---------- Echo Area ----------
Reverting ‘subr.el’...
---------- Echo Area ----------

如需根据内容长度自动选择在回显区或弹出缓冲区显示信息,可使用 display-message-or-buffer(见下文)。

警告: 若希望原样使用自定义字符串作为信息,不要直接写 (message string)。如果 string 包含 ‘%’、‘`’ 或 ‘'’,可能会被重新格式化并产生非预期结果。应改用 (message "%s" string)

下列机制允许用户和 Lisp 程序控制回显区信息的显示方式。

Variable: set-message-function

若该变量为非 nil,其值应为一个单参数函数,参数为要在回显区显示的信息文本。message 及相关函数会调用该函数。若函数返回 nil,信息会按常规方式显示在回显区。若返回字符串,则该字符串会 替代 原信息显示在回显区。若返回其他非 nil 值,表示信息已被处理,message 将不在回显区显示任何内容。

该变量的默认值会调用下文介绍的 set-minibuffer-message

Variable: clear-message-function

若该变量为非 nil,其值应为一个无参函数;当 message 及相关函数的信息参数为 nil 或空字符串时,会调用该函数以清空回显区。

通常该函数会在显示回显区信息后、下一个输入事件到达时调用。函数应清空由 set-message-function 指定的对应函数所显示的信息,但并非必须如此。若函数希望回显区保持不清空,应返回符号 dont-clear-message;其他返回值均会导致回显区被清空。

该变量的默认值为清空激活状态小缓冲区中显示信息的函数。

User Option: set-message-functions

该用户选项的值是一个函数列表,用于处理回显区信息的显示。每个函数接收一个参数,即待显示的信息文本。若函数返回字符串,该字符串会替换原信息,列表中的下一个函数将使用新文本继续调用。若函数返回 nil,下一个函数使用原文本调用;若列表最后一个函数返回 nil,信息文本会显示在回显区。若函数返回非字符串的非 nil 值,表示信息已处理完毕,列表中后续函数不再执行。

下文介绍适合放入该选项列表的三个实用函数。

Function: set-minibuffer-message message

当小缓冲区未激活时,该函数在回显区显示 message;当小缓冲区激活时,在小缓冲区末尾显示。但若激活的小缓冲区中某字符带有 minibuffer-message 文本属性(see 具有特殊含义的文本属性),信息会显示在第一个带有该属性的字符之前。

该函数默认是 set-message-functions 列表中的唯一成员。

Function: inhibit-message message

若回显区信息 message 与用户选项 inhibit-message-regexps 列表中的任一正则表达式匹配,该函数会禁止显示该信息并返回一个非字符串的非 nil 值。因此,若该函数在 set-message-functions 列表中,当 message 匹配正则表达式时,列表中后续函数不会被调用。如需确保匹配的信息永不显示,应将该函数设为 set-message-functions 列表的第一个元素。

Function: set-multi-message message

该函数会累积连续发出的多条回显区信息,并以单个字符串返回,各条信息之间以换行符分隔。最多可累积 multi-message-max 条最近信息。若自第一条信息发出后超过 multi-message-timeout 秒,累积的信息会被清空。

Variable: inhibit-message

当该变量为非 nil 时,message 及相关函数不会在回显区显示任何信息,但信息仍会记录到 *Messages* 缓冲区。

Macro: with-temp-message message &rest body

该结构会在 body 执行期间临时在回显区显示一条信息。它先显示 message,再执行 body,最后恢复回显区原有内容并返回 body 最后一个表单的执行结果。

Function: message-or-box format-string &rest arguments

该函数与 message 类似地显示信息,但可能使用对话框而非回显区。若该函数在通过鼠标调用的命令中执行—更准确地说,若 last-nonmenu-event(see 来自命令循环的信息)为 nil 或列表—则使用对话框或弹出菜单显示信息,否则使用回显区。(该判断逻辑与 y-or-n-p 一致,可参考 Yes-or-No 查询。)

你可以在调用时将 last-nonmenu-event 绑定为合适的值,强制使用鼠标弹窗或回显区。

Function: message-box format-string &rest arguments

该函数与 message 类似地显示信息,但会尽可能使用对话框(或弹出菜单)。若终端不支持对话框或弹出菜单,则 message-box 会像 message 一样使用回显区。

Function: display-message-or-buffer message &optional buffer-name action frame

该函数显示信息 message,其可以是字符串或缓冲区。若内容长度小于由 max-mini-window-height 定义的回显区最大高度,则通过 message 在回显区显示;否则通过 display-buffer 在弹出缓冲区中显示。

返回值为回显区中显示的字符串,或弹出缓冲区所用的窗口(若使用弹窗)。

message 为字符串,可选参数 buffer-name 为使用弹窗时的缓冲区名称,默认为 *Message*。若 message 为字符串并在回显区显示,不保证其内容会被插入该缓冲区。

可选参数 actionframe 用法与 display-buffer 一致,仅在使用缓冲区显示时生效。

Function: current-message

该函数返回当前在回显区显示的信息,若无则返回 nil