display Property ¶The 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 the value of a specific
display specification, no matter whether the display property is
a vector, a list or a single display specification. This is like
get-text-property (see Examining Text Properties), but works on
the display property only. For specifications with a single
value (e.g. height), this returns the value itself; for
properties with a list of values (e.g. slice), this returns the
list of values.
position is the position in the buffer or string to examine, and
spec is the CAR of the display specification 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 the display specification (prop 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 specification, the region from 4 to 8 will have both the
raise and height display specifications, and finally the
region from 8 to 12 will only have the raise display
specification.
object is either a string or a buffer to add the specification to. If omitted, object defaults to the current buffer.
Remove the display specification spec from the text from
start to end. spec is the CAR of the display
specification to remove, e.g. height or '(margin nil).
If any text in the region has any other display properties, those
properties are retained. For instance:
(add-display-text-property 1 8 'raise 0.5) (add-display-text-property 4 8 'height 2.0) (remove-display-text-property 2 6 'raise)
After doing this, the text will have the following display
properties:
raise
height
raise and height
object is either a string or a buffer to remove the specification from. If omitted, object 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.