Функции атрибутов лиц

В этом разделе описаны функции для непосредственного доступа к атрибутам именованного лица и их изменения.

Функция: face-attribute face attribute &optional frame inherit

Эта функция возвращает значение атрибута attribute для лица face в кадре frame. Сведения о поддерживаемых атрибутах см. в разделе Атрибуты лиц.

Если аргумент frame опущен или равен nil, это означает выбранный кадр (см. раздел Фокус ввода). Если frame равен t, эта функция возвращает значение указанного атрибута для вновь созданных кадров, то есть значение атрибута до применения спецификации лица из определения defface этого лица (см. раздел Определение лиц) или спецификации, заданной с помощью face-spec-set. Обычно значение по умолчанию для attribute равно unspecified, если только вы не указали другое значение с помощью set-face-attribute; см. ниже.

Если inherit равен nil, учитываются только атрибуты, непосредственно определённые для face, поэтому возвращаемое значение может быть unspecified или относительным. Если inherit не равен nil, определение attribute для face объединяется с лицами, указанными в его атрибуте :inherit; однако возвращаемое значение всё ещё может быть unspecified или относительным. Если inherit — это лицо или список лиц, результат дополнительно объединяется с этим лицом (или этими лицами), пока значение не станет заданным и абсолютным.

Чтобы гарантировать, что возвращаемое значение всегда задано и является абсолютным, укажите для inherit значение default; это разрешит все незаданные или относительные значения путём объединения с лицом default, для которого всегда заданы все значения.

Например:

(face-attribute 'bold :weight)
     ⇒ bold

Функция: face-attribute-relative-p attribute value

Эта функция возвращает значение, отличное от nil, если value, используемое в качестве значения атрибута лица attribute, является относительным. Это означает, что оно изменит, а не полностью переопределит любое значение, полученное от следующего лица в списке лиц или унаследованное от другого лица.

unspecified является относительным значением для всех атрибутов. Для :height относительными также являются значения с плавающей точкой и функции.

Например:

(face-attribute-relative-p :height 2.0)
     ⇒ t

Функция: face-all-attributes face &optional frame inherit

Эта функция возвращает список ассоциаций атрибутов лица face. Элементы результата — пары «имя—значение» вида (attr-name . attr-value). Необязательный аргумент frame задаёт кадр, определение face для которого нужно вернуть; если он опущен или равен nil, возвращаемое значение описывает атрибуты face по умолчанию для вновь созданных кадров, то есть значения этих атрибутов до применения спецификации лица из определения defface этого лица или спецификации, заданной с помощью face-spec-set. Обычно значения атрибутов по умолчанию равны unspecified, если только вы не указали другие значения с помощью set-face-attribute; см. ниже. Необязательный аргумент inherit имеет то же значение, что и одноимённый аргумент функции face-attribute; см. её описание. Это полезно, когда нужно, чтобы атрибуты лица были абсолютными, а не unspecified.

Функция: merge-face-attribute attribute value1 value2

Если value1 является относительным значением атрибута лица attribute, функция возвращает его, объединённое с базовым значением value2; в противном случае, если value1 является абсолютным значением атрибута лица attribute, функция возвращает value1 без изменений.

Обычно Emacs использует спецификации лиц каждого лица для автоматического вычисления его атрибутов в каждом кадре (см. раздел Определение лиц). Функция set-face-attribute может переопределить это вычисление, напрямую назначая атрибуты лицу — как для определённого кадра, так и для всех кадров. Эта функция предназначена главным образом для внутреннего использования.

Функция: set-face-attribute face frame &rest arguments

Эта функция задаёт один или несколько атрибутов лица face для кадра frame. Указанные таким образом атрибуты переопределяют спецификации лица, относящиеся к face. Сведения о поддерживаемых атрибутах см. в разделе Атрибуты лиц.

Дополнительные аргументы arguments задают атрибуты и их значения. Они должны состоять из чередующихся имён атрибутов (например, :family или :underline) и значений. Таким образом,

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

задаёт атрибут :weight равным bold, а атрибут :slant — равным italic.

Если frame равен t, эта функция задаёт атрибуты по умолчанию для вновь созданных кадров; фактически они переопределяют значения атрибутов, указанные с помощью defface. Если frame равен nil, эта функция задаёт атрибуты для всех существующих, а также вновь создаваемых кадров.

Чтобы сбросить значение атрибута, то есть указать, что само лицо не задаёт значение этого атрибута, используйте для атрибута специальное значение unspecified (не nil!) и задайте аргументу frame значение t в дополнение к вызову, в котором frame равен nil. Это необходимо потому, что атрибуты по умолчанию для вновь созданных кадров объединяются со спецификацией лица в defface при создании нового кадра, поэтому значение unspecified среди атрибутов по умолчанию для новых кадров не сможет переопределить defface; специальный вызов этой функции, описанный выше, обеспечит переопределение defface.

Обратите внимание, что пары «атрибут—значение» вычисляются в указанном порядке, за исключением атрибутов :family и :foundry, которые вычисляются первыми. Это означает, что если атрибут указан несколько раз, будет использовано только последнее значение. Кроме того, в некоторых случаях изменение порядка атрибутов приводит к разным результатам. Например, если :weight указан перед :font, значение толщины начертания применяется к текущему шрифту лица и может быть округлено до ближайшей доступной толщины начертания этого шрифта; если же :font указан перед :weight, значение толщины начертания применяется к заданному шрифту.

Следующие команды и функции предназначены главным образом для совместимости со старыми версиями Emacs. Они работают, вызывая set-face-attribute. Значения t и nil (или отсутствие аргумента) для аргумента frame обрабатываются так же, как set-face-attribute и face-attribute. При интерактивном вызове команды считывают аргументы с помощью минибуфера.

Команда: set-face-foreground face color &optional frame

Команда: set-face-background face color &optional frame

Эти команды задают для лица face атрибут :foreground (или, соответственно, атрибут :background), устанавливая его в значение color.

Команда: set-face-stipple face pattern &optional frame

Эта команда задаёт для лица face атрибут :stipple, устанавливая его в значение pattern.

Команда: set-face-font face font &optional frame

Изменяет атрибуты лица face, связанные со шрифтом, устанавливая их в значения атрибутов шрифта font (строки или объекта шрифта). О поддерживаемых форматах аргумента font см. в разделе Атрибут face-font-attribute. Эта функция задаёт атрибут лица :font, а также косвенно атрибуты :family, :foundry, :width, :height, :weight и :slant, определяемые шрифтом. Если frame не равен nil, изменяются только атрибуты указанного кадра.

Функция: set-face-bold face bold-p &optional frame

Эта функция задаёт для лица face атрибут :weight, устанавливая его в значение normal, если bold-p равно nil, и в значение bold в противном случае.

Функция: set-face-italic face italic-p &optional frame

Эта функция задаёт для лица face атрибут :slant, устанавливая его в значение normal, если italic-p равно nil, и в значение italic в противном случае.

Команда: set-face-underline face underline &optional frame

Эта команда задаёт для лица face атрибут :underline, устанавливая его в значение underline.

Команда: set-face-inverse-video face inverse-video-p &optional frame

Эта команда задаёт для лица face атрибут :inverse-video, устанавливая его в значение inverse-video-p.

Команда: invert-face face &optional frame

Эта команда меняет местами цвета переднего и заднего плана лица face.

Команда: set-face-extend face extend &optional frame

Эта команда задаёт для лица face атрибут :extend, устанавливая его в значение extend.

Следующие функции проверяют атрибуты лица. Они предназначены главным образом для совместимости со старыми версиями Emacs. Если аргумент frame не указан, они относятся к выбранному кадру; t обозначает данные по умолчанию для новых кадров. Если лицо не задаёт значение атрибута, функции возвращают unspecified. Если inherit равен nil, возвращается только атрибут, непосредственно заданный лицом. Если inherit не равен nil, также учитываются все лица, указанные в атрибуте :inherit; если же inherit — это лицо или список лиц, учитываются и они, пока не будет найден заданный атрибут. Чтобы гарантировать, что возвращаемое значение всегда задано, укажите для inherit значение default.

Функция: face-font face &optional frame character

Эта функция возвращает имя шрифта, используемого указанным лицом face.

Если указан необязательный аргумент frame, функция возвращает имя шрифта лица face для этого кадра; если frame равен nil или опущен, используется выбранный кадр. Если frame равен t, функция возвращает значения шрифтов по умолчанию для face, которые будут использоваться в новых кадрах.

По умолчанию возвращаемый шрифт предназначен для отображения символов ASCII, но если frame не равен t и задан необязательный третий аргумент character, функция возвращает имя шрифта, используемого лицом face для этого символа.

Функция: face-foreground face &optional frame inherit

Функция: face-background face &optional frame inherit

Эти функции возвращают цвет переднего плана (или, соответственно, цвет заднего плана) лица face в виде строки. Если цвет не задан, они возвращают nil.

Функция: face-stipple face &optional frame inherit

Эта функция возвращает имя фонового узора лица face или nil, если он не задан.

Функция: face-bold-p face &optional frame inherit

Эта функция возвращает значение, отличное от nil, если атрибут :weight лица face соответствует начертанию жирнее обычного (то есть одному из значений semi-bold, bold, extra-bold или ultra-bold). В противном случае она возвращает nil.

Функция: face-italic-p face &optional frame inherit

Эта функция возвращает значение, отличное от nil, если атрибут :slant лица face равен italic или oblique, и nil в противном случае.

Функция: face-underline-p face &optional frame inherit

Эта функция возвращает значение, отличное от nil, если для лица face задан атрибут :underline, отличный от nil.

Функция: face-inverse-video-p face &optional frame inherit

Эта функция возвращает значение, отличное от nil, если для лица face задан атрибут :inverse-video, отличный от nil.

Функция: face-extend-p face &optional frame inherit

Эта функция возвращает значение, отличное от nil, если для лица face задан атрибут :extend, отличный от nil. Аргумент inherit передаётся функции face-attribute.