38.15 The display Property

The display text property (or overlay property) is used to insert images into text, and also 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.

Some kinds of display properties specify something to display instead of the text that has the property. In this case, “the text” means all the consecutive characters that have the same Lisp object as their display property; these characters are replaced as a single unit. By contrast, characters that have similar but distinct Lisp objects as their display properties are handled separately. Here's a function that illustrates this point:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1))))

It gives each of the first ten characters in the buffer string "A" as the display property, but they don't all get the same string. The first two characters get the same string, so they together are replaced with one `A'. The next two characters get a second string, so they together are replaced with one `A'. Likewise for each following pair of characters. Thus, the ten characters appear as five A's. This function would have the same results:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (2+ (point)) 'display string)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 2))))

This illustrates that what matters is the property value for each character. If two consecutive characters have the same object as the display property value, it's irrelevant whether they got this property from a single call to put-text-property or from two different calls.

The rest of this section describes several kinds of display specifications and what they mean.

• Specified Space: Displaying one space with a specified width.
• Pixel Specification: Specifying space width or height in pixels.
• Other Display Specs: Displaying an image; magnifying text; moving it up or down on the page; adjusting the width of spaces within text.
• Display Margins: Displaying text or images to the side of the main text.