38.15.1 Display Specs That Replace The Text

Some kinds of display specifications specify something to display instead of the text that has the property. These are called replacing display specifications. Emacs does not allow the user to interactively move point into the middle of buffer text that is replaced in this way.

If a list of display specifications includes more than one replacing display specification, the first overrides the rest. Replacing display specifications make most other display specifications irrelevant, since those don't apply to the replacement.

For replacing display specifications, “the text that has the property” 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.