GNU Emacs Lisp Reference Manual

35.9.1: Overlay Properties

Overlay properties are like text properties in some respects, but the differences are more important than the similarities. Text properties are considered a part of the text; overlays are specifically considered not to be part of the text. Thus, copying text between various buffers and strings preserves text properties, but does not try to preserve overlays. Changing a buffer's text properties marks the buffer as modified, while moving an overlay or changing its properties does not. Unlike text propery changes, overlay changes are not recorded in the buffer's undo list.

priority

This property's value (which should be a nonnegative number) determines the priority of the overlay. The priority matters when two or more overlays cover the same character and both specify a face for display; the one whose priority value is larger takes priority over the other, and its face attributes override the face attributes of the lower priority overlay.

Currently, all overlays take priority over text properties. Please avoid using negative priority values, as we have not yet decided just what they should mean.

window

If the window property is non-nil, then the overlay applies only on that window.

category

If an overlay has a category property, we call it the category of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay.

face

This property controls the font and color of text. Its value is a face name or a list of face names. See Faces, for more information. This feature may be temporary; in the future, we may replace it with other ways of specifying how to display text.

mouse-face

This property is used instead of face when the mouse is within the range of the overlay. This feature may be temporary, like face.

modification-hooks

This property's value is a list of functions to be called if any character within the overlay is changed or if text is inserted strictly within the overlay.

The hook functions are called both before and after each change. If the functions save the information they receive, and compare notes between calls, they can determine exactly what change has been made in the buffer text.

When called before a change, each function receives four arguments: the overlay, nil, and the beginning and end of the text range to be modified.

When called after a change, each function receives five arguments: the overlay, t, the beginning and end of the text range just modified, and the length of the pre-change text replaced by that range. (For an insertion, the pre-change length is zero; for a deletion, that length is the number of characters deleted, and the post-change beginning and end are equal.)

insert-in-front-hooks

This property's value is a list of functions to be called before and after inserting text right at the beginning of the overlay. The calling conventions are the same as for the modification-hooks functions.

insert-behind-hooks

This property's value is a list of functions to be called before and after inserting text right at the end of the overlay. The calling conventions are the same as for the modification-hooks functions.

invisible

The invisible property can make the text in the overlay invisible, which means that it does not appear on the screen. See Invisible Text, for details.

intangible

The intangible property on an overlay works just like the intangible text property. See Special Properties, for details.

before-string

This property's value is a string to add to the display at the beginning of the overlay. The string does not appear in the buffer in any sense---only on the screen. The string should contain only characters that display as a single column---control characters, including tabs or newlines, will give strange results.

after-string

This property's value is a string to add to the display at the end of the overlay. The string does not appear in the buffer in any sense---only on the screen. The string should contain only characters that display as a single column---control characters, including tabs or newlines, will give strange results.

evaporate

If this property is non-nil, the overlay is deleted automatically if it ever becomes empty (i.e., if it spans no characters).

These are the functions for reading and writing the properties of an overlay.

Function: overlay-get overlay prop

This function returns the value of property prop recorded in overlay, if any. If overlay does not record any value for that property, but it does have a category property which is a symbol, that symbol's prop property is used. Otherwise, the value is nil.

Function: overlay-put overlay prop value

This function sets the value of property prop recorded in overlay to value. It returns value.

See also the function get-char-property which checks both overlay properties and text properties for a given character. See Examining Properties.