Add some tests on TextRenderer extensions. Add appropriate documentation.

DEVSIX-5277

Author: ars18wrw

io/src/main/java/com/itextpdf/io/LogMessageConstant.java

@@ -82,6 +82,11 @@ public final class LogMessageConstant {
     public static final String COMB_FLAG_MAY_BE_SET_ONLY_IF_MAXLEN_IS_PRESENT = "The Comb flag may be set only if the MaxLen entry is present in the text field dictionary and if the Multiline, Password, and FileSelect flags are clear.";
     public static final String COULD_NOT_FIND_GLYPH_WITH_CODE = "Could not find glyph with the following code: {0}";
     public static final String CREATED_ROOT_TAG_HAS_MAPPING = "Created root tag has role mapping: \"/Document\" role{0} is mapped{1}. Resulting tag structure might have invalid root tag.";
+    public static final String CREATE_COPY_SHOULD_BE_OVERRIDDEN = "While processing an instance of TextRenderer, "
+            + "iText uses createCopy() to create glyph lines of specific fonts, which represent its parts. "
+            + "So if one extends TextRenderer, one should override createCopy, otherwise if FontSelector "
+            + "related logic is triggered, copies of this TextRenderer will have the default behavior "
+            + "rather than the custom one.";
     public static final String DESTINATION_NOT_PERMITTED_WHEN_ACTION_IS_SET = "Destinations are not permitted for link annotations that already have actions. The old action will be removed.";
     public static final String DIRECTONLY_OBJECT_CANNOT_BE_INDIRECT = "DirectOnly object cannot be indirect";
     public static final String DOCFONT_HAS_ILLEGAL_DIFFERENCES = "Document Font has illegal differences array. Entry {0} references a glyph ID over 255 and will be ignored.";

layout/src/main/java/com/itextpdf/layout/renderer/TextRenderer.java

@@ -1209,10 +1209,12 @@ public float getTabAnchorCharacterPosition() {
      * {@link #layout(LayoutContext)} is called more than once.
      *
      * <p>
-     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * If {@link TextRenderer} overflows to the next line, iText uses this method to create a renderer
      * for the overflow part. So if one wants to extend {@link TextRenderer}, one should override
      * this method: otherwise the default method will be used and thus the default rather than the custom
-     * renderer will be created.
+     * renderer will be created. Another method that should be overridden in case of
+     * {@TextRenderer}'s extension is {@link #createCopy(GlyphLine, PdfFont)}. This method is responsible
+     * for creation of {@TextRenderer}'s copies, which represent its parts of specific font.
      * @return new renderer instance
      */
     @Override
@@ -1591,7 +1593,24 @@ protected void setProcessedGlyphLineAndFont(GlyphLine gl, PdfFont font) {
         setProperty(Property.FONT, font);
     }
 
+    /**
+     * Creates a copy of this {@link TextRenderer}, which corresponds to the passed {@link GlyphLine}
+     * with {@link PdfFont}.
+     * <p>
+     * While processing {@link TextRenderer}, iText uses this method to create {@link GlyphLine glyph lines}
+     * of specific {@link PdfFont fonts}, which represent the {@link TextRenderer}'s parts. If one extends
+     * {@link TextRenderer}, one should override this method, otherwise if {@link com.itextpdf.layout.font.FontSelector}
+     * related logic is triggered, copies of this {@link TextRenderer} will have the default behavior rather than
+     * the custom one.
+     * @param gl a {@link GlyphLine} which represents some of this {@link TextRenderer}'s content
+     * @param font a {@link PdfFont} for this part of the {@link TextRenderer}'s content
+     * @return copy of this {@link TextRenderer}, which correspond to the passed {@link GlyphLine} with {@link PdfFont}
+     */
     protected TextRenderer createCopy(GlyphLine gl, PdfFont font) {
+        if (TextRenderer.class != this.getClass()) {
+            Logger logger = LoggerFactory.getLogger(TextRenderer.class);
+            logger.error(MessageFormatUtil.format(LogMessageConstant.CREATE_COPY_SHOULD_BE_OVERRIDDEN));
+        }
         TextRenderer copy = new TextRenderer(this);
         copy.setProcessedGlyphLineAndFont(gl, font);
         return copy;

layout/src/test/java/com/itextpdf/layout/renderer/TextRendererIntegrationTest.java

@@ -24,6 +24,7 @@ This file is part of the iText (R) project.
 
 import com.itextpdf.io.LogMessageConstant;
 import com.itextpdf.io.font.PdfEncodings;
+import com.itextpdf.io.font.otf.GlyphLine;
 import com.itextpdf.io.image.ImageDataFactory;
 import com.itextpdf.kernel.colors.ColorConstants;
 import com.itextpdf.kernel.font.PdfFont;
@@ -42,6 +43,7 @@ This file is part of the iText (R) project.
 import com.itextpdf.layout.element.Paragraph;
 import com.itextpdf.layout.element.Table;
 import com.itextpdf.layout.element.Text;
+import com.itextpdf.layout.font.FontProvider;
 import com.itextpdf.layout.property.FloatPropertyValue;
 import com.itextpdf.layout.property.OverflowPropertyValue;
 import com.itextpdf.layout.property.OverflowWrapPropertyValue;
@@ -54,6 +56,7 @@ This file is part of the iText (R) project.
 import com.itextpdf.test.annotations.LogMessages;
 import com.itextpdf.test.annotations.type.IntegrationTest;
 
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import org.junit.Assert;
 import org.junit.BeforeClass;
@@ -718,4 +721,139 @@ public void overflowWrapBreakWordWithOverflowXTest() throws IOException, Interru
         doc.close();
         Assert.assertNull(new CompareTool().compareByContent(outFileName, cmpFileName, destinationFolder));
     }
+
+    @Test
+    @LogMessages(messages = {
+            @LogMessage(messageTemplate = LogMessageConstant.GET_NEXT_RENDERER_SHOULD_BE_OVERRIDDEN, count = 3)
+    })
+    public void customTextRendererShouldOverrideGetNextRendererTest() throws IOException, InterruptedException {
+        String outFileName = destinationFolder + "customTextRendererShouldOverrideGetNextRendererTest.pdf";
+        String cmpFileName = sourceFolder + "cmp_customTextRendererShouldOverrideGetNextRendererTest.pdf";
+
+        PdfDocument pdfDoc = new PdfDocument(new PdfWriter(outFileName));
+        Document doc = new Document(pdfDoc);
+
+        Text text = new Text("If getNextRenderer() is not overridden and text overflows to the next line,"
+                + " then customizations are not applied. ");
+        text.setNextRenderer(new TextRenderer(text) {
+            @Override
+            public void draw(DrawContext drawContext) {
+                drawContext.getCanvas()
+                        .saveState()
+                        .setFillColor(ColorConstants.RED)
+                        .rectangle(occupiedArea.getBBox())
+                        .fill()
+                        .restoreState();
+                super.draw(drawContext);
+            }
+        });
+        doc.add(new Paragraph(text));
+
+        text = new Text("If getNextRenderer() is overridden and text overflows to the next line, "
+                + "then customizations are applied. ");
+        text.setNextRenderer(new TextRenderer(text) {
+            @Override
+            public void draw(DrawContext drawContext) {
+                drawContext.getCanvas()
+                        .saveState()
+                        .setFillColor(ColorConstants.RED)
+                        .rectangle(occupiedArea.getBBox())
+                        .fill()
+                        .restoreState();
+                super.draw(drawContext);
+            }
+
+            @Override
+            public IRenderer getNextRenderer() {
+                return new TextRendererWithOverriddenGetNextRenderer((Text) modelElement);
+            }
+        });
+        doc.add(new Paragraph(text));
+
+        doc.close();
+        Assert.assertNull(new CompareTool().compareByContent(outFileName, cmpFileName, destinationFolder));
+    }
+
+    @Test
+    @LogMessages(messages = {
+            @LogMessage(messageTemplate = LogMessageConstant.CREATE_COPY_SHOULD_BE_OVERRIDDEN, count = 8)
+    })
+    public void customTextRendererShouldOverrideCreateCopyTest() throws IOException, InterruptedException {
+        String outFileName = destinationFolder + "customTextRendererShouldOverrideCreateCopyTest.pdf";
+        String cmpFileName = sourceFolder + "cmp_customTextRendererShouldOverrideCreateCopyTest.pdf";
+
+        PdfDocument pdfDoc = new PdfDocument(new PdfWriter(outFileName));
+        Document doc = new Document(pdfDoc);
+
+        FontProvider fontProvider = new FontProvider();
+        Assert.assertTrue(fontProvider.addFont(fontsFolder + "NotoSans-Regular.ttf"));
+
+        doc.setFontProvider(fontProvider);
+        // To trigger font selector related logic one need to apply some font on a document
+        doc.setProperty(Property.FONT, new String[] {"SomeFont"});
+
+        StringBuilder longTextBuilder = new StringBuilder();
+        for (int i = 0; i < 4; i++) {
+            longTextBuilder.append("Дзень добры, свет! Hallo Welt! ");
+        }
+
+        Text text = new Text(longTextBuilder.toString());
+        text.setNextRenderer(new TextRenderer(text) {
+            @Override
+            public void draw(DrawContext drawContext) {
+                drawContext.getCanvas()
+                        .saveState()
+                        .setFillColor(ColorConstants.RED)
+                        .rectangle(occupiedArea.getBBox())
+                        .fill()
+                        .restoreState();
+                super.draw(drawContext);
+            }
+
+            @Override
+            public IRenderer getNextRenderer() {
+                return new TextRendererWithOverriddenGetNextRenderer((Text) modelElement);
+            }
+        });
+        doc.add(new Paragraph(text));
+
+        text.setNextRenderer(new TextRendererWithOverriddenGetNextRenderer(text));
+        doc.add(new Paragraph(text));
+
+        doc.close();
+        Assert.assertNull(new CompareTool().compareByContent(outFileName, cmpFileName, destinationFolder));
+    }
+
+    private static class TextRendererWithOverriddenGetNextRenderer extends TextRenderer {
+        public TextRendererWithOverriddenGetNextRenderer(Text textElement) {
+            super(textElement);
+        }
+
+        protected TextRendererWithOverriddenGetNextRenderer(TextRenderer other) {
+            super(other);
+        }
+
+        @Override
+        public void draw(DrawContext drawContext) {
+            drawContext.getCanvas()
+                    .saveState()
+                    .setFillColor(ColorConstants.RED)
+                    .rectangle(occupiedArea.getBBox())
+                    .fill()
+                    .restoreState();
+            super.draw(drawContext);
+        }
+
+        @Override
+        public IRenderer getNextRenderer() {
+            return new TextRendererWithOverriddenGetNextRenderer((Text) modelElement);
+        }
+
+        @Override
+        protected TextRenderer createCopy(GlyphLine gl, PdfFont font) {
+            TextRenderer copy = new TextRendererWithOverriddenGetNextRenderer(this);
+            copy.setProcessedGlyphLineAndFont(gl, font);
+            return copy;
+        }
+    }
 }