29.4 窗口尺寸

Emacs 提供了多种函数用于获取窗口的高度和宽度。其中许多函数的返回值既可以用像素为单位,也可以用行数和列数为单位。 在图形化显示器上,行和列实际对应由框架默认字体所确定的默认字符的高度和宽度,该值由 frame-char-heightframe-char-width 返回(see 框架字体)。 因此,如果某个窗口使用不同字体或字号显示文本,该窗口返回的行高和列宽可能与其中实际显示的文本行数或列数不一致。

窗口的总高度(total height)是组成其主体以及上下装饰区域的总行数(see Emacs 窗口的基本概念)。

Function: window-total-height &optional window round

该函数以行为单位返回窗口 window 的总高度。 如果 window 被省略或为 nil,则默认为选中窗口。 如果 window 是内部窗口,返回值为其所有后代窗口占据的总高度。

如果一个窗口的像素高度并非其框架默认字符高度的整数倍,窗口占用的行数会在内部进行舍入。 舍入方式会保证:如果该窗口是父窗口,其所有子窗口的总高度之和在内部等于父窗口的总高度。 这意味着即便两个窗口像素高度相同,它们的内部总高度也可能相差一行。 这同时也意味着,如果该窗口属于垂直组合且存在下一个兄弟窗口,该兄弟窗口的最顶行可通过本窗口的最顶行与总高度之和计算得出(see 坐标与窗口)。

如果可选参数 roundceiling,该函数返回窗口像素高度除以框架字符高度后向上取整的最小整数; 如果为 floor,则返回向下取整的最大整数; 其他 round 值则返回窗口总高度的内部计数值。

窗口的总宽度(total width)是组成其主体以及左右装饰区域的总列数(see Emacs 窗口的基本概念)。

Function: window-total-width &optional window round

该函数以列为单位返回窗口 window 的总宽度。 如果 window 被省略或为 nil,则默认为选中窗口。 如果 window 是内部窗口,返回值为其所有后代窗口占据的总宽度。

如果一个窗口的像素宽度并非其框架字符宽度的整数倍,窗口占用的列数会在内部进行舍入。 舍入方式会保证:如果该窗口是父窗口,其所有子窗口的总宽度之和在内部等于父窗口的总宽度。 这意味着即便两个窗口像素宽度相同,它们的内部总宽度也可能相差一列。 这同时也意味着,如果该窗口属于水平组合且存在下一个兄弟窗口,该兄弟窗口的最左列可通过本窗口的最左列与总宽度之和计算得出(see 坐标与窗口)。 可选参数 round 的行为与 window-total-height 一致。

Function: window-total-size &optional window horizontal round

该函数返回窗口 window 的总高度(行数)或总宽度(列数)。 如果 horizontal 被省略或为 nil,等价于对 window 调用 window-total-height; 否则等价于调用 window-total-width。 可选参数 round 的行为与 window-total-height 一致。

以下两个函数可用于以像素为单位返回窗口的总尺寸。

Function: window-pixel-height &optional window

该函数以像素为单位返回窗口 window 的总高度。 window 必须是有效窗口,默认为选中窗口。

返回值包含窗口上下装饰区域的高度。 如果 window 是内部窗口,其像素高度为所有子窗口所覆盖屏幕区域的像素高度。

Function: window-pixel-width &optional window

该函数以像素为单位返回窗口 window 的总宽度。 window 必须是有效窗口,默认为选中窗口。

返回值包含窗口左右装饰区域的宽度。 如果 window 是内部窗口,其像素宽度为所有子窗口所覆盖屏幕区域的像素宽度。

以下函数可用于判断指定窗口是否存在相邻窗口。

Function: window-full-height-p &optional window

如果窗口 window 在其框架内上下均无其他窗口,该函数返回非 nil 值。 更精确地说,这表示该窗口的总高度与其框架根窗口的总高度相等。 迷你缓冲区窗口不计入此判断。 如果 window 被省略或为 nil,则默认为选中窗口。

Function: window-full-width-p &optional window

如果窗口 window 在其框架内左右均无其他窗口,该函数返回非 nil 值, 即其总宽度与该框架根窗口的总宽度相等。 如果 window 被省略或为 nil,则默认为选中窗口。

窗口的主体高度(body height)是其文本主体的高度,不包含任何上下装饰区域(see Emacs 窗口的基本概念)。

Function: window-body-height &optional window pixelwise

该函数以行为单位返回窗口 window 主体的高度。 如果 window 被省略或为 nil,则默认为选中窗口;否则必须为活动窗口。

可选参数 pixelwise 用于指定高度单位。 如果为 nil,以字符为单位返回窗口主体高度,必要时向下取整。 这意味着如果文本区域底部某一行仅部分可见,该行不计入高度。 同时也意味着窗口主体高度永远不会超过 window-total-height 返回的总高度。

如果 pixelwiseremap 且默认 face 被重映射(see 文本视觉样式重映射),则使用重映射后的 face 确定字符高度。 其他非 nil 值则以像素为单位返回高度。

窗口的主体宽度(body width)是其主体与文本区域的宽度,不包含任何左右装饰区域(see Emacs 窗口的基本概念)。

注意,当一侧或两侧 fringe 被移除(宽度设为 0)时,显示引擎会在窗口两侧各保留一个字符单元格用于显示续行和截断标记, 这会使文本可用列数减少 2 列。(下文介绍的 window-max-chars-per-line 函数会考虑这一特性。)

Function: window-body-width &optional window pixelwise

该函数以列为单位返回窗口 window 主体的宽度。 如果 window 被省略或为 nil,则默认为选中窗口;否则必须为活动窗口。

可选参数 pixelwise 用于指定宽度单位。 如果为 nil,以字符为单位返回窗口主体宽度,必要时向下取整。 这意味着如果文本区域右侧某一列仅部分可见,该列不计入宽度。 同时也意味着窗口主体宽度永远不会超过 window-total-width 返回的总宽度。

如果 pixelwiseremap 且默认 face 被重映射(see 文本视觉样式重映射),则使用重映射后的 face 确定字符宽度。 其他非 nil 值则以像素为单位返回宽度。

Function: window-body-size &optional window horizontal pixelwise

该函数返回窗口 window 的主体高度或主体宽度。 如果 horizontal 被省略或为 nil,等价于调用 window-body-height; 否则等价于调用 window-body-width。 两种情况下,可选参数 pixelwise 都会传递给对应函数。

窗口的模式行、标签栏和标题栏的像素高度可通过以下函数获取。 它们的返回值通常是精确的,除非该窗口此前从未被显示过:此时返回值基于对窗口框架所用字体的估算。

Function: window-mode-line-height &optional window

该函数以像素为单位返回窗口 window 模式行的高度。 window 必须为活动窗口,默认为选中窗口。 如果窗口无模式行,返回值为 0。

Function: window-tab-line-height &optional window

该函数以像素为单位返回窗口 window 标签栏的高度。 window 必须为活动窗口,默认为选中窗口。 如果窗口无标签栏,返回值为 0。

Function: window-header-line-height &optional window

该函数以像素为单位返回窗口 window 标题栏的高度。 window 必须为活动窗口,默认为选中窗口。 如果窗口无标题栏,返回值为 0。

获取窗口分隔线(see 窗口分隔线)、fringe(see 侧边栏)、滚动条(see 滚动条) 和显示边距(see 在边距中显示)高度和/或宽度的函数将在对应章节介绍。

如果你的 Lisp 程序需要进行布局决策,以下函数会很有用:

Function: window-max-chars-per-line &optional window face

该函数返回在指定窗口 window(必须为活动窗口)中以指定 face face 显示时,每行可容纳的字符数。 如果 face 被重映射(see 文本视觉样式重映射),则返回重映射后 face 的对应信息。 如果被省略或为 nilface 默认为默认 face,window 默认为选中窗口。

window-body-width 不同,该函数依据 face 字体的实际尺寸计算,而非使用窗口框架的标准字符宽度单位(see 框架字体)。 如果窗口缺少一侧或两侧 fringe,它还会计入续行标记占用的空间。

改变窗口大小(see 调整窗口大小)或拆分窗口(see 拆分窗口)的命令会遵守变量 window-min-heightwindow-min-width,它们指定了窗口允许的最小高度和宽度。 这些命令同样遵守变量 window-size-fixed,使用该变量可以将窗口固定(fixed)尺寸(see 保留窗口尺寸)。

User Option: window-min-height

该选项以行为单位指定所有窗口允许的最小总高度。 其值必须至少容纳一行文本以及所有上下装饰区域。

User Option: window-min-width

该选项以列为单位指定所有窗口允许的最小总宽度。 其值必须至少容纳两列文本以及所有左右装饰区域。

以下函数会根据窗口各区域尺寸以及 window-min-heightwindow-min-widthwindow-size-fixed(see 保留窗口尺寸)的值,返回指定窗口可以缩小到的最小尺寸。

Function: window-min-size &optional window horizontal ignore pixelwise

该函数返回窗口 window 的最小尺寸。 window 必须为有效窗口,默认为选中窗口。 可选参数 horizontal 为非 nil 时返回窗口的最小列数;否则返回最小行数。

返回值可以保证:如果窗口实际设为该尺寸,其所有组成部分仍能完全可见。 当 horizontalnil 时,包含所有上下装饰区域; 非 nil 时包含所有左右装饰区域。

可选参数 ignore 为非 nil 时,表示忽略固定尺寸窗口、window-min-heightwindow-min-width 带来的限制。 如果 ignore 等于 safe,活动窗口最小可至 window-safe-min-height 行和 window-safe-min-width 列。 如果 ignore 是一个窗口,则仅忽略该窗口的限制。 其他非 nil 值表示忽略所有窗口的上述全部限制。

可选参数 pixelwise 为非 nil 时,以像素为单位返回窗口最小尺寸。