42.9.1 Управление наложениями

В этом разделе описаны функции для создания, удаления и перемещения наложений, а также для просмотра их содержимого. Изменения наложений не записываются в список отмены (undo list) буфера, поскольку наложения не считаются частью содержимого буфера.

Функция: overlayp object ¶

Эта функция возвращает t, если object является наложением.

Функция: make-overlay start end &optional buffer front-advance rear-advance ¶

Эта функция создает и возвращает наложение, принадлежащее buffer и охватывающее диапазон от start до end. Оба start и end должны указывать позиции в буфере; они могут быть целыми числами или маркерами. Если buffer опущен, наложение создается в текущем буфере.

Наложение, чьи start и end указывают на одну и ту же позицию в буфере, называется пустым. Непустое наложение может стать пустым, если удаляется текст между его start и end. Когда это происходит, наложение по умолчанию не удаляется, но вы можете заставить его удалиться, присвоив ему свойство ‘evaporate’ (см. свойство evaporate).

Аргументы front-advance и rear-advance определяют, что происходит при вставке текста в начале (т.е. перед start) и в конце. Если оба они равны nil, то используется значение по умолчанию, и наложение расширяется, чтобы включить любой вставленный текст в начале, но не текст, вставленный в конце. Если front-advance не равно nil, текст, вставленный в начало наложения, исключается из наложения. Если rear-advance не равно nil, текст, вставленный в конец наложения, включается в наложение.

Функция: overlay-start overlay ¶

Эта функция возвращает позицию, с которой начинается overlay, в виде целого числа.

Функция: overlay-end overlay ¶

Эта функция возвращает позицию, где заканчивается overlay, в виде целого числа.

Функция: overlay-buffer overlay ¶

Эта функция возвращает буфер, к которому принадлежит overlay. Она возвращает nil, если overlay был удален.

Функция: delete-overlay overlay ¶

Эта функция удаляет указанное overlay. Наложение продолжает существовать как объект Lisp, и его список свойств не изменяется, но оно перестает быть привязанным к буферу, к которому принадлежало, и перестает оказывать какое-либо влияние на отображение.

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

Функция: move-overlay overlay start end &optional buffer ¶

Эта функция перемещает overlay в buffer и устанавливает его границы на start и end в этом буфере. Оба аргумента start и end должны указывать позиции в буфере; они могут быть целыми числами или маркерами.

Если buffer опущен, overlay остается в том же буфере, к которому он уже был привязан; если overlay был ранее удален (и, следовательно, не связан ни с каким буфером), он помещается в текущий буфер.

Возвращаемое значение — это overlay.

Это единственный допустимый способ изменить конечные точки наложения.

Функция: remove-overlays &optional start end name value ¶

Эта функция очищает текст в области между start и end для любых наложений, свойство которых с именем name имеет указанное value, таким образом, ни одно из таких наложений не повлияет на текст в этой области. Для этого функция может удалить наложения в области, изменить их конечные точки, разделить их или выполнить какое-либо сочетание этих действий. В частности:

• Наложения, начинающиеся в start или после него и заканчивающиеся до end, будут полностью удалены.
• Наложения, начинающиеся до start и заканчивающиеся после start, но до end, будут изменены так, что они закончатся в start.
• Наложения, начинающиеся в start или после него и заканчивающиеся после end, будут изменены так, что они начнутся в end.
• Наложения, начинающиеся до start и заканчивающиеся после end, будут разделены на два наложения: одно, которое заканчивается в start, и другое, которое начинается в end.

Если name опущен или равен nil, это означает удаление/изменение всех наложений, влияющих на текст в указанной области. Если start и/или end опущены или равны nil, по умолчанию используются начало и конец буфера, соответственно. Следовательно, (remove-overlays) удаляет все наложения в текущем буфере.

Значения именованного свойства наложения сравниваются с помощью eq, что важно, если значения не являются символами или фиксированными числами (см. Предикаты равенства). Это означает, что переданные функции значения должны быть теми же значениями, которые использовались для установки свойства наложения, а не их копиями; объекты, которые различаются, не будут считаться равными, даже если они имеют идентичное содержимое.

Необязательные аргументы name и value должны либо оба быть переданы и не равны nil, либо оба опущены или равны nil.

Функция: copy-overlay overlay ¶

Эта функция возвращает копию overlay. Копия имеет те же конечные точки и свойства, что и overlay. Однако тип вставки текста для начала наложения и для конца наложения устанавливается в значения по умолчанию.

Вот несколько примеров:

;; Создание наложения.
(setq foo (make-overlay 1 10))
     ⇒ #<наложение от 1 до 10 в display.texi>

(overlay-start foo)
     ⇒ 1

(overlay-end foo)
     ⇒ 10
(overlay-buffer foo)
     ⇒ #<буфер display.texi>
;; Присвоение ему свойства, которое мы можем проверить позже.
(overlay-put foo 'happy t)
     ⇒ t
;; Проверка наличия свойства.
(overlay-get foo 'happy)
     ⇒ t

;; Перемещение наложения.
(move-overlay foo 5 20)
     ⇒ #<наложение от 5 до 20 в display.texi>
(overlay-start foo)
     ⇒ 5
(overlay-end foo)
     ⇒ 20

;; Удаление наложения.
(delete-overlay foo)
     ⇒ nil
;; Проверка его удаления.
foo
     ⇒ #<наложение в отсутствии буфера>
;; У удаленного наложения нет позиции.
(overlay-start foo)
     ⇒ nil
(overlay-end foo)
     ⇒ nil
(overlay-buffer foo)
     ⇒ nil

;; Восстановление наложения.
(move-overlay foo 1 20)
     ⇒ #<наложение от 1 до 20 в display.texi>
;; Проверка результатов.
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 20
(overlay-buffer foo)
     ⇒ #<буфер display.texi>

;; Перемещение и удаление наложения не меняет его свойств.
(overlay-get foo 'happy)
     ⇒ t