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
property value generally apply in parallel to the text they cover.
If several sources (overlays and/or a text property) specify values
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
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
(see Examining Text Properties), but works on the
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
and in that case, position and object are ignored. (This
can be useful if you’ve already gotten the
get-char-property, for instance (see Examining Text Properties).
display property prop of value to the text from
start to end.
If any text in the region has a non-
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
display property, the region from 4 to 8 will have both the
display properties, and finally
the region from 8 to 12 will only have the
If object is non-
nil, it should be a string or a buffer.
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
The rest of this section describes several kinds of display specifications and what they mean.