Иконки

Emacs иногда использует кнопки (для нажатия) или небольшие изображения (чтобы что-либо проиллюстрировать). Поскольку Emacs доступен на самых разных системах с различными возможностями, а у пользователей разные предпочтения, в Emacs предусмотрен удобный механизм для работы с этим, позволяющий настраивать иконки, обеспечивать корректное снижение качества отображения, доступность и поддержку тем: иконки.

Основной макрос здесь — define-icon, вот простой пример:

(define-icon outline-open button
  '((image "right.svg" "open.xpm" "open.pbm" :height line)
    (emoji "▶️")
    (symbol "▶" "➤")
    (text "open" :face icon-button))
  "Icon used for buttons for opening a section in outline buffers."
  :version "29.1"
  :help-echo "Open this section")

То, какой вариант будет отображён, зависит от значения пользовательского параметра icon-preference (см. Иконки в Руководстве GNU Emacs) и от результатов проверок во время выполнения, определяющих, что именно может отображать терминал текущего кадра.

Макрос в приведённом выше примере определяет outline-open как иконку и наследует свойства иконки с именем button (таким образом, она предназначена для использования в качестве нажимаемой кнопки, вставляемой в буфер). За ним следует список типов иконок с соответствующими изображениями. Кроме того, указываются строка документации и различные ключевые слова с дополнительной информацией и свойствами.

Чтобы создать экземпляр иконки, используйте icon-string. Эта функция учитывает текущие настройки тем в Customize, пользовательский параметр icon-preference и, наконец, то, что Emacs действительно может отобразить. Если icon-preference имеет значение (image emoji symbol text) (то есть разрешены все эти варианты иконок), в этом случае icon-string сначала проверит, может ли Emacs вообще отображать изображения, а затем — поддерживает ли он каждый из этих форматов изображений. Если это не удастся, Emacs проверит, может ли он отображать эмодзи (в текущем кадре). Если и это не удастся, он проверит, может ли отобразить нужный символ. Если и это не удастся, будет использован обычный текстовый вариант.

Например, если icon-preference не содержит image или emoji, эти элементы будут пропущены.

Код может уверенно вызывать icon-string при любых обстоятельствах и быть уверенным, что на экране появится что-нибудь читаемое — независимо от того, использует ли пользователь графический или текстовый терминал и с какими возможностями был собран Emacs.

Макрос: define-icon name parent specs doc &rest keywords

Определяет иконку name — символ с вариантами отображения, заданными в spec, который позднее можно создать с помощью icon-string. name — это имя результирующего ключевого слова.

Результирующая иконка наследует спецификации от parent, от родителей этого элемента и так далее; при этом приоритет имеет самый нижний элемент в иерархии.

specs — это список спецификаций иконки. Первый элемент каждой спецификации задаёт тип, остальные — объект, который можно использовать как иконку этого типа, после чего может следовать список ключевых слов. Доступны следующие типы иконок:

image

В этом случае в качестве вариантов могут быть перечислены несколько изображений. Emacs выберет первое, которое сможет показать в текущем экземпляре. Если изображение указано абсолютным именем файла, оно используется как есть; в противном случае оно ищется в списке image-load-path (см. Определение изображений).

emoji

Здесь следует указать эмодзи (возможно, цветной).

symbol

Здесь следует указать символ (монохромный).

text

Для иконок также следует предусмотреть текстовый вариант. Он может использоваться и для людей с нарушениями зрения: если icon-preference имеет значение только (text), все иконки будут заменены текстом.

После списка спецификаций иконки могут следовать различные ключевые слова. Например:

(symbol "▶" "➤" :face icon-button)

Неизвестные ключевые слова игнорируются. Допустимы следующие ключевые слова:

:face

Шрифт начертания, используемый для иконки.

:height

Допустимо только для иконок image; значением может быть число (задающее высоту в пикселях) или символ line, который задаёт высоту строки по умолчанию в текущем выбранном окне.

:width

Допустимо только для иконок image; значением может быть число (задающее ширину в пикселях) или символ font, который задаёт ширину в пикселях шрифта начертания по умолчанию для текущего буфера.

doc должна быть строкой документации.

keywords — это список пар «ключевое слово/значение». Допустимы следующие ключевые слова:

:version

Примерная версия Emacs, в которой впервые появилась эта кнопка. (Это ключевое слово обязательно.)

:group

Группа настройки, к которой относится эта иконка. Если она не указана, группа определяется автоматически.

:help-echo

Справочная строка, отображаемая при наведении указателя мыши на иконку.

Функция: icon-string icon

Эта функция возвращает строку, подходящую для отображения в текущем буфере вместо icon.

Функция: icon-elements icon

Эта функция позволяет получить «разобранное» представление icon. Она возвращает plist (см. Списки свойств), ключами которого являются string, face и image. (Последний ключ присутствует только в том случае, если иконка представлена изображением.) Это может быть полезно, если иконку не нужно напрямую вставлять в буфер, а перед этим требуется выполнить некоторую предварительную обработку.

Иконки можно настраивать с помощью M-x customize-icon. Темы могут задавать изменения иконок, например, так:

(custom-theme-set-icons
  'my-theme
  '(outline-open ((image :height 100)
                  (text " OPEN ")))
  '(outline-close ((image :height 100)
                   (text " CLOSE " :face warning))))