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

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

Функция: 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.
• Пустые оверлеи (см. пустые оверлеи) будут удалены, если они находятся в позиции start, строго между start и end (не включая end) или в позиции end, когда end обозначает позицию в конце буфера.

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

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

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

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

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

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

;; Create an overlay.
(setq foo (make-overlay 1 10))
     ⇒ #<overlay from 1 to 10 in display.texi>

(overlay-start foo)
     ⇒ 1

(overlay-end foo)
     ⇒ 10
(overlay-buffer foo)
     ⇒ #<buffer display.texi>
;; Give it a property we can check later.
(overlay-put foo 'happy t)
     ⇒ t
;; Verify the property is present.
(overlay-get foo 'happy)
     ⇒ t

;; Move the overlay.
(move-overlay foo 5 20)
     ⇒ #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
     ⇒ 5
(overlay-end foo)
     ⇒ 20

;; Delete the overlay.
(delete-overlay foo)
     ⇒ nil
;; Verify it is deleted.
foo
     ⇒ #<overlay in no buffer>
;; A deleted overlay has no position.
(overlay-start foo)
     ⇒ nil
(overlay-end foo)
     ⇒ nil
(overlay-buffer foo)
     ⇒ nil

;; Undelete the overlay.
(move-overlay foo 1 20)
     ⇒ #<overlay from 1 to 20 in display.texi>
;; Verify the results.
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 20
(overlay-buffer foo)
     ⇒ #<buffer display.texi>

;; Moving and deleting the overlay does not change its properties.
(overlay-get foo 'happy)
     ⇒ t