29.24 坐标与窗口

本节描述用于返回窗口位置以及窗口内部位置的函数。 其中大部分函数返回相对于窗口框架(frame)原生位置的坐标(see 框架几何属性)。 部分函数返回相对于该窗口框架显示区域原点的坐标。 无论哪种情况,坐标原点均为 (0, 0),X 坐标向右递增,Y 坐标向下递增。

对于下面这些函数,X 和 Y 坐标以整数字符单位返回,即分别对应行数和列数。 在图形化显示器上,每一个 “行(line)” 和 “列(column)” 对应框架默认字体所指定的默认字符高度和宽度(see 框架字体)。

Function: window-edges &optional window body absolute pixelwise

该函数返回 window 的边缘坐标列表。 若 window 被省略或为 nil,则默认为当前选中窗口。

返回值格式为 (left top right bottom)。 列表元素依次为:窗口占据的最左列 X 坐标、最顶行 Y 坐标、最右列右侧一列的 X 坐标、最底行下方一行的 Y 坐标。

注意,这些是窗口的实际外边缘,包含其所有装饰。 在文本终端上,如果窗口右侧有相邻窗口,其右边缘包含窗口与相邻窗口之间的分隔线。

若可选参数 bodynil,表示返回 window 总尺寸对应的边缘。 bodynil 表示返回窗口主体(body)的边缘。 若 bodynil,则 window 必须指定一个活动窗口。

若可选参数 absolutenil,表示返回相对于 window 所属框架原生位置的边缘坐标。 absolutenil 表示返回相对于窗口显示区域原点 (0, 0) 的坐标。 在非图形化系统上,该参数无效。

若可选参数 pixelwisenil,表示以窗口框架的默认字符宽度和高度为单位返回坐标(see 框架字体),必要时会取整。 pixelwisenil 表示以 像素(pixels) 为单位返回坐标。 注意,由 rightbottom 指定的像素点紧邻这些边缘外侧。 若 absolutenil,则 pixelwise 也隐式为非 nil

Function: window-body-edges &optional window

该函数返回 window 主体部分的边缘(see 窗口尺寸)。 调用 (window-body-edges window) 等价于调用 (window-edges window t),见上文。

下面这些函数可用于将一组框架相对坐标关联到某个窗口:

Function: window-at x y &optional frame

该函数返回位于坐标 xy 处的活动窗口,坐标单位为默认字符尺寸(see 框架字体),相对于 frame 的原生位置(see 框架几何属性)。

若该位置无窗口,则返回 nil。 若 frame 被省略或为 nil,则默认为当前选中框架。

Function: coordinates-in-window-p coordinates window

该函数检查窗口 window 是否占据框架相对坐标 coordinates 所在位置,若是则返回位于窗口的哪个部分。 window 必须是活动窗口。

coordinates 应为格式为 (x . y) 的 cons 单元, 其中 xy 以默认字符尺寸为单位(see 框架字体),相对于 window 所属框架的原生位置(see 框架几何属性)。

若指定位置无窗口,返回值为 nil。 否则返回下列值之一:

(relx . rely)

坐标位于 window 内部。 relxrely 是该位置对应的窗口相对坐标,从窗口左上角 (0, 0) 开始计数。

mode-line

坐标位于 window 的模式行。

header-line

坐标位于 window 的标题行。

tab-line

坐标位于 window 的标签行。

right-divider

坐标位于窗口与其右侧窗口之间的分隔条。

bottom-divider

坐标位于窗口与其下方窗口之间的分隔条。

vertical-line

坐标位于窗口与其右侧相邻窗口之间的竖直线。 该值仅在窗口无滚动条时出现;滚动条位置在此类判断中视为窗口外部。

left-fringe
right-fringe

坐标位于窗口的左侧或右侧边衬区。

left-margin
right-margin

坐标位于窗口的左侧或右侧边距。

nil

坐标不在 window 的任何区域。

函数 coordinates-in-window-p 不需要框架作为参数,因为它始终使用 window 所在的框架。

