41.16 The 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.

Function: get-display-property position prop &optional object properties

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).

Function: add-display-text-property start end prop value &optional object

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.