42.18 Значки

В 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))
  "Значок для кнопок, используемых для раскрытия раздела в буферах структуры."
  :version "29.1"
  :help-echo "Раскрыть этот раздел")

Какой из вариантов будет фактически отображён, зависит от значения пользовательской опции 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 выберет первое из них, которое текущий экземпляр 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))))