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. See 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:
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
categoryproperty which is a symbol, that symbol's prop property is used. Otherwise, the value is
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.
Many overlay properties have special meanings; here is a table of them:
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
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
), 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
overlays-at. See Finding Overlays.
windowproperty is non-
nil, then the overlay applies only on that window.
categoryproperty, 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.
...), where each keyword is a face attribute name and value is a value for that attribute.
). This specifies the foreground or background color, similar to
). This form is supported for backward compatibility only, and should be avoided.
facewhen 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.,
:slant). Those attributes are always the same as in the unhighlighted text.
help-echoproperty, 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.
fieldproperty constitute a field. Some motion functions including
beginning-of-linestop moving at a field boundary. See Fields.
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
nil, and the beginning and end of the text range to be
When called after a change, each function receives five arguments: the
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
t around doing so, to
avoid confusing the internal mechanism that calls these hooks.
Text properties also support the
but the details are somewhat different (see Special Properties).
invisibleproperty can make the text in the overlay invisible, which means that it does not appear on the screen. See Invisible Text, for details.
intangibleproperty on an overlay works just like the
intangibletext property. It is obsolete. See Special Properties, for details.
nil, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give an empty overlay (see empty overlay) a non-
evaporateproperty, 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.
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. See Active Keymaps.
local-mapproperty is similar to
keymapbut replaces the buffer's local map rather than augmenting existing keymaps. This also means it has lower precedence than minor mode keymaps.
local-map properties do not affect a
string displayed by the
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
local-map text property. See Special Properties.