Next: Managing Overlays, Up: Overlays
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 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 property changes, overlay changes are not recorded in the buffer's undo list. See Text Properties, for comparison.
These functions are used for reading and writing 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
category
property which is a symbol, that symbol's prop property is used. Otherwise, the value isnil
.
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:
priority
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
window
property is non-nil
, then the overlay
applies only on that window.
category
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
In the simplest case, the value is a face name. It can also be a list; then each element can be any of these possibilities:
(foreground-color .
color-name)
or
(background-color .
color-name)
. These elements specify
just the foreground color or just the background color.
(foreground-color .
color-name)
is equivalent to
(:foreground
color-name)
, and likewise for the background.
mouse-face
face
when the mouse is within
the range of the overlay.
display
help-echo
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. This feature is available starting in Emacs 21.
modification-hooks
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
modification-hooks
functions.
insert-behind-hooks
modification-hooks
functions.
invisible
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
intangible
property on an overlay works just like the
intangible
text property. See Special Properties, for details.
isearch-open-invisible
isearch-open-invisible-temporary
before-string
after-string
evaporate
nil
, the overlay is deleted automatically
if it ever becomes empty (i.e., if it spans no characters).
local-map
nil
, it specifies a keymap for a portion
of the text. The property's value replaces the buffer's local map, when
the character after point is within the overlay. See Active Keymaps.
keymap
keymap
property is similar to local-map
but overrides the
buffer's local map (and the map specified by the local-map
property) rather than replacing it.