Overlay Properties — Elisp

Свойства оверлеев

Свойства оверлеев похожи на свойства текста в том, что свойства, изменяющие отображение символа, могут задаваться обоими способами. Но в большинстве отношений они различаются. Для сравнения см. Свойства текста.

Свойства текста считаются частью текста; оверлеи и их свойства, напротив, специально считаются не частью текста. Поэтому при копировании текста между различными буферами и строками свойства текста сохраняются, а оверлеи сохранять не пытаются. Изменение свойств текста в буфере помечает буфер как изменённый, а перемещение оверлея или изменение его свойств — нет. В отличие от изменений свойств текста, изменения свойств оверлея не записываются в список отмены буфера.

Поскольку для одного и того же символа значение свойства могут задавать несколько оверлеев, Emacs позволяет указать приоритет каждого оверлея. Значение приоритета используется для определения того, какой из перекрывающихся оверлеев «победит».

Эти функции считывают и задают свойства оверлея:

Функция: overlay-get overlay prop: Эта функция возвращает значение свойства prop, записанное в overlay, если оно есть. Если в overlay не записано значение этого свойства, но имеется свойство category, являющееся символом, используется свойство prop этого символа. В противном случае возвращается значение nil.

Функция: overlay-put overlay prop value: Эта функция задаёт для свойства prop, записанного в overlay, значение value. Она возвращает value.

Функция: overlay-properties overlay: Эта функция возвращает копию списка свойств overlay.

См. также функцию get-char-property, которая проверяет как свойства оверлея, так и свойства текста для заданного символа. См. Просмотр свойств текста.

Многие свойства оверлеев имеют особое значение; ниже приведена таблица таких свойств:

priority

Значение этого свойства определяет приоритет оверлея. Чтобы задать значение приоритета, используйте либо nil (или ноль), либо положительное целое число, либо пару из двух значений. Любое другое значение приводит к неопределённому поведению.

Приоритет имеет значение, когда два или более оверлеев покрывают один и тот же символ и задают для одного свойства разные значения: значение оверлея с более высоким значением priority переопределяет другое. (Для свойства face значение оверлея с более высоким приоритетом не полностью переопределяет другое значение; вместо этого отдельные атрибуты его лица переопределяют соответствующие атрибуты лица свойства face с более низким приоритетом.) Если у двух оверлеев одинаковое значение приоритета и один «вложен» в другой (то есть охватывает меньше позиций буфера или строки), преимущество имеет внутренний оверлей. Если ни один оверлей не вложен в другой, не следует предполагать, какой из них будет иметь преимущество.

Если программа на Lisp помещает на текст оверлеи с заданными приоритетами, на котором могут быть оверлеи без приоритетов, это может привести к нежелательным результатам, поскольку любой оверлей с положительным значением приоритета переопределит все оверлеи без приоритета. Поскольку большинство функций Emacs, использующих оверлеи, не задают для них приоритеты, целочисленные приоритеты следует использовать с осторожностью. Вместо целочисленных приоритетов, которые могут переопределять другие оверлеи, можно использовать значения приоритета вида (primary . secondary), где значение primary используется, как описано выше, а secondary — как резервное значение, когда с помощью primary и правил вложенности не удаётся определить порядок оверлеев. В частности, значение приоритета (nil . n), где n — положительное целое число, позволяет при необходимости упорядочивать оверлеи по приоритету, не переопределяя полностью другие оверлеи.

В настоящее время все оверлеи имеют приоритет над свойствами текста.

Чтобы расположить оверлеи в порядке приоритета, используйте аргумент sorted функции overlays-at. См. Поиск оверлеев.

window

Если свойство window не равно nil, оверлей применяется только в этом окне.

category

Если у оверлея есть свойство category, его называют категорией оверлея. Это свойство должно быть символом. Свойства символа используются как значения по умолчанию для свойств оверлея.

face

Это свойство управляет внешним видом текста (см. Лица). Значение свойства может быть одним из следующих:

Имя лица (символ или строка).
Анонимное лицо: список свойств вида (keyword value …), где каждое keyword — имя атрибута лица, а value — значение этого атрибута.
Список лиц. Каждый элемент списка должен быть либо именем лица, либо анонимным лицом. Так задаётся лицо, объединяющее атрибуты всех перечисленных лиц. Лица, стоящие в списке раньше, имеют более высокий приоритет.
Пара вида (foreground-color . color-name) или (background-color . color-name). Она задаёт цвет переднего плана или фона, аналогично (:foreground color-name) или (:background color-name). Эта форма поддерживается только для обратной совместимости, и её следует избегать.

mouse-face

Это свойство используется вместо face, когда указатель мыши находится в пределах оверлея. Однако Emacs игнорирует все атрибуты лица из этого свойства, изменяющие размер текста (например, :height, :weight и :slant); эти атрибуты всегда совпадают с атрибутами невыделенного текста.

display

Это свойство включает различные функции, изменяющие способ отображения текста. Например, оно может сделать текст выше или ниже, поднять или опустить его, сделать шире или уже либо заменить изображением. См. Свойство display. Обратите внимание: если свойство display является замещающим (см. Спецификации отображения, заменяющие текст), свойство invisible того же оверлея игнорируется.

