42.12.3 文本视觉样式属性函数

本节描述用于直接访问和 修改具名文本视觉样式属性的函数。

Function: face-attribute face attribute &optional frame inherit

此函数返回 frame 框架上 face 文本视觉样式 的 attribute 属性值。See 文本视觉样式属性,查看支持的属性。

frame 省略或为 nil,则表示当前选中框架 (see 输入焦点)。若 framet,此函数 返回新建框架的指定属性值,即 在应用文本视觉样式的 defface 定义(see 定义文本视觉样式) 或由 face-spec-set 设置的规范中的文本视觉样式规范之前的属性值。 attribute 的默认值通常为 unspecified, 除非你已通过 set-face-attribute 指定了其他值,详见下文。

inheritnil,仅考虑由 face 直接定义的属性,因此返回值可能为 unspecified 或相对值。若 inheritnil,则 faceattribute 定义 会与其 :inherit 属性指定的文本视觉样式合并; 但返回值仍可能为 unspecified 或相对值。若 inherit 为一个文本视觉样式或文本视觉样式列表, 结果会进一步与该(这些)文本视觉样式合并,直至变为确定且绝对的值。

若要确保返回值始终为确定且绝对,可将 inherit 设为 default;这会通过与 default 文本视觉样式 (始终完整定义)合并来解析所有未指定或相对值。

例如:

