Custom Themes — Elisp

Пользовательские темы

Пользовательские темы — это наборы параметров, которые можно включать или отключать целиком. См. Пользовательские темы в Руководстве GNU Emacs. Каждая пользовательская тема определяется исходным файлом Emacs Lisp, который должен соответствовать соглашениям, описанным в этом разделе. (Вместо того чтобы создавать пользовательскую тему вручную, вы также можете создать её с помощью интерфейса, подобного Customize; см. Создание пользовательских тем в Руководстве GNU Emacs.)

Файл пользовательской темы должен называться foo-theme.el, где foo — имя темы. Первой формой Lisp в файле должен быть вызов deftheme, а последней формой — вызов provide-theme.

Макрос: deftheme theme &optional doc &rest properties

Этот макрос объявляет theme (символ) именем пользовательской темы. Необязательный аргумент doc должен быть строкой с описанием темы; это описание отображается, когда пользователь вызывает команду describe-theme или вводит ? в буфере ‘*Custom Themes*’. Остальные аргументы properties используются для передачи списка свойств с атрибутами темы.

Поддерживаются следующие атрибуты:

:family: Символ, обозначающий, к какому «семейству» относится тема. Семейство тем — это набор похожих тем, различающихся незначительными аспектами, например цветами лиц, предназначенными для светлого или тёмного фона окна.
:kind: Символ. Если тема включена и это свойство имеет значение color-scheme, команда theme-choose-variant будет искать другие доступные темы того же семейства, чтобы переключать темы. Другие значения в настоящее время не определены и не должны использоваться.
:background-mode: Символ: либо light, либо dark. Этот атрибут в настоящее время не используется, но его всё равно следует указывать.

Использование двух специальных имён тем запрещено (при их использовании возникает ошибка): user — фиктивная тема, в которой хранятся непосредственные пользовательские настройки, а changed — фиктивная тема, в которой хранятся изменения, внесённые вне системы Customize.

Макрос: provide-theme theme: Этот макрос объявляет, что тема с именем theme полностью определена.

Между deftheme и provide-theme располагаются формы Lisp, задающие параметры темы: обычно вызов custom-theme-set-variables и/или вызов custom-theme-set-faces.

Функция: custom-theme-set-variables theme &rest args

Эта функция задаёт параметры переменных пользовательской темы theme. theme должен быть символом. Каждый аргумент в args должен представлять собой список следующей формы:

(var expression [now [request [comment]]])

Элементы списка имеют то же значение, что и в custom-set-variables. См. Применение настроек.

Функция: custom-theme-set-faces theme &rest args

Эта функция задаёт параметры лиц пользовательской темы theme. theme должен быть символом. Каждый аргумент в args должен представлять собой список следующей формы:

(face spec [now [comment]])

Элементы списка имеют то же значение, что и в custom-set-faces. См. Применение настроек.

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

Следующие функции полезны для программного включения и отключения тем:

Функция: custom-theme-p theme: Эта функция возвращает значение, отличное от nil, если theme (символ) является именем пользовательской темы (то есть пользовательской темы, загруженной в Emacs, независимо от того, включена она или нет). В противном случае она возвращает nil.

Переменная: custom-known-themes: Значение этой переменной — список тем, загруженных в Emacs. Каждая тема представлена символом Lisp (именем темы). Значение этой переменной по умолчанию — список из двух фиктивных тем: (user changed). Тема changed хранит параметры, заданные до применения каких-либо пользовательских тем (например, переменные, заданные вне Customize). Тема user хранит параметры, настроенные и сохранённые пользователем. Все дополнительные темы, объявленные с помощью макроса deftheme, добавляются в начало этого списка.

Команда: load-theme theme &optional no-confirm no-enable: Эта функция загружает пользовательскую тему с именем theme из исходного файла, выполняя поиск этого файла в каталогах, заданных переменной custom-theme-load-path. См. Пользовательские темы в Руководстве GNU Emacs. Она также включает тему (если необязательный аргумент no-enable не равен nil), в результате чего вступают в силу заданные ею параметры переменных и лиц. Перед загрузкой темы функция запрашивает подтверждение пользователя, если необязательный аргумент no-confirm не равен nil.

Функция: require-theme feature &optional noerror

Эта функция выполняет поиск в custom-theme-load-path файла, предоставляющего feature, а затем загружает его. Она действует подобно функции require (см. Возможности), за исключением того, что выполняет поиск в custom-theme-load-path, а не в load-path (см. Поиск библиотек). Это может быть полезно для пользовательских тем, которым нужно загружать вспомогательные файлы Lisp, когда require для этого не подходит.

Если feature (который должен быть символом) ещё не присутствует в текущем сеансе Emacs согласно featurep, то require-theme ищет в каталогах, заданных custom-theme-load-path, файл с именем feature и суффиксом ‘.elc’ или ‘.el’, в указанном порядке.

Если файл, предоставляющий feature, успешно найден и загружен, require-theme возвращает feature. Необязательный аргумент noerror определяет, что произойдёт при неудачном поиске или загрузке. Если он равен nil, функция сигнализирует об ошибке; в противном случае она возвращает nil. Если файл успешно загружен, но не предоставляет feature, require-theme сигнализирует об ошибке; подавить её нельзя.

Команда: enable-theme theme: Эта функция включает пользовательскую тему с именем theme. Если такая тема не была загружена, функция сигнализирует об ошибке.

Команда: disable-theme theme: Эта функция отключает пользовательскую тему с именем theme. Тема остаётся загруженной, поэтому последующий вызов enable-theme снова включит её.