help-echo

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

field

Соседние символы с одинаковым свойством field образуют поле. Некоторые функции перемещения, в том числе forward-word и beginning-of-line, останавливаются на границе поля. См. Определение и использование полей.

modification-hooks

Значение этого свойства — список функций, вызываемых при изменении любого символа внутри оверлея или при вставке текста строго внутри оверлея.

Функции-перехватчики вызываются как до, так и после каждого изменения. Если функции сохраняют полученную информацию и сопоставляют данные между вызовами, они могут точно определить, какое изменение было внесено в текст буфера.

При вызове перед изменением каждая функция получает четыре аргумента: оверлей, nil, а также начало и конец диапазона текста, который будет изменён.

При вызове после изменения каждая функция получает пять аргументов: оверлей, t, начало и конец только что изменённого диапазона текста и длину предшествовавшего изменению текста, заменённого этим диапазоном. (При вставке длина исходного текста равна нулю; при удалении эта длина равна числу удалённых символов, а начало и конец после изменения совпадают.)

При вызове этих функций inhibit-modification-hooks привязывается к значению, отличному от nil. Если функции изменяют буфер, возможно, вам понадобится привязать inhibit-modification-hooks к nil, чтобы перехватчики изменений запускались и для этих изменений. Однако это может привести к рекурсивному вызову собственного перехватчика изменений, поэтому предусмотрите обработку такой ситуации. См. Перехватчики изменений.

Свойства текста также поддерживают свойство modification-hooks, но подробности несколько отличаются (см. Свойства с особыми значениями).

insert-in-front-hooks

Значение этого свойства — список функций, вызываемых до и после вставки текста непосредственно в начало оверлея. Соглашения о вызове те же, что и для функций modification-hooks.

insert-behind-hooks

Значение этого свойства — список функций, вызываемых до и после вставки текста непосредственно в конец оверлея. Соглашения о вызове те же, что и для функций modification-hooks.

invisible

Свойство invisible может сделать текст в оверлее невидимым, то есть он не будет отображаться на экране. Однако, если текст, покрытый оверлеем, имеет замещающее свойство display, свойство invisible будет игнорироваться, поскольку замещающее свойство display пропускает текст, не проверяя его свойства. Подробности см. в разделе Невидимый текст.

intangible

Свойство intangible оверлея работает так же, как свойство текста intangible. Оно устарело. Подробности см. в разделе Свойства с особыми значениями.

isearch-open-invisible

Это свойство сообщает инкрементальному поиску (см. Инкрементальный поиск в Руководстве GNU Emacs), как навсегда сделать невидимый оверлей видимым, если окончательное совпадение перекрывает его. См. Невидимый текст.

isearch-open-invisible-temporary

Это свойство сообщает инкрементальному поиску, как временно сделать невидимый оверлей видимым во время поиска. См. Невидимый текст.

before-string

Значение этого свойства — строка, добавляемая к отображению в начале оверлея. Эта строка никак не присутствует в буфере — она отображается только на экране. Обратите внимание: если текст в начале оверлея сделан невидимым, строка отображаться не будет.

after-string

Значение этого свойства — строка, добавляемая к отображению в конце оверлея. Эта строка никак не присутствует в буфере — она отображается только на экране. Обратите внимание: если текст в конце оверлея сделан невидимым, строка отображаться не будет.

line-prefix

Это свойство задаёт спецификацию отображения, добавляемую в начале каждой строки без продолжения во время отображения. См. Усечение.

wrap-prefix

Это свойство задаёт спецификацию отображения, добавляемую в начале каждой строки продолжения во время отображения. См. Усечение.

evaporate

Если это свойство не равно nil, оверлей автоматически удаляется, если становится пустым (то есть его длина становится равной нулю). Если задать пустому оверлею (см. пустые оверлеи) свойство evaporate со значением, отличным от nil, он будет немедленно удалён. Обратите внимание: если у оверлея нет этого свойства, он не удаляется при удалении из буфера текста между его начальной и конечной позициями.

display-line-numbers-disable

Это свойство предотвращает отображение номеров строк (см. display-line-numbers в Руководстве GNU Emacs) для текста, находящегося внутри оверлея с этим свойством. Например, полезно использовать оверлей с этим свойством в конце буфера, поскольку иначе невозможно предотвратить отображение там номера строки.

keymap

Если это свойство не равно nil, оно задаёт карту клавиш для части текста. Эта карта клавиш имеет приоритет над большинством других карт клавиш (см. Активные карты клавиш) и используется, когда точка находится внутри оверлея; свойства продвижения переднего и заднего края определяют, считаются ли границы внутренней частью оверлея.

local-map

Свойство local-map похоже на keymap, но заменяет локальную карту буфера, а не дополняет существующие карты клавиш. Это также означает, что оно имеет более низкий приоритет, чем карты клавиш второстепенных режимов.

Свойства keymap и local-map не влияют на строку, отображаемую свойствами before-string, after-string или display. Это важно только для щелчков мышью и других событий мыши, приходящихся на строку, поскольку точка никогда не находится в строке. Чтобы привязать специальные события мыши к строке, назначьте ей текстовое свойство keymap или local-map. См. Свойства с особыми значениями.