From ae20c1c3bdc3630056552edd6becb0e9620a474c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 18 May 2024 12:15:21 +0300 Subject: [PATCH] Document :box attribute caveats when used on display strings * doc/lispref/display.texi (Replacing Specs, Face Attributes): Mention special considerations when a display string has a ':box' face attribute identical to the surrounding buffer text. Suggested by JD Smith . (Bug#70637) (cherry picked from commit df1a9e42ba483f2a0e3747abc7edb16818993f13) --- doc/lispref/display.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 59e1f5cd2f2..39a5bbc106e 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2752,6 +2752,11 @@ being pressed. If it is @code{pressed-button}, the box looks like a @code{flat-button} or omitted, a plain 2D box is used. @end table +If you use the @code{:box} face attribute on strings displayed instead +of buffer text via the @code{display} text property, special +considerations might apply if the surrounding buffer text also has the +@code{:box} face attribute. @xref{Replacing Specs}. + @item :inverse-video Whether or not characters should be displayed in inverse video. The value should be @code{t} (yes) or @code{nil} (no). @@ -5308,6 +5313,34 @@ characters get a second string (@code{concat} creates a new string object), so they are replaced with one @samp{A}; and so on. Thus, the ten characters appear as five A's. +@cindex box face attribute, and @code{display} properties +Note: Using @code{:box} face attribute (@pxref{Face Attributes}) on a +replacing @code{display} string that is adjacent to normal text with +the same @code{:box} style can lead to display artifacts when moving +the cursor across the text with this face attribute. These can be +avoided by applying the @code{:box} attribute directly to the text +being replaced, rather than (or in addition to) the @code{display} +string itself. Here's an example: + +@smallexample +@group +;; Causes display artifacts when moving the cursor across text +(progn + (put-text-property 1 2 'display (propertize " [" 'face '(:box t))) + (put-text-property 2 3 'face '(:box t)) + (put-text-property 3 4 'display (propertize "] " 'face '(:box t)))) +@end group + +@group +;; No display artifacts due to `:box' +(progn + (add-text-properties 1 2 '(face (:box t) display " [")) + (put-text-property 2 3 'face '(:box t)) + (add-text-properties 3 4 '(face (:box t) display "] "))) +@end group +@end smallexample + + @node Specified Space @subsection Specified Spaces @cindex spaces, specified height or width -- 2.39.5