display PropertyThe display text property (or overlay property) is used to
insert images into text, and to control other aspects of how text
displays. Display specifications in the same display
property value generally apply in parallel to the text they cover.
If several sources (overlays and/or a text property) specify values
for the display property, only one of the values takes effect,
following the rules of get-char-property. See Examining Text Properties.
The value of the display property should be a display
specification, or a list or vector containing several display
specifications.
This convenience function can be used to get a specific display
property, no matter whether the display property is a vector, a
list or a simple property. This is like get-text-property
(see Examining Text Properties), but works on the display
property only.
position is the position in the buffer or string to examine, and
prop is the display property to return. The optional
object argument should be either a string or a buffer, and
defaults to the current buffer. If the optional properties
argument is non-nil, it should be a display property,
and in that case, position and object are ignored. (This
can be useful if you’ve already gotten the display property
with get-char-property, for instance (see Examining Text Properties).
Add display property prop of value to the text from
start to end.
If any text in the region has a non-nil display
property, those properties are retained. For instance:
(add-display-text-property 4 8 'height 2.0) (add-display-text-property 2 12 'raise 0.5)
After doing this, the region from 2 to 4 will have the raise
display property, the region from 4 to 8 will have both the
raise and height display properties, and finally
the region from 8 to 12 will only have the raise display
property.
If object is non-nil, it should be a string or a buffer.
If nil, this defaults to the current buffer.
Some of the display specifications allow inclusion of Lisp forms,
which are evaluated at display time. This could be unsafe in certain
situations, e.g., when the display specification was generated by some
external program/agent. Wrapping a display specification in a list
that begins with the special symbol disable-eval, as in
(disable-eval spec), will disable evaluation of any
Lisp in spec, while still supporting all the other display
property features.
The rest of this section describes several kinds of display specifications and what they mean.