39.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. The value of the display property should be a display specification, or a list or vector containing several display specifications. 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 Properties.

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.

• Replacing Specs: Display specs that replace the text.
• Specified Space: Displaying one space with a specified width.
• Pixel Specification: Specifying space width or height in pixels.
• Other Display Specs: Displaying an image; adjusting the height, spacing, and other properties of text.
• Display Margins: Displaying text or images to the side of the main text.