(face-attribute 'bold :weight)
     ⇒ bold
Function: face-attribute-relative-p attribute value

value 用作文本视觉样式属性 attribute 的值时为相对值, 此函数返回非 nil。相对值意味着它会修改 而非完全覆盖来自文本视觉样式列表中后续文本视觉样式 或从其他文本视觉样式继承的值。

unspecified 对所有属性均为相对值。对于 :height,浮点数与函数值同样为相对值。

例如:

(face-attribute-relative-p :height 2.0)
     ⇒ t
Function: face-all-attributes face &optional frame

此函数返回 face 文本视觉样式的属性关联列表。 结果元素为形如 (attr-name . attr-value) 的键值对。可选参数 frame 指定要返回 该框架上 face 文本视觉样式的定义; 若省略或为 nil,返回值描述新建框架 face 文本视觉样式的默认属性,即 在应用文本视觉样式的 defface 定义 或由 face-spec-set 设置的规范中的属性值。 这些属性默认值通常为 unspecified, 除非你已通过 set-face-attribute 指定了其他值,详见下文。

Function: merge-face-attribute attribute value1 value2

value1 为文本视觉样式属性 attribute 的相对值,则返回其与基础值 value2 合并后的结果; 否则,若 value1 为该属性的绝对值, 则直接返回 value1

通常 Emacs 会使用各文本视觉样式的样式规范 在每个框架上自动计算其属性(see 定义文本视觉样式)。 函数 set-face-attribute 可通过直接为文本视觉样式 在指定框架或所有框架分配属性来覆盖此计算。 该函数主要供内部使用。

Function: set-face-attribute face frame &rest arguments

此函数为 frame 框架上的 face 文本视觉样式 设置一个或多个属性。以此方式指定的属性 会覆盖属于 face 的文本视觉样式规范。 See 文本视觉样式属性,查看支持的属性。

额外参数 arguments 指定要设置的属性及其值。 它们应由交替出现的属性名(如 :family:underline) 与值组成。因此:

(set-face-attribute 'foo nil :weight 'bold :slant 'italic)

:weight 属性设为 bold, 将 :slant 属性设为 italic

framet,此函数设置新建框架的默认属性; 这会有效覆盖 defface 指定的属性值。 若 framenil, 此函数为所有现有框架及新建框架设置属性。

重置 属性值,即表示该文本视觉样式 本身不指定该属性的值,需为该属性使用特殊值 unspecified而非 nil!), 并在将 frame 设为 nil 调用的同时, 额外将 frame 设为 t 调用一次。 原因是新建框架时,新建框架的默认属性 会与 defface 中的文本视觉样式规范合并, 因此新建框架默认属性中的 unspecified 无法覆盖 defface;上述特殊调用方式 可确保 defface 被覆盖。

注意属性值对按指定顺序求值, :family:foundry 属性除外,它们会优先求值。 这意味着若某属性被多次指定,仅最后一次值生效。 同时在某些情况下,属性顺序不同会产生不同结果。 例如,若 :weight 置于 :font 之前, 字重值会应用于文本视觉样式的当前字体, 并可能舍入为该字体最接近的可用字重; 而若 :font 置于 :weight 之前, 字重值则应用于指定字体。

下列命令与函数主要用于兼容旧版 Emacs。 它们通过调用 set-face-attribute 工作。 其 frame 参数的 tnil(或省略) 处理方式与 set-face-attributeface-attribute 一致。 若交互调用,这些命令会通过迷你缓冲区读取参数。

Command: set-face-foreground face color &optional frame
Command: set-face-background face color &optional frame

分别将 face 文本视觉样式的 :foreground 属性(或 :background 属性) 设为 color

Command: set-face-stipple face pattern &optional frame

face 文本视觉样式的 :stipple 属性 设为 pattern

Command: set-face-font face font &optional frame

face 文本视觉样式的字体相关属性 改为 font(字符串或字体对象)对应的属性。 See face-font-attribute,查看 font 参数支持的格式。 此函数设置文本视觉样式的 :font 属性, 并间接设置由该字体定义的 :family:foundry:width:height:weight:slant 属性。 若 framenil,仅修改指定框架上的属性。

Function: set-face-bold face bold-p &optional frame

bold-pnil, 将 face 文本视觉样式的 :weight 属性设为 normal, 否则设为 bold

Function: set-face-italic face italic-p &optional frame

italic-pnil, 将 face 文本视觉样式的 :slant 属性设为 normal, 否则设为 italic

Command: set-face-underline face underline &optional frame

face 文本视觉样式的 :underline 属性 设为 underline

Command: set-face-inverse-video face inverse-video-p &optional frame

face 文本视觉样式的 :inverse-video 属性 设为 inverse-video-p

Command: invert-face face &optional frame

交换 face 文本视觉样式的前景色与背景色。

Command: set-face-extend face extend &optional frame

face 文本视觉样式的 :extend 属性 设为 extend

下列函数用于查询文本视觉样式的属性。 它们主要用于兼容旧版 Emacs。 若未指定 frame,则指向当前选中框架; t 指向新建框架的默认数据。 若文本视觉样式未定义该属性值,返回 unspecified。 若 inheritnil,仅返回由该文本视觉样式 直接定义的属性。若 inheritnil, 则同时考虑其 :inherit 属性指定的文本视觉样式; 若 inherit 为一个或多个文本视觉样式, 则一并纳入计算,直至找到确定的属性值。 若要确保返回值始终确定,可将 inherit 设为 default

Function: face-font face &optional frame character

此函数返回指定 face 文本视觉样式所使用的字体名称。

若指定可选参数 frame,则返回该框架上 face 文本视觉样式的字体名称; 若 framenil 或省略,默认为当前选中框架。 若 framet,函数返回用于新建框架的 face 文本视觉样式默认字体。

默认情况下,返回的字体用于显示 ASCII 字符; 但若 frame 不为 t 且提供了可选第三个参数 character, 函数返回 face 文本视觉样式用于该字符的字体名称。

Function: face-foreground face &optional frame inherit
Function: face-background face &optional frame inherit

这些函数以字符串形式返回 face 文本视觉样式的 前景色(或背景色)。若颜色未指定,返回 nil

Function: face-stipple face &optional frame inherit

此函数返回 face 文本视觉样式的背景点画图案名称, 若无则返回 nil

Function: face-bold-p face &optional frame inherit

face 文本视觉样式的 :weight 属性 比常规更粗(即 semi-boldboldextra-boldultra-bold 之一), 函数返回非 nil,否则返回 nil

Function: face-italic-p face &optional frame inherit

face 文本视觉样式的 :slant 属性 为 italicoblique, 函数返回非 nil,否则返回 nil

Function: face-underline-p face &optional frame inherit

face 文本视觉样式指定了非 nil:underline 属性,函数返回非 nil

Function: face-inverse-video-p face &optional frame inherit

face 文本视觉样式指定了非 nil:inverse-video 属性,函数返回非 nil

Function: face-extend-p face &optional frame inherit

face 文本视觉样式指定了非 nil:extend 属性,函数返回非 nil。 参数 inherit 会传递给 face-attribute