Add test for true type collection fonts, improve documentation

DEVSIX-8824

Author: Alexandr Pliushchou

io/src/main/java/com/itextpdf/io/font/FontProgramFactory.java

@@ -120,12 +120,7 @@ public static FontProgram createFont(String fontProgram, String cmap, boolean ca
     }
 
     /**
-     * Creates a new font program. This font program can be one of the 14 built in fonts,
-     * a Type1 font referred to by an AFM or PFM file, a TrueType font or
-     * a CJK font from the Adobe Asian Font Pack.
-     * Fonts in TrueType Collections are addressed by index such as "msgothic.ttc,1".
-     * This would get the second font (indexes start at 0), in this case "MS PGothic".
-     * <p>
+     * Creates a new font program.
      * The fonts are cached and if they already exist they are extracted from the cache,
      * not parsed again.
      * <p>
@@ -139,12 +134,7 @@ public static FontProgram createFont(byte[] fontProgram) throws java.io.IOExcept
     }
 
     /**
-     * Creates a new font program. This font program can be one of the 14 built in fonts,
-     * a Type 1 font referred to by an AFM or PFM file, a TrueType font or
-     * a CJK font from the Adobe Asian Font Pack.
-     * Fonts in TrueType Collections are addressed by index such as "msgothic.ttc,1".
-     * This would get the second font (indexes start at 0), in this case "MS PGothic".
-     * <p>
+     * Creates a new font program.
      * The fonts are cached and if they already exist they are extracted from the cache,
      * not parsed again.
      * <p>

layout/src/main/java/com/itextpdf/layout/font/FontProvider.java

@@ -157,8 +157,11 @@ public boolean addFont(FontProgram fontProgram) {
     /**
      * Add font to {@link FontSet} cache.
      *
-     * @param fontPath path to the font file to add. Can be a path to file or font name,
-     *                 see {@link FontProgramFactory#createFont(String)}.
+     * @param fontPath path to the font file to add. Can be a path to file or font name.
+     *                 As a font name one of 14 built in fonts can be used, see {@link StandardFonts}.
+     *                 If file is a true type collection, fonts in it should be addressed by index
+     *                 such as "msgothic.ttc,1", starting with index 0.
+     *                 See {@link FontProgramFactory#createFont(String)} for more information.
      * @param encoding font encoding to create {@link com.itextpdf.kernel.font.PdfFont}. Possible values for this
      *                 argument are the same as for {@link PdfFontFactory#createFont()} family of methods.
      * @param unicodeRange sets the specific range of characters to be used from the font.
@@ -172,8 +175,11 @@ public boolean addFont(String fontPath, String encoding, Range unicodeRange) {
     /**
      * Add font to {@link FontSet} cache.
      *
-     * @param fontPath path to the font file to add. Can be a path to file or font name,
-     *                 see {@link FontProgramFactory#createFont(String)}.
+     * @param fontPath path to the font file to add. Can be a path to file or font name.
+     *                 As a font name one of 14 built in fonts can be used, see {@link StandardFonts}.
+     *                 If file is a true type collection, fonts in it should be addressed by index
+     *                 such as "msgothic.ttc,1", starting with index 0.
+     *                 See {@link FontProgramFactory#createFont(String)} for more information.
      * @param encoding font encoding to create {@link com.itextpdf.kernel.font.PdfFont}. Possible values for this
      *                 argument are the same as for {@link PdfFontFactory#createFont()} family of methods.
      *
@@ -186,9 +192,11 @@ public boolean addFont(String fontPath, String encoding) {
     /**
      * Add font to {@link FontSet} cache.
      *
-     * @param fontPath path to the font file to add. Can be a path to file or font name,
-     *                 see {@link FontProgramFactory#createFont(String)}.
-     *
+     * @param fontPath path to the font file to add. Can be a path to file or font name.
+     *                 As a font name one of 14 built in fonts can be used, see {@link StandardFonts}.
+     *                 If file is a true type collection, fonts in it should be addressed by index
+     *                 such as "msgothic.ttc,1", starting with index 0.
+     *                 See {@link FontProgramFactory#createFont(String)} for more information.
      * @return true, if font was successfully added, otherwise false.
      */
     public boolean addFont(String fontPath) {

layout/src/test/java/com/itextpdf/layout/FontProviderTest.java

@@ -47,8 +47,7 @@ This file is part of the iText (R) project.
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Tag;
 
-import java.io.FileInputStream;
-import java.io.FileOutputStream;
+import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
@@ -180,7 +179,6 @@ public void customFontProvider2() throws Exception {
     public void fontProviderNotSetExceptionTest() throws Exception {
         String fileName = "fontProviderNotSetExceptionTest.pdf";
         String outFileName = destinationFolder + fileName + ".pdf";
-
         try (PdfDocument pdfDoc = new PdfDocument(new PdfWriter(FileUtil.getFileOutputStream(outFileName)))) {
             Document doc = new Document(pdfDoc);
 
@@ -191,4 +189,28 @@ public void fontProviderNotSetExceptionTest() throws Exception {
             Assertions.assertEquals(LayoutExceptionMessageConstant.FONT_PROVIDER_NOT_SET_FONT_FAMILY_NOT_RESOLVED, e.getMessage());
         }
     }
+
+    @Test
+    public void trueTypeCollectionTest() throws IOException, InterruptedException {
+        String fileName = "trueTypeCollectionFonts.pdf";
+        String outFileName = destinationFolder + fileName;
+        String cmpFileName = sourceFolder + "cmp_" + fileName;
+        PdfDocument pdfDoc = new PdfDocument(CompareTool.createTestPdfWriter(outFileName));
+        Document doc = new Document(pdfDoc);
+
+        FontProvider fontProvider = new FontProvider();
+        fontProvider.addFont(fontsFolder + "/NotoSansAndSpaceMono.ttc,0");
+        fontProvider.addFont(fontsFolder + "/NotoSansAndSpaceMono.ttc,1");
+        doc.setFontProvider(fontProvider);
+
+        Paragraph paragraph1 = new Paragraph("some test text here").setFontFamily("Noto Sans");
+        doc.add(paragraph1);
+
+        Paragraph paragraph2 = new Paragraph("and here should be different font").setFontFamily("Space Mono");
+        doc.add(paragraph2);
+
+        doc.close();
+
+        Assertions.assertNull(new CompareTool().compareByContent(outFileName, cmpFileName, destinationFolder, "diff" + fileName));
+    }
 }

layout/src/test/resources/com/itextpdf/layout/FontProviderTest/cmp_trueTypeCollectionFonts.pdf

@@ -16,6 +16,7 @@ Please notice that the following fonts are used with the mentioned below license
 * NotoKufiArabic-Regular.ttf - SIL Open Font License v1.1
 * SpaceMono-Regular - SIL Open Font License v1.1 - OFL.txt (29.04.2024)
 * Roboto-Regular - Apache License V 2.0
+* NotoSansAndSpaceMono - SIL Open Font License v1.1
 
 
 All the used bold Google Noto fonts have been taken from the https://github.com/googlefonts.