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 spec &optional object properties

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

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

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.

Function: remove-display-text-property start end spec &optional object

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:

The region from 1 to 2, only raise
The region from 2 to 4, no properties
The region from 4 to 6, only height
The region from 6 to 8, both 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.