From df1a9e42ba483f2a0e3747abc7edb16818993f13 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 18 May 2024 12:15:21 +0300 Subject: 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) --- doc/lispref/display.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index f20064519fc..869bf15a40a 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2747,6 +2747,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). @@ -5266,6 +5271,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 -- cgit v1.2.3