elisp: Overlay Properties
37.9.2 Overlay Properties
-------------------------
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
most respects they are different. 
Text Properties, for
comparison.
Text properties are considered a part of the text; overlays and their
properties 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 property changes, overlay
property changes are not recorded in the buffer’s undo list.
Since more than one overlay can specify a property value for the same
character, Emacs lets you specify a priority value of each overlay. The
priority value is used to decide which of the overlapping overlays will
“win”.
These functions read and set 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.
-- Function: overlay-properties overlay
This returns a copy of the property list of OVERLAY.
See also the function ‘get-char-property’ which checks both overlay
properties and text properties for a given character. Examining
Properties.
Many overlay properties have special meanings; here is a table of
them:
‘priority’
This property’s value determines the priority of the overlay. If
you want to specify a priority value, use either ‘nil’ (or zero),
or a positive integer. Any other value has undefined behavior.
The priority matters when two or more overlays cover the same
character and both specify the same property; the one whose
‘priority’ value is larger overrides the other. (For the ‘face’
property, the higher priority overlay’s value does not completely
override the other value; instead, its face attributes override the
face attributes of the lower priority ‘face’ property.) If two
overlays have the same priority value, and one is nested in the
other, then the inner one will prevail over the outer one. If
neither is nested in the other then you should not make assumptions
about which overlay will prevail.
Currently, all overlays take priority over text properties.
Note that Emacs sometimes uses non-numeric priority values for some
of its internal overlays, so do not try to do arithmetic on the
priority of an overlay (unless it is one that you created). In
particular, the overlay used for showing the region uses a priority
value of the form ‘(PRIMARY . SECONDARY)’, where the PRIMARY value
is used as described above, and SECONDARY is the fallback value
used when PRIMARY and the nesting considerations fail to resolve
the precedence between overlays. However, you are advised not to
design Lisp programs based on this implementation detail; if you
need to put overlays in priority order, use the SORTED argument of
‘overlays-at’. Finding Overlays.
‘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 appearance of the text (Faces).
The value of the property can be the following:
• A face name (a symbol or string).
• An anonymous face: a property list of the form ‘(KEYWORD VALUE
...)’, where each KEYWORD is a face attribute name and VALUE
is a value for that attribute.
• A list of faces. Each list element should be either a face
name or an anonymous face. This specifies a face which is an
aggregate of the attributes of each of the listed faces.
Faces occurring earlier in the list have higher priority.
• A cons cell of the form ‘(foreground-color . COLOR-NAME)’ or
‘(background-color . COLOR-NAME)’. This specifies the
foreground or background color, similar to ‘(:foreground
COLOR-NAME)’ or ‘(:background COLOR-NAME)’. This form is
supported for backward compatibility only, and should be
avoided.
‘mouse-face’
This property is used instead of ‘face’ when the mouse is within
the range of the overlay. However, Emacs ignores all face
attributes from this property that alter the text size (e.g.,
‘:height’, ‘:weight’, and ‘:slant’). Those attributes are always
the same as in the unhighlighted text.
‘display’
This property activates various features that change the way text
is displayed. For example, it can make text appear taller or
shorter, higher or lower, wider or narrower, or replaced with an
image. Display Property.
‘help-echo’
If an overlay has a ‘help-echo’ property, then when you move the
mouse onto the text in the overlay, Emacs displays a help string in
the echo area, or in the tooltip window. For details see
Text help-echo.
‘field’
Consecutive characters with the same ‘field’ property constitute a
_field_. Some motion functions including ‘forward-word’ and
‘beginning-of-line’ stop moving at a field boundary.
Fields.
‘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.)
If these functions modify the buffer, they should bind
‘inhibit-modification-hooks’ to ‘t’ around doing so, to avoid
confusing the internal mechanism that calls these hooks.
Text properties also support the ‘modification-hooks’ property, but
the details are somewhat different (Special Properties).
‘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.
Invisible Text, for details.
‘intangible’
The ‘intangible’ property on an overlay works just like the
‘intangible’ text property. It is obsolete. Special
Properties, for details.
‘isearch-open-invisible’
This property tells incremental search how to make an invisible
overlay visible, permanently, if the final match overlaps it.
Invisible Text.
‘isearch-open-invisible-temporary’
This property tells incremental search how to make an invisible
overlay visible, temporarily, during the search. Invisible
Text.
‘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.
‘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.
‘line-prefix’
This property specifies a display spec to prepend to each
non-continuation line at display-time. Truncation.
‘wrap-prefix’
This property specifies a display spec to prepend to each
continuation line at display-time. Truncation.
‘evaporate’
If this property is non-‘nil’, the overlay is deleted automatically
if it becomes empty (i.e., if its length becomes zero). If you
give an empty overlay (empty overlay Managing Overlays.) a
non-‘nil’ ‘evaporate’ property, that deletes it immediately. Note
that, unless an overlay has this property, it will not be deleted
when the text between its starting and ending positions is deleted
from the buffer.
‘keymap’
If this property is non-‘nil’, it specifies a keymap for a portion
of the text. This keymap is used when the character after point is
within the overlay, and takes precedence over most other keymaps.
Active Keymaps.
‘local-map’
The ‘local-map’ property is similar to ‘keymap’ but replaces the
buffer’s local map rather than augmenting existing keymaps. This
also means it has lower precedence than minor mode keymaps.
The ‘keymap’ and ‘local-map’ properties do not affect a string
displayed by the ‘before-string’, ‘after-string’, or ‘display’
properties. This is only relevant for mouse clicks and other mouse
events that fall on the string, since point is never on the string. To
bind special mouse events for the string, assign it a ‘keymap’ or
‘local-map’ text property. Special Properties.
Info Catalog
elisp: Managing Overlays
elisp: Overlays
elisp: Finding Overlays