下面这些函数以 像素(pixels) 而非字符单位返回窗口位置。 虽然主要用于图形化显示器,但也可在文本终端上调用,此时每个文本字符的屏幕区域视为 1 像素。

Function: window-pixel-edges &optional window

该函数返回 window 边缘的像素坐标列表。 调用 (window-pixel-edges window) 等价于调用 (window-edges window nil nil t),见上文。

Function: window-body-pixel-edges &optional window

该函数返回 window 主体部分的像素边缘坐标。 调用 (window-body-pixel-edges window) 等价于调用 (window-edges window t nil t),见上文。

下面这些函数以像素为单位返回窗口位置,坐标相对于**整个显示屏**原点,而非框架原点:

Function: window-absolute-pixel-edges &optional window

该函数返回 window 相对于其框架显示区域原点 (0, 0) 的像素坐标。 调用 (window-absolute-pixel-edges) 等价于调用 (window-edges window nil t t),见上文。

Function: window-absolute-body-pixel-edges &optional window

该函数返回 window 主体部分相对于其框架显示区域原点 (0, 0) 的像素坐标。 调用 (window-absolute-body-pixel-edges window) 等价于调用 (window-edges window t t t),见上文。

结合 set-mouse-absolute-pixel-position,该函数可用于将鼠标指针移动到某个窗口中可见的任意缓冲区位置:

(let ((edges (window-absolute-body-pixel-edges))
      (position (pos-visible-in-window-p nil nil t)))
  (set-mouse-absolute-pixel-position
   (+ (nth 0 edges) (nth 0 position))
   (+ (nth 1 edges) (nth 1 position))))

在图形化终端上,这段代码会将鼠标光标“瞬移”到选中窗口中点所在字形的左上角。 以此方式计算出的位置也可用于在该处显示提示框窗口。

下面的函数返回窗口中可见的某个缓冲区位置的屏幕坐标:

Function: window-absolute-pixel-position &optional position window

若缓冲区位置 position 在窗口 window 中可见, 该函数返回 position 处字形左上角的显示坐标。 返回值为该角点的 X、Y 坐标组成的 cons 单元,相对于 window 显示区域的原点 (0, 0)。 若 positionwindow 中不可见,则返回 nil

window 必须是活动窗口,默认为选中窗口。 position 默认为 windowwindow-point 值。

这意味着,若要将鼠标指针移动到选中窗口中点的位置,只需编写:

(let ((position (window-absolute-pixel-position)))
  (set-mouse-absolute-pixel-position
   (car position) (cdr position)))

下面的函数返回可内接于窗口、且不覆盖窗口内显示文本的最大矩形:

Function: window-largest-empty-rectangle &optional window count min-width min-height positions left

该函数计算可内接于指定 window 文本区域的最大空白矩形的尺寸。 window 必须是活动窗口,默认为选中窗口。

返回值为一个三元组,包含可内接于窗口文本区域空白空间(不显示任何文本的区域)的最大矩形的宽度、起始 Y 坐标和结束 Y 坐标。 该函数不返回 X 坐标——所有此类矩形均默认终止于 window 文本区域的右边缘。 若无法找到空白区域,则返回 nil

可选参数 countnil 时,指定最多返回的矩形数量。 此时返回值为一个由多个三元组组成的列表,按矩形从大到小排序。 count 也可以是一个 cons 单元,其 car 指定返回矩形数量,cdr 非 nil 时表示所有返回矩形必须互不相交。

可选参数 min-widthmin-heightnil 时,指定返回矩形的最小宽度和高度。

可选参数 positionsnil 时,应为一个 cons 单元, 其 car 指定所有返回矩形必须覆盖的最顶部像素位置,cdr 指定必须覆盖的最底部像素位置。 这些位置从 window 文本区域起始处开始计算。

可选参数 leftnil 时,表示返回适用于显示从右到左文本缓冲区的值。 此时,所有返回矩形均默认起始于 window 文本区域的左边缘。

注意,该函数必须通过 window-lines-pixel-dimensions 获取窗口字形矩阵每一行的尺寸(see 显示文本尺寸)。 因此,当窗口当前字形矩阵不是最新状态时,该函数也可能返回 nil