Added background highlight in richtext

phax · phax · commit c5433346c644 · 2026-05-31T00:15:19.000+02:00
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ A set of example files as created from the unit test can be found in folder [exa
 
 # Rich text (markup) — module `ph-pdf-layout-richtext`
 
-The optional sibling module **`ph-pdf-layout-richtext`** adds **multi-style runs inside a single paragraph** — i.e. a single text element can carry mixed bold/italic, per-segment colors, in-line hyperlinks, anchors, underlines, and sub/superscript.
+The optional sibling module **`ph-pdf-layout-richtext`** adds **multi-style runs inside a single paragraph** — i.e. a single text element can carry mixed bold/italic, per-segment colors, in-line hyperlinks, anchors, underlines, sub/superscript and background highlights.
 The base `PLText` is single-style by design; rich text fills that gap.
 
 ## Huge credit where it's due
@@ -72,6 +72,9 @@ Markup syntax (Markdown / CommonMark style for bold, italic and line breaks; the
 | `{_:0.5|0.2}foo{_}` | subscript with explicit fontScale and baselineOffset |
 | `{color:#rrggbb}` | switches the current colour to RGB (set, not toggle — reset with `{color:#000000}`) |
 | `{color_cmyk:C,M,Y,K}` | switches the current colour to CMYK (percent values 0..100, floats OK — e.g. `{color_cmyk:75,15,0,20}`). The RGB marker is unchanged. Originally requested at [ralfstuckert/pdfbox-layout#94](https://github.com/ralfstuckert/pdfbox-layout/issues/94). |
+| `{bg:#rrggbb}…{bg}` | fills a background rectangle behind the wrapped run (default `tight` extent — per-segment box that follows sub/superscript shifts) |
+| `{bg:tight:#rrggbb}…{bg}` | background with explicit `tight` extent — same as the default |
+| `{bg:line:#rrggbb}…{bg}` | background with `line` extent — uses the line's full slot so the highlight stays a single uniform rectangle across mixed sizes / sub-superscript, and is contiguous across wrapped lines |
 | `{link[uri]}…{link}` | wraps the inner text in an external hyperlink (default underline-decorated) |
 | `{link:none[uri]}…{link}` | hyperlink with no visual decoration |
 | `{link[#name]}…{link}` | internal link jumping to a named anchor declared elsewhere |
@@ -172,6 +175,13 @@ Between v4.0.0 and v5.2.2 the `artifactId` was called `ph-pdf-layout4`
 
 # News and Noteworthy
 
+v8.3.2 - in development
+* `ph-pdf-layout-richtext`: added inline **background-color markup** — `{bg:#rrggbb}…{bg}` fills a rectangle behind the wrapped run. Two vertical-extent modes selected by an optional qualifier:
+  * `{bg:#rrggbb}` / `{bg:tight:#rrggbb}` — **tight** (default): per-segment box sized to the segment's own font, anchored on its (possibly sub/superscript-shifted) baseline; the highlight follows the visible glyphs.
+  * `{bg:line:#rrggbb}` — **line-height**: box sized to the line's full slot using the unshifted baseline, so the highlight stays a single uniform rectangle across sub/superscript and is contiguous across wrapped lines.
+  * Backgrounds are painted *before* the glyphs and the existing post-text decorations (underline, hyperlink, anchor); they compose with bold / italic / colour / underline / sub-superscript inside the span.
+  * Internally: new `PLBackgroundAnnotation` (an `IPLRichTextAnnotation`) plus `EPLBackgroundExtent` enum (`TIGHT`, `LINE_HEIGHT`); new `BackgroundFactory` in `PLMarkupCharacters`; pre-text fill pass added in `PLRichText`'s render loop.
+
 v8.3.1 - 2026-05-30
 * **`ph-pdf-layout-richtext` markup syntax is now Markdown / CommonMark style** — breaking change vs v8.3.0:
   * Bold is `**bold**` (was `*bold*`).
diff --git a/example-files/richtext/richtext-background.pdf b/example-files/richtext/richtext-background.pdf
diff --git a/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/annotation/EPLBackgroundExtent.java b/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/annotation/EPLBackgroundExtent.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2026 Philip Helger (www.helger.com)
+ * philip[at]helger[dot]com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.helger.pdflayout.richtext.annotation;
+
+/**
+ * Vertical extent of the background fill rectangle behind a rich-text segment.
+ *
+ * @author Philip Helger
+ */
+public enum EPLBackgroundExtent
+{
+  /**
+   * Box sized to the segment's own font (its text height and descent). Sub-/superscript segments
+   * follow their shifted baseline, so the highlight tracks the visible glyphs even when their
+   * dimensions differ from the rest of the line. This is the HTML
+   * <code>&lt;span style="background-color"&gt;</code> look.
+   */
+  TIGHT,
+  /**
+   * Box sized to the full line slot of the enclosing rich-text element. All segments on a line
+   * share identical Y bounds — adjacent segments meet without seams and the background extends
+   * into the line-spacing gap so consecutive lines of a multi-line highlight stay visually
+   * contiguous (Word "highlight" look).
+   */
+  LINE_HEIGHT
+}
diff --git a/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/annotation/PLBackgroundAnnotation.java b/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/annotation/PLBackgroundAnnotation.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright (C) 2026 Philip Helger (www.helger.com)
+ * philip[at]helger[dot]com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.helger.pdflayout.richtext.annotation;
+
+import org.jspecify.annotations.NonNull;
+
+import com.helger.annotation.concurrent.Immutable;
+import com.helger.base.enforce.ValueEnforcer;
+import com.helger.base.tostring.ToStringGenerator;
+import com.helger.pdflayout.base.PLColor;
+
+/**
+ * Background-color annotation for rich text. Fills a rectangle behind the annotated run before the
+ * glyphs are emitted. The vertical extent of the rectangle is selected via
+ * {@link EPLBackgroundExtent}.
+ *
+ * @author Philip Helger
+ */
+@Immutable
+public final class PLBackgroundAnnotation implements IPLRichTextAnnotation
+{
+  /** Default vertical extent: {@link EPLBackgroundExtent#TIGHT}. */
+  public static final EPLBackgroundExtent DEFAULT_EXTENT = EPLBackgroundExtent.TIGHT;
+
+  private final PLColor m_aColor;
+  private final EPLBackgroundExtent m_eExtent;
+
+  public PLBackgroundAnnotation (@NonNull final PLColor aColor)
+  {
+    this (aColor, DEFAULT_EXTENT);
+  }
+
+  public PLBackgroundAnnotation (@NonNull final PLColor aColor, @NonNull final EPLBackgroundExtent eExtent)
+  {
+    ValueEnforcer.notNull (aColor, "Color");
+    ValueEnforcer.notNull (eExtent, "Extent");
+    m_aColor = aColor;
+    m_eExtent = eExtent;
+  }
+
+  @NonNull
+  public PLColor getColor ()
+  {
+    return m_aColor;
+  }
+
+  @NonNull
+  public EPLBackgroundExtent getExtent ()
+  {
+    return m_eExtent;
+  }
+
+  @Override
+  public String toString ()
+  {
+    return new ToStringGenerator (this).append ("Color", m_aColor).append ("Extent", m_eExtent).getToString ();
+  }
+}
diff --git a/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/element/PLRichText.java b/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/element/PLRichText.java
@@ -49,8 +49,10 @@
 import com.helger.pdflayout.render.PageRenderContext;
 import com.helger.pdflayout.render.PreparationContext;
 import com.helger.pdflayout.render.PreparationContextGlobal;
+import com.helger.pdflayout.richtext.annotation.EPLBackgroundExtent;
 import com.helger.pdflayout.richtext.annotation.IPLRichTextAnnotation;
 import com.helger.pdflayout.richtext.annotation.PLAnchorAnnotation;
+import com.helger.pdflayout.richtext.annotation.PLBackgroundAnnotation;
 import com.helger.pdflayout.richtext.annotation.PLHyperlinkAnnotation;
 import com.helger.pdflayout.richtext.annotation.PLUnderlineAnnotation;
 import com.helger.pdflayout.richtext.run.PLFontFamily;
@@ -408,6 +410,19 @@ protected void onRender (@NonNull final PageRenderContext aCtx) throws IOExcepti
       final float fIndentX = getIndentX (fPreparedWidth, fLineWidth);
       // PDF user-space baseline of this line (Y grows upward).
       final float fBaselineY = fRenderTop - m_fTextHeight - m_fDescent - nLine * m_fTextHeight * m_fLineSpacing;
+      final boolean bIsLastLine = nLine == nLineCount - 1;
+      // Deepest descent (most-negative value) across the segments of THIS line.
+      // We can't reuse the element-wide m_fDescent because onPrepare folds it
+      // with Math.max starting at 0, which clamps negative descents to 0 — the
+      // layout tolerates that for baseline positioning but a LINE_HEIGHT
+      // highlight needs the actual depth so descenders are covered.
+      float fLineDescent = 0f;
+      for (final PLRichTextSegment aSeg : aLine.segments ())
+      {
+        final float fSegDescent = aSeg.getLoadedFont ().getDescent (aSeg.getFontSpec ().getFontSize ());
+        if (fSegDescent < fLineDescent)
+          fLineDescent = fSegDescent;
+      }
 
       // Compute character spacing for JUSTIFY/BLOCK. This matches how
       // AbstractPLText justifies — extra width is distributed across all
@@ -441,6 +456,27 @@ protected void onRender (@NonNull final PageRenderContext aCtx) throws IOExcepti
         final float fFontSize = aSeg.getFontSpec ().getFontSize ();
         final float fSegBaselineY = fBaselineY - fFontSize * aSeg.getBaselineOffsetScale ();
 
+        // Pre-text pass: backgrounds must paint BEFORE the glyphs so the text
+        // stays on top. Width-zero or empty segments contribute nothing visible.
+        if (nSegChars > 0 && fSegFullWidth > 0f)
+        {
+          for (final IPLRichTextAnnotation aAnn : aSeg.annotations ())
+          {
+            if (aAnn instanceof final PLBackgroundAnnotation aBg)
+            {
+              _drawBackground (aCS,
+                               aSeg,
+                               aBg,
+                               fSegStartX,
+                               fSegFullWidth,
+                               fSegBaselineY,
+                               fBaselineY,
+                               fLineDescent,
+                               bIsLastLine);
+            }
+          }
+        }
+
         if (nSegChars > 0)
         {
           aCS.beginText ();
@@ -451,7 +487,8 @@ protected void onRender (@NonNull final PageRenderContext aCtx) throws IOExcepti
           aCS.endText ();
         }
 
-        // Inline annotations: underline, hyperlink, anchor.
+        // Post-text pass: underline, hyperlink, anchor (drawn over the glyphs
+        // where applicable, or registered with the page).
         for (final IPLRichTextAnnotation aAnn : aSeg.annotations ())
         {
           if (aAnn instanceof final PLUnderlineAnnotation aUnderline)
@@ -487,6 +524,46 @@ private static int _countCharsInLine (@NonNull final PLRichTextLine aLine)
     return n;
   }
 
+  private void _drawBackground (@NonNull final PDPageContentStreamWithCache aCS,
+                                @NonNull final PLRichTextSegment aSeg,
+                                @NonNull final PLBackgroundAnnotation aBg,
+                                final float fStartX,
+                                final float fSegWidth,
+                                final float fSegBaselineY,
+                                final float fLineBaselineY,
+                                final float fLineDescent,
+                                final boolean bIsLastLine) throws IOException
+  {
+    // Note on the descent sign: PDFontDescriptor stores Descent as a NEGATIVE
+    // value (the PDF spec convention — distance below the baseline). We follow
+    // the same convention here: `baseline + descent` lands BELOW the baseline.
+    final float fBottomY;
+    final float fHeight;
+    if (aBg.getExtent () == EPLBackgroundExtent.LINE_HEIGHT)
+    {
+      // Full line slot of the enclosing element. Anchor at the line's UNshifted
+      // baseline (so sub/superscript segments don't perturb the box) and pull
+      // the bottom down by the line's deepest descent so descenders are
+      // covered. Height is the baseline-to-baseline distance for non-last
+      // lines (which makes consecutive lines' boxes contiguous through the
+      // leading gap) and the bare textHeight for the last line.
+      fBottomY = fLineBaselineY + fLineDescent;
+      fHeight = bIsLastLine ? m_fTextHeight : m_fTextHeight * m_fLineSpacing;
+    }
+    else
+    {
+      // Tight box around this segment's own font, anchored on the SHIFTED
+      // baseline so sub/superscript highlights follow the visible glyphs.
+      final float fFontSize = aSeg.getFontSpec ().getFontSize ();
+      final float fSegDescent = aSeg.getLoadedFont ().getDescent (fFontSize);
+      final float fSegTextHeight = aSeg.getLoadedFont ().getTextHeight (fFontSize);
+      fBottomY = fSegBaselineY + fSegDescent;
+      fHeight = fSegTextHeight;
+    }
+    aCS.setNonStrokingColor (aBg.getColor ());
+    aCS.fillRect (fStartX, fBottomY, fSegWidth, fHeight);
+  }
+
   private static void _drawUnderline (@NonNull final PDPageContentStreamWithCache aCS,
                                       @NonNull final PLRichTextSegment aSeg,
                                       @NonNull final PLUnderlineAnnotation aUnderline,
diff --git a/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/markup/PLMarkupCharacters.java b/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/markup/PLMarkupCharacters.java
@@ -22,9 +22,11 @@
 import org.jspecify.annotations.NonNull;
 
 import com.helger.pdflayout.base.PLColor;
+import com.helger.pdflayout.richtext.annotation.EPLBackgroundExtent;
 import com.helger.pdflayout.richtext.annotation.EPLLinkStyle;
 import com.helger.pdflayout.richtext.color.PLCMYKColor;
 import com.helger.pdflayout.richtext.annotation.PLAnchorAnnotation;
+import com.helger.pdflayout.richtext.annotation.PLBackgroundAnnotation;
 import com.helger.pdflayout.richtext.annotation.PLHyperlinkAnnotation;
 import com.helger.pdflayout.richtext.annotation.PLUnderlineAnnotation;
 
@@ -47,6 +49,11 @@
  * <li>{@code {^}sup{^}} — toggles superscript (font scaled, baseline shifted up)</li>
  * <li>{@code {_:0.5|0.2}sub{_}} — subscript with custom font / baseline scale</li>
  * <li>{@code {color:#rrggbb}} — switches the current color</li>
+ * <li>{@code {bg:#rrggbb}text{bg}} — fills a background rectangle behind the text.
+ * The extent defaults to {@link EPLBackgroundExtent#TIGHT tight} (the segment's
+ * own font box); writing {@code {bg:line:#rrggbb}} selects
+ * {@link EPLBackgroundExtent#LINE_HEIGHT line-height} (full line slot, contiguous
+ * across adjacent segments and across wrapped lines).</li>
  * <li>{@code {link:ul[http://example.com]}} — wraps text in a hyperlink. The
  * style (<code>ul</code> = underline, <code>none</code> = no decoration) is
  * optional and defaults to underline.</li>
@@ -158,6 +165,9 @@ public final class PLMarkupCharacters
   /** Factory for the anchor marker {@code {anchor:name}}. */
   public static final IPLMarkupCharacterFactory ANCHOR = new AnchorFactory ();
 
+  /** Factory for the background marker {@code {bg:#rrggbb}}…{@code {bg}}. */
+  public static final IPLMarkupCharacterFactory BACKGROUND = new BackgroundFactory ();
+
   private PLMarkupCharacters ()
   {}
 
@@ -670,6 +680,71 @@ public String unescape (@NonNull final String sText)
     }
   }
 
+  /**
+   * Recognises the opening {@code {bg:#rrggbb}} and {@code {bg:line:#rrggbb}}
+   * (the literal {@code line} selects {@link EPLBackgroundExtent#LINE_HEIGHT};
+   * absent defaults to {@link EPLBackgroundExtent#TIGHT}) plus the closing bare
+   * {@code {bg}}. Both shapes emit an {@link IPLMarkupToken.AnnotationToggle}
+   * carrying a {@link PLBackgroundAnnotation}. Open/close pairing is by
+   * ANNOTATION CLASS, not parameter — so two {@code {bg:#...}} with different
+   * colours do NOT nest; the second one simply closes the first. The closing
+   * bare {@code {bg}} carries a sentinel transparent color; the builder pops
+   * the annotation by type so the sentinel is never actually painted.
+   *
+   * @author Philip Helger
+   */
+  private static final class BackgroundFactory implements IPLMarkupCharacterFactory
+  {
+    /**
+     * Regex: <code>(?&lt;!\\)(\\\\)*\{bg(:(tight|line))?(:#(\p{XDigit}{6}))?\}</code>
+     * <ul>
+     * <li><code>(?&lt;!\\)(\\\\)*</code> — escape guard.</li>
+     * <li><code>\{bg</code> — literal <code>{bg</code>.</li>
+     * <li><code>(:(tight|line))?</code> — OPTIONAL extent suffix. group 3
+     * captures the extent literal. Absent defaults to
+     * {@link EPLBackgroundExtent#TIGHT}.</li>
+     * <li><code>(:#(\p{XDigit}{6}))?</code> — OPTIONAL colour. group 5 captures
+     * the six hex digits. Absent → CLOSING marker {@code {bg}}.</li>
+     * <li><code>\}</code> — literal <code>}</code>.</li>
+     * </ul>
+     */
+    private static final Pattern PATTERN = Pattern.compile ("(?<!\\\\)(\\\\\\\\)*\\{bg(:(tight|line))?(:#(\\p{XDigit}{6}))?\\}");
+    private static final String MARKER = "{";
+
+    @Override
+    @NonNull
+    public Pattern getPattern ()
+    {
+      return PATTERN;
+    }
+
+    @Override
+    @NonNull
+    public IPLMarkupToken createToken (@NonNull final String sText, @NonNull final Matcher aMatcher)
+    {
+      final String sExtent = aMatcher.group (3);
+      final EPLBackgroundExtent eExtent = "line".equals (sExtent) ? EPLBackgroundExtent.LINE_HEIGHT
+                                                                  : EPLBackgroundExtent.TIGHT;
+      final String sHex = aMatcher.group (5);
+      if (sHex == null)
+      {
+        // closing marker — emit a "neutral" toggle (matched by type)
+        return new IPLMarkupToken.AnnotationToggle (new PLBackgroundAnnotation (PLColor.BLACK, eExtent));
+      }
+      final int nR = Integer.parseUnsignedInt (sHex.substring (0, 2), 16);
+      final int nG = Integer.parseUnsignedInt (sHex.substring (2, 4), 16);
+      final int nB = Integer.parseUnsignedInt (sHex.substring (4, 6), 16);
+      return new IPLMarkupToken.AnnotationToggle (new PLBackgroundAnnotation (new PLColor (nR, nG, nB), eExtent));
+    }
+
+    @Override
+    @NonNull
+    public String unescape (@NonNull final String sText)
+    {
+      return sText.replaceAll ("\\\\" + Pattern.quote (MARKER), MARKER);
+    }
+  }
+
   /**
    * Recognises {@code {color_cmyk:C,M,Y,K}}. The four components are percent
    * values in {@code 0..100} (floats accepted). Like {@link ColorFactory} this
diff --git a/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/markup/PLMarkupParser.java b/ph-pdf-layout-richtext/src/main/java/com/helger/pdflayout/richtext/markup/PLMarkupParser.java
@@ -63,6 +63,7 @@ public final class PLMarkupParser
    * <li>COLOR (<code>{color:#xxxxxx}</code>)</li>
    * <li>HYPERLINK (<code>{link...}</code>)</li>
    * <li>ANCHOR (<code>{anchor:...}</code>)</li>
+   * <li>BACKGROUND (<code>{bg:#xxxxxx}...{bg}</code>)</li>
    * </ol>
    */
   public static final ICommonsList <IPLMarkupCharacterFactory> DEFAULT_FACTORIES = new CommonsArrayList <> (PLMarkupCharacters.HARD_BREAK,
@@ -75,7 +76,8 @@ public final class PLMarkupParser
                                                                                                             PLMarkupCharacters.ITALIC_UNDERSCORE,
                                                                                                             PLMarkupCharacters.COLOR,
                                                                                                             PLMarkupCharacters.HYPERLINK,
-                                                                                                            PLMarkupCharacters.ANCHOR);
+                                                                                                            PLMarkupCharacters.ANCHOR,
+                                                                                                            PLMarkupCharacters.BACKGROUND);
 
   private final ICommonsList <IPLMarkupCharacterFactory> m_aFactories;
 
diff --git a/ph-pdf-layout-richtext/src/test/java/com/helger/pdflayout/richtext/element/PLRichTextBackgroundTest.java b/ph-pdf-layout-richtext/src/test/java/com/helger/pdflayout/richtext/element/PLRichTextBackgroundTest.java
