GNU Emacs Lisp Reference Manual

35.9.2: Managing Overlays

This section describes the functions to create, delete and move overlays, and to examine their contents.

Function: make-overlay start end &optional buffer

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.

Function: overlay-start overlay

This function returns the position at which overlay starts.

Function: overlay-end overlay

This function returns the position at which overlay ends.

Function: overlay-buffer overlay

This function returns the buffer that overlay belongs to.

Function: delete-overlay overlay

This function deletes overlay. The overlay continues to exist as a Lisp object, but ceases to be part of the buffer it belonged to, and ceases to have any effect on display.

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, the overlay stays in the same 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: overlays-at pos

This function returns a list of all the overlays that contain position pos in the current buffer. The list is in no particular order. An overlay contains position pos if it begins at or before pos, and ends after pos.

Function: next-overlay-change pos

This function returns the buffer position of the next beginning or end of an overlay, after pos.

Function: previous-overlay-change pos

This function returns the buffer position of the previous beginning or end of an overlay, before pos.