29.13.4 显示缓冲区的附加选项

缓冲区显示动作的行为 (see 为显示缓冲区选择窗口) 可以通过下面的用户选项进一步调整。

User Option: pop-up-windows

如果该变量的值为非 nil,则 display-buffer 允许分割现有窗口,创建一个新窗口用于显示缓冲区。这是默认行为。

该变量仅为向后兼容而提供。display-buffer 通过 display-buffer-fallback-action 中的特殊机制遵守该选项:当此选项值为非 nil 时,调用动作函数 display-buffer-pop-up-window (see 缓冲区显示动作函数)。display-buffer-pop-up-window 本身不会查询该变量,用户可以在 display-buffer-alist 等处直接指定它。

User Option: split-window-preferred-function

该变量指定一个用于分割窗口的函数,以便创建新窗口显示缓冲区。它由动作函数 display-buffer-pop-up-window 调用,实际执行窗口分割。

该值必须是一个单参数函数,参数为一个窗口,返回新窗口(将用于显示目标缓冲区)或 nil(表示分割失败)。默认值为 split-window-sensibly,其说明见下。

Function: split-window-sensibly &optional window

该函数尝试分割 window 并返回新创建的窗口。如果 window 无法分割,则返回 nil。如果 window 被省略或为 nil,则默认使用当前选中窗口。

该函数遵守控制窗口能否分割的常规规则 (see 拆分窗口)。它首先尝试在下方新建窗口,同时受 split-height-threshold 限制(见下文)以及其他约束。如果失败,则尝试在右侧新建窗口,受 split-width-threshold 限制。如果仍然失败,且该窗口是其框架上的唯一窗口,则忽略 split-height-threshold 再次尝试向下分割。如果依旧失败,函数放弃并返回 nil

User Option: split-height-threshold

该变量控制 split-window-sensibly 是否允许向下分割窗口。若为整数,表示仅当原窗口至少有这么多行时才分割。若为 nil,表示不允许这种分割方式。

User Option: split-width-threshold

该变量控制 split-window-sensibly 是否允许向右分割窗口。若为整数,表示仅当原窗口至少有这么多列时才分割。若为 nil,表示不允许这种分割方式。

User Option: even-window-sizes

如果该变量非 nil,则当 display-buffer 复用一个现有窗口,且该窗口与选中窗口相邻时,会自动均分窗口大小。

如果值为 width-only,则仅当复用窗口在选中窗口左侧或右侧、且选中窗口更宽时才均分宽度。如果值为 height-only,则仅当复用窗口在选中窗口上方或下方、且选中窗口更高时才均分高度。其他非 nil 值表示只要选中窗口在组合尺寸上更大,就会在上述任意情况下均分大小。

User Option: pop-up-frames

如果该变量的值为非 nil,表示 display-buffer 可以通过创建新框架来显示缓冲区。默认值为 nil

nil 值还表示,当 display-buffer 寻找已显示 buffer-or-name 的窗口时,可以搜索所有可见或最小化的框架,而不仅是选中框架。

display-bufferalist 中同名条目优先级高于该变量。

该变量主要为向后兼容提供。display-buffer 通过 display-buffer-fallback-action 中的特殊机制遵守该选项:当值为非 nil 时调用动作函数 display-buffer-pop-up-frame (see 缓冲区显示动作函数),这一操作会在尝试分割窗口之前执行。display-buffer-pop-up-frame 本身不会查询该变量,用户可在 display-buffer-alist 等处直接指定。

User Option: pop-up-frame-function

该变量指定一个用于创建新框架的函数,以便生成新窗口显示缓冲区。它由动作函数 display-buffer-pop-up-frame 使用。

该值应为一个无参函数,返回一个框架;若无法创建框架则返回 nil。默认是一个使用 pop-up-frame-alist 指定参数创建框架的函数(见下文)。

User Option: pop-up-frame-alist

该变量保存框架参数关联列表 (see 框架参数),由 pop-up-frame-function 指定的函数用于创建新框架。默认值为 nil

该选项仅为向后兼容提供。注意,当 display-buffer-pop-up-frame 调用 pop-up-frame-function 指定的函数时,会将所有 pop-up-frame-parameters 动作列表条目添加到 pop-up-frame-alist 前面,使动作列表中的参数覆盖 pop-up-frame-alist 中的对应值。

因此,用户应在 display-buffer-alist 中设置 pop-up-frame-parameters 动作列表条目,而不是自定义 pop-up-frame-alist。只有这样才能保证用户设置的参数覆盖 display-buffer 调用方指定的参数。

display-buffer 在设计中做了大量工作,以保持与使用旧选项的代码兼容,例如 pop-up-windowspop-up-framespop-up-frame-alistsame-window-buffer-namessame-window-regexps。Lisp 程序与用户应避免使用这些旧选项。上文已经提醒不要自定义 pop-up-frame-alist,本节说明如何将其余旧选项转换为使用显示动作的方式。

pop-up-windows

该变量默认为 t。与其将其设为 nil 来禁止 display-buffer 的某些行为,更好的做法是在 display-buffer-base-action 中列出希望尝试的动作函数,例如:

(setopt
 display-buffer-base-action
 '((display-buffer-reuse-window display-buffer-same-window
    display-buffer-in-previous-window
    display-buffer-use-some-window)))
pop-up-frames

与其将该变量设为 t,可以自定义 display-buffer-base-action,例如:

(setopt display-buffer-base-action '(nil (pop-up-frames . t)))
same-window-buffer-names
same-window-regexps

与其向这些选项添加缓冲区名或正则表达式,不如为对应缓冲区在 display-buffer-alist 中添加条目,指定动作函数 display-buffer-same-window

(setopt
 display-buffer-alist
 (cons '("\\*foo\\*" (display-buffer-same-window))
        display-buffer-alist))