动作关联列表(action alist) 是一个关联列表,它将动作函数能够识别的预定义符号,映射到这些函数需要按规则解析的对应值。在每次调用时,display-buffer 都会构建一个新的、可能为空的动作关联列表,并将整个列表传递给它调用的所有动作函数。
按照设计,动作函数可以自由解释动作关联列表中的条目。实际上,有些条目如 allow-no-window 或 previous-window 只对一个或少数几个动作函数有意义,其余函数会直接忽略。另一些条目,如 inhibit-same-window 或 window-parameters,则要求绝大多数动作函数都予以遵守,包括应用程序和外部扩展包提供的函数。
在上一小节中,我们详细说明了各个动作函数如何处理它们关心的动作关联列表条目。本节按符号列出所有已知的动作关联列表条目,同时说明其取值含义,以及能够识别它们的动作函数 (see 缓冲区显示动作函数)。在整个列表中,“缓冲区”均指 display-buffer 需要显示的缓冲区,“值”指条目的取值。
inhibit-same-window ¶如果值为非 nil,表示禁止使用当前选中窗口显示该缓冲区。所有会(重)复用现有窗口的动作函数都应当遵守该条目。
previous-window ¶值必须指定一个曾经显示过该缓冲区的窗口。display-buffer-in-previous-window 会优先选择这类窗口,前提是该窗口仍然存活,并且没有专用于其他缓冲区。
mode ¶值可以是一个主模式,或者一个主模式列表。当该条目指定的值与某个窗口所显示缓冲区的主模式匹配时,display-buffer-reuse-mode-window 可以复用该窗口。其他动作函数会忽略该条目。
frame-predicate ¶值必须是一个单参数函数,参数为一个框架,如果该框架适合显示缓冲区则返回非 nil。该条目由 display-buffer-use-some-frame 使用。
reusable-frames ¶值指定需要搜索的框架集合,用于查找已经显示该缓冲区、因此可以被复用的窗口。可以设置为:
nil 表示只考虑选中框架上的窗口。(实际是最近使用过的、非纯迷你缓冲区的框架。)
visible 表示考虑所有可见框架上的窗口。
t 表示考虑所有框架上的窗口。注意该值很少适用,可能会返回提示框框架。
注意 nil 的含义与 next-window 的 all-frames 参数略有不同 (see 窗口循环顺序)。
该条目的主要使用者是 display-buffer-reuse-window,但其他所有尝试复用窗口的动作函数都会受其影响。display-buffer-in-previous-window 在其他框架上搜索曾显示该缓冲区的窗口时也会参考该条目。
inhibit-switch-frame ¶如果值为非 nil,当 display-buffer 选中的窗口位于另一个框架时,禁止将该框架前置或选中。主要受影响的函数是 display-buffer-use-some-frame 和 display-buffer-reuse-window。理想情况下 display-buffer-pop-up-frame 也应受影响,但无法保证窗口管理器会配合执行。
window-parameters ¶值指定要赋予选中窗口的窗口参数关联列表。所有选择窗口的动作函数都应当处理该条目。
window-min-width ¶值以标准框架列数指定所用窗口的最小宽度。特殊值 full-width 表示选中的窗口在其框架内左右两侧没有其他窗口。
该条目目前由 display-buffer-use-some-window 和 display-buffer-use-least-recent-window 遵守,它们会尽量避免返回不满足该条件的最近最少使用窗口。
注意仅提供该条目不一定能让窗口达到指定宽度。要真正将现有窗口或新建窗口调整到该值对应的宽度,还需要同时提供指定该值的 window-width 条目。不过 window-width 也可以指定完全不同的值,或要求窗口宽度自适应其缓冲区,此时 window-min-width 提供窗口的保证最小宽度。
window-min-height ¶值以标准框架行数指定所用窗口的最小高度。特殊值 full-height 表示选中的窗口为全高窗口,在其框架内上下没有其他窗口。
该条目目前由 display-buffer-below-selected 遵守,它不会使用未达到指定高度的窗口。display-buffer-use-some-window 和 display-buffer-use-least-recent-window 也会遵守,尽量避免返回不满足该约束的最近最少使用窗口。
注意仅提供该条目不一定能让窗口达到指定高度。要真正将现有窗口或新建窗口调整到该值对应的高度,还需要同时提供指定该值的 window-height 条目。不过 window-height 也可以指定完全不同的值,或要求窗口高度自适应其缓冲区,此时 window-min-height 提供所用窗口的保证最小高度。
window-height ¶值指定是否以及如何调整选中窗口的高度,可以是以下之一:
nil 表示不调整选中窗口的高度。
body-lines,CDR 为整数,以框架行数指定选中窗口主体的高度。
fit-window-to-buffer 和 shrink-window-if-larger-than-buffer,见 调整窗口大小。
按照惯例,只有当窗口属于垂直组合结构时才会调整其高度 (see 窗口与框架),以避免改变其他无关窗口的高度。同时,该条目只应在本列表下方说明的特定条件下处理。
window-width ¶该条目与前面的 window-height 类似,只是用于调整选中窗口的宽度。值可以是以下之一:
nil 表示不调整选中窗口的宽度。
body-columns,CDR 为整数,以框架列数指定选中窗口主体的宽度。
window-size ¶该条目是前两个条目的组合,可同时调整选中窗口的高度和宽度。由于窗口只能在一个方向上调整大小而不影响其他窗口,window-size 只对独占整个框架的窗口有效。值可以是以下之一:
nil 表示不调整选中窗口的大小。
body-chars,CDR 为两个整数组成的 cons 单元,以框架列数和行数指定选中窗口主体的宽高,效果是相应调整框架大小。
该条目只应在本列表下方说明的特定条件下处理。
dedicated ¶如果值为非 nil,该条目告知 display-buffer 将其创建的所有窗口标记为专属于对应缓冲区 (see 专用窗口)。实现方式是调用 set-window-dedicated-p,以选中窗口为第一个参数,条目值为第二个参数。侧边窗口默认以 side 为值设为专用 (see 侧边窗口选项与函数)。
preserve-size ¶如果值为非 nil,该条目告知 Emacs 保留选中窗口的大小 (see 保留窗口尺寸)。值应当是 (t . nil) 保留宽度、(nil . t) 保留高度,或 (t . t) 同时保留宽高。该条目只应在本列表之后说明的特定条件下处理。
lru-frames ¶值指定需要搜索的框架集合,用于查找可用于显示该缓冲区的窗口。display-buffer-use-some-window 和 display-buffer-use-least-recent-window 在寻找显示其他缓冲区的最近最少使用窗口时会遵守该条目。其取值与上面的 reusable-frames 相同。
lru-time ¶值用于指定一个使用时间 (see 选中窗口)。display-buffer-use-some-window 和 display-buffer-use-least-recent-window 在寻找显示其他缓冲区的最近最少使用窗口时会遵守该条目。如果某个窗口的使用时间高于该选项指定的值,这些动作函数不会考虑用它显示缓冲区。
bump-use-time ¶如果值为非 nil,该条目会让 display-buffer 提升所用窗口的使用时间 (see 选中窗口)。这可以避免后续 display-buffer-use-some-window 和 display-buffer-use-least-recent-window 等动作函数使用该窗口显示其他缓冲区。
使用该条目与使用动作函数 display-buffer-use-least-recent-window 存在细微区别。调用后者只会提升它用于显示缓冲区的窗口的使用时间。而该条目会让 display-buffer 提升所有用于显示缓冲区的窗口的使用时间。
pop-up-frame-parameters ¶值指定创建新框架时要赋予的框架参数关联列表。唯一使用该条目的函数是 display-buffer-pop-up-frame。
pop-up-frames ¶值控制 display-buffer 是否可以通过新建框架来显示缓冲区。其含义与变量 pop-up-frames 相同,存在时优先级更高。主要用途是对用户希望保留在选中框架中的特定缓冲区,覆盖该变量的非 nil 设置。
parent-frame ¶值指定缓冲区在子框架中显示时所使用的父框架。该条目仅由 display-buffer-in-child-frame 使用。
child-frame-parameters ¶值指定缓冲区在子框架中显示时所用的框架参数关联列表。该条目仅由 display-buffer-in-child-frame 使用。
side ¶值表示创建显示缓冲区的新窗口时,应位于框架或现有窗口的哪一侧。display-buffer-in-side-window 用它指定新侧边窗口放置在框架的哪一侧 (see 在侧边窗口中显示缓冲区)。display-buffer-in-atom-window 也用它指定新窗口位于现有窗口的哪一侧 (see 原子窗口)。
slot ¶如果值为非 nil,指定用于显示缓冲区的侧边窗口槽位。该条目仅由 display-buffer-in-side-window 使用。
direction ¶值指定一个方向,配合 window 条目,让 display-buffer-in-direction 确定显示缓冲区的窗口位置。
window ¶值指定一个与 display-buffer 选中窗口存在某种关联的窗口。目前 display-buffer-in-atom-window 用它指定在哪个窗口的侧边创建新窗口。display-buffer-in-direction 也用它指定结果窗口应依附于哪个参考窗口。
allow-no-window ¶如果值为非 nil,表示 display-buffer 不一定需要显示缓冲区,且调用方已经准备好处理这种情况。该条目不面向用户定制,因为无法保证任意 display-buffer 调用方都能处理无窗口显示缓冲区的情形。唯一关心该条目的动作函数是 display-buffer-no-window。
some-window ¶如果值为 nil 或 lru,display-buffer-use-some-window 优先选择最近最少使用窗口,同时避免选择非全宽窗口和其他框架上的窗口。如果值为 mru,则优先选择最近最多使用窗口,不考虑选中窗口以及选中框架之外的窗口。如果值为函数,会以缓冲区和关联列表为两个参数调用,并返回用于显示缓冲区的窗口。
body-function ¶值必须是一个单参数函数,参数为已显示的窗口。该函数可用于向已显示窗口的主体填充内容,这些内容可能依赖窗口的尺寸。它在缓冲区显示之后、window-height、window-width 和 preserve-size 等可能调整窗口以适配内容的条目应用之前被调用。
post-command-select-window ¶如果值为非 nil,在当前命令执行完毕并运行 post-command-hook 钩子后 (see 命令循环概述),会自动选中 display-buffer 显示的缓冲区。如果值为 nil,则取消 pop-to-buffer 等函数选中的缓冲区,调用该函数前选中的窗口保持选中,无论本命令后续选中过哪些窗口。
category ¶如果 display-buffer 的调用方在 action 参数中传入关联列表条目 (category . symbol),那么就可以在 display-buffer-alist 条目的条件部分使用相同的分类符号来匹配所显示的缓冲区。See buffer-match-p. 因此,如果某个 Lisp 程序在调用 display-buffer 时使用特定符号作为分类,用户就可以在 display-buffer-alist 中加入对应条目,定制这类缓冲区的显示方式。
按照惯例,window-height、window-width 和 preserve-size 条目在选中窗口的缓冲区设置完成后应用,并且仅当该窗口此前从未显示过其他缓冲区时才生效。更精确地说,后者指该窗口必须是由当前 display-buffer 调用创建,或者是此前由 display-buffer 创建用于显示该缓冲区,并且在被当前调用复用时从未显示过其他缓冲区。
如果没有指定 window-height、window-width 或 window-size 条目,当缓冲区为临时缓冲区且启用了 temp-buffer-resize-mode 时,窗口仍可能被自动调整大小,临时显示。在这种情况下,可以使用 window-height、window-width 或 window-size 条目的 CDR,针对特定缓冲区或 display-buffer 调用,禁止或覆盖 temp-buffer-resize-mode 的默认行为。