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.

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.

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. See 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-startoverlay

This function returns the position at which overlay starts,
as an integer.

Function: overlay-endoverlay

This function returns the position at which overlay ends,
as an integer.

Function: overlay-bufferoverlay

This function returns the buffer that overlay belongs to. It
returns nil if overlay has been deleted.

Function: delete-overlayoverlay

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-overlayoverlay 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-overlayoverlay

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 (see Marker Insertion Types).

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-recenterpos

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.