Lisp 程序使用临时显示将输出放入缓冲区并呈现给用户查看,而非用于编辑。许多帮助命令都使用此功能。
该函数执行 body 中的表达式,同时将其打印输出插入名为 buffer-name 的缓冲区(必要时先创建),并设为帮助模式。(参见下方类似宏 with-temp-buffer-window。)最后,该缓冲区会在某个框架中显示,但该框架不会被选中。
若 body 中的表达式未修改输出缓冲区的主模式,执行结束时仍为帮助模式,
则 with-output-to-temp-buffer 会在最后将该缓冲区设为只读,并扫描其中的函数与变量名,将其转为可点击交叉引用。See Tips for Documentation Strings, 尤其文档字符串中超链接相关条目,可查看更多细节。
字符串 buffer-name 指定临时缓冲区,该缓冲区无需预先存在。参数必须为字符串而非缓冲区。
缓冲区会先被清空(无提示),并在 with-output-to-temp-buffer 退出后标记为未修改。
with-output-to-temp-buffer 将 standard-output 绑定到临时缓冲区,然后执行 body 中的表达式。
body 内使用 Lisp 输出函数产生的输出默认写入该缓冲区(但屏幕显示与回显区消息虽属广义 “输出(output)”,不受影响)。
See 输出函数。
提供若干钩子用于自定义该结构行为,列于下方。
返回 body 中最后一个表达式的值。
---------- Buffer: foo ---------- This is the contents of foo. ---------- Buffer: foo ----------
(with-output-to-temp-buffer "foo"
(print 20)
(print standard-output))
⇒ #<buffer foo>
---------- Buffer: foo ----------
20
#<buffer foo>
---------- Buffer: foo ----------
若该变量非 nil,with-output-to-temp-buffer 会将其作为函数调用,负责显示帮助缓冲区。
该函数接收一个参数,即需要显示的缓冲区。
该函数最好在 save-selected-window 内部、选中目标框架与缓冲区的情况下,
像 with-output-to-temp-buffer 常规做法一样运行 temp-buffer-show-hook。
该常规钩子由 with-output-to-temp-buffer 在执行 body 前运行。钩子运行时,临时缓冲区为当前缓冲区。
该钩子通常绑定一个将缓冲区设为帮助模式的函数。
该常规钩子由 with-output-to-temp-buffer 在显示临时缓冲区后运行。钩子运行时,临时缓冲区为当前缓冲区,
显示该缓冲区的框架被选中。
该宏与 with-output-to-temp-buffer 类似。同该结构一样,它执行 body,
并将打印输出插入 buffer-or-name 指定的缓冲区,再在某个框架中显示。
但与 with-output-to-temp-buffer 不同,它不会自动将该缓冲区切换为帮助模式。
参数 buffer-or-name 指定临时缓冲区。可以是已存在的缓冲区,或字符串(必要时创建同名缓冲区)。
with-temp-buffer-window 退出时,该缓冲区会标记为未修改且只读。
该宏不会调用 temp-buffer-show-function,而是将 action 参数传给 display-buffer
(see 为显示缓冲区选择窗口)以显示缓冲区。
返回 body 中最后一个表达式的值,除非指定了 quit-function。 此时会以两个参数调用它:显示缓冲区的框架与 body 的执行结果。 最终返回值为 quit-function 的返回值。
该宏使用常规钩子 temp-buffer-window-setup-hook 与 temp-buffer-window-show-hook,
替代 with-output-to-temp-buffer 运行的对应钩子。
下面两种结构与 with-temp-buffer-window 基本一致,仅存在指定差异:
该宏与 with-temp-buffer-window 类似,但会使 buffer-or-name 指定的缓冲区
成为执行 body 时的当前缓冲区。
显示临时缓冲区的框架可通过以下模式适配缓冲区大小:
启用该次要模式时,显示临时缓冲区的框架会自动调整尺寸以适配缓冲区内容。
框架仅在专为该缓冲区创建时才会被调整大小。特别地,此前显示过其他缓冲区的框架不会被调整。
默认情况下,该模式使用 fit-window-to-buffer(see 调整窗口大小)调整尺寸。
你可通过自定义下方选项 temp-buffer-max-height 与 temp-buffer-max-width 指定其他函数。
可为 display-buffer 提供合适的 window-height、window-width 或 window-size 动作列表项,
以覆盖该选项效果。see 缓冲区显示动作关联列表。
该选项指定启用 temp-buffer-resize-mode 时,显示临时缓冲区的框架最大高度(行数)。
它也可以是一个函数,用于为该类缓冲区选择高度,接收一个缓冲区参数并返回正整数。
函数调用时,待调整的框架已被选中。
该选项指定启用 temp-buffer-resize-mode 时,显示临时缓冲区的框架最大宽度(列数)。
它也可以是一个函数,用于为该类缓冲区选择宽度,接收一个缓冲区参数并返回正整数。
函数调用时,待调整的框架已被选中。
下面函数使用当前缓冲区进行临时显示:
该函数在当前缓冲区的 position 位置临时显示 string。 它不影响撤销列表或缓冲区修改状态。
临时显示会持续到下次输入事件。若下次输入事件为 char,
momentary-string-display 会忽略该事件并返回。
否则该事件会被缓存供后续输入使用。因此,输入 char 仅会移除显示的字符串,
而输入(例如)C-f 会先移除字符串,之后(通常)向前移动光标。
参数 char 默认为空格。
momentary-string-display 的返回值无实际意义。
若字符串 string 不包含控制字符,你可通过创建(随后删除)带有 before-string 属性的覆盖层,
以更通用的方式实现相同效果。See 覆盖层属性。
若 message 非 nil,则在缓冲区显示 string 时,该信息会显示在回显区。
若为 nil,则使用默认提示,说明输入 char 继续。
本示例中,光标初始位于第二行开头:
---------- Buffer: foo ---------- This is the contents of foo. ∗Second line. ---------- Buffer: foo ----------
(momentary-string-display "**** Important Message! ****" (point) ?\r "Type RET when done reading") ⇒ t
---------- Buffer: foo ---------- This is the contents of foo. **** Important Message! ****Second line. ---------- Buffer: foo ---------- ---------- Echo Area ---------- Type RET when done reading ---------- Echo Area ----------