elisp: Managing Overlays
37.9.1 Managing Overlays
------------------------
This section describes the functions to create, delete and move
overlays, and to examine their contents. Overlay changes are not
recorded in the buffer’s undo list, since the overlays are not part of
the buffer’s contents.
-- Function: overlayp object
This function returns ‘t’ if OBJECT is an overlay.
-- Function: make-overlay start end &optional buffer front-advance
rear-advance
This function creates and returns an overlay that belongs to BUFFER
and ranges from START to END. Both START and END must specify
buffer positions; they may be integers or markers. If BUFFER is
omitted, the overlay is created in the current buffer.
An overlay whose START and END specify the same buffer position is
known as “empty”. A non-empty overlay can become empty if the text
between its START and END is deleted. When that happens, the
overlay is by default not deleted, but you can cause it to be
deleted by giving it the ‘evaporate’ property (
evaporate
property Overlay Properties.).
The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker
insertion type for the start of the overlay and for the end of the
overlay, respectively. Marker Insertion Types. If they
are both ‘nil’, the default, then the overlay extends to include
any text inserted at the beginning, but not text inserted at the
end. If FRONT-ADVANCE is non-‘nil’, text inserted at the beginning
of the overlay is excluded from the overlay. If REAR-ADVANCE is
non-‘nil’, text inserted at the end of the overlay is included in
the overlay.
-- Function: overlay-start overlay
This function returns the position at which OVERLAY starts, as an
integer.
-- Function: overlay-end overlay
This function returns the position at which OVERLAY ends, as an
integer.
-- Function: overlay-buffer overlay
This function returns the buffer that OVERLAY belongs to. It
returns ‘nil’ if OVERLAY has been deleted.
-- Function: delete-overlay overlay
This function deletes OVERLAY. The overlay continues to exist as a
Lisp object, and its property list is unchanged, but it ceases to
be attached to the buffer it belonged to, and ceases to have any
effect on display.
A deleted overlay is not permanently disconnected. You can give it
a position in a buffer again by calling ‘move-overlay’.
-- Function: move-overlay overlay start end &optional buffer
This function moves OVERLAY to BUFFER, and places its bounds at
START and END. Both arguments START and END must specify buffer
positions; they may be integers or markers.
If BUFFER is omitted, OVERLAY stays in the same buffer it was
already associated with; if OVERLAY was deleted, it goes into the
current buffer.
The return value is OVERLAY.
This is the only valid way to change the endpoints of an overlay.
Do not try modifying the markers in the overlay by hand, as that
fails to update other vital data structures and can cause some
overlays to be lost.
-- Function: remove-overlays &optional start end name value
This function removes all the overlays between START and END whose
property NAME has the value VALUE. It can move the endpoints of
the overlays in the region, or split them.
If NAME is omitted or ‘nil’, it means to delete all overlays in the
specified region. If START and/or END are omitted or ‘nil’, that
means the beginning and end of the buffer respectively. Therefore,
‘(remove-overlays)’ removes all the overlays in the current buffer.
-- Function: copy-overlay overlay
This function returns a copy of OVERLAY. The copy has the same
endpoints and properties as OVERLAY. However, the marker insertion
type for the start of the overlay and for the end of the overlay
are set to their default values (Marker Insertion Types).
Here are some examples:
;; 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
Emacs stores the overlays of each buffer in two lists, divided around
an arbitrary center position. One list extends backwards through the
buffer from that center position, and the other extends forwards from
that center position. The center position can be anywhere in the
buffer.
-- Function: overlay-recenter pos
This function recenters the overlays of the current buffer around
position POS. That makes overlay lookup faster for positions near
POS, but slower for positions far away from POS.
A loop that scans the buffer forwards, creating overlays, can run
faster if you do ‘(overlay-recenter (point-max))’ first.
Info Catalog
elisp: Overlays
elisp: Overlay Properties