42.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 considered 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 (see evaporate property).

The arguments front-advance and rear-advance specify what happens when text is inserted at the beginning (i.e., before start) and at the end. 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 the specified 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 in that buffer. 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 previously deleted (and thus isn’t associated with any buffer), it goes into the current buffer.

The return value is overlay.

This function is the only valid way to change the endpoints of an overlay.

Function: remove-overlays &optional start end name value ¶

This function clears the text in the region between start and end of any overlays whose property named name has the specified value, such that no such overlay will affect the text in the region. To do this, the function can remove overlays in the region, or move their endpoints, or split them, or do some combination of these. Specifically:

• Overlays that start at or after start and end before end will be removed completely.
• Overlays that start before start and end after start, but before end, will be altered so that they end at start.
• Overlays that start at or after start and end after end will be altered so that they start at end.
• Overlays that start before start and end after end will be split into two overlays: one that ends at start and the other that begins at end.

If name is omitted or nil, it means to delete/modify all overlays that affect text in the specified region. If start and/or end are omitted or nil, they default to the beginning and end of the buffer, respectively. Therefore, (remove-overlays) removes all the overlays in the current buffer.

Values of the named overlay property are compared using eq, which is important if the values are anything but symbols or fixnums (see Equality Predicates). It means the values passed to the function must be the same values used to set the overlay property, not their copies; objects which are different will not compare equal even if they have identical contents.

The optional arguments name and value should either both be passed and non-nil, or both omitted or nil.

Function: copy-overlay overlay ¶

This function returns a copy of overlay. The copy has the same endpoints and properties as overlay. However, the text insertion type for the start of the overlay and for the end of the overlay are set to their default values.

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