Introduce #setFontFamily methods for setting preferred font families on elements

New setFontFamily methods replace the older setFont(String)
method (which is deprecated now). The older method took a
single String which was later processed by FontFamilySplitter.
Some of the symbols in contents of this String argument were
treated in a special way (like commas and quotes), also
font family names with non-latin letters were previously
ignored. New setFontFamily methods accept an array or list
of Strings where every string is treated directly as
desired font family name (without any preprocessing:
all symbols are treated as a part of font-family name).

DEVSIX-2525

Autoported commit.
Original commit hash: [7c42087a0]
Manual files:
layout/src/main/java/com/itextpdf/layout/font/FontFamilySplitter.java

Author: yulian-gaponenko

itext.tests/itext.layout.tests/itext/layout/BlockTest.cs

@@ -901,7 +901,7 @@ public virtual void ParagraphVerticalAlignmentTest01() {
             doc.SetFontProvider(fontProvider);
             String loremIpsum = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
             doc.Add(new Paragraph(loremIpsum).SetHeight(100).SetVerticalAlignment(VerticalAlignment.MIDDLE).SetBorder(
-                new SolidBorder(3)).SetFont(StandardFonts.TIMES_ROMAN));
+                new SolidBorder(3)).SetFontFamily(StandardFonts.TIMES_ROMAN));
             doc.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
                 , "diff"));

itext.tests/itext.layout.tests/itext/layout/FontProviderTest.cs

@@ -104,14 +104,13 @@ public virtual void StandardAndType3Fonts() {
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
             Paragraph paragraph = new Paragraph("Next paragraph contains a triangle, actually Type 3 Font");
-            paragraph.SetProperty(Property.FONT, StandardFontFamilies.TIMES);
-            // TODO DEVSIX-2136 Update of necessary
+            paragraph.SetProperty(Property.FONT, new String[] { StandardFontFamilies.TIMES });
             doc.Add(paragraph);
             paragraph = new Paragraph("A");
-            paragraph.SetFont("CustomFont");
+            paragraph.SetFontFamily("CustomFont");
             doc.Add(paragraph);
             paragraph = new Paragraph("Next paragraph");
-            paragraph.SetProperty(Property.FONT, StandardFonts.COURIER);
+            paragraph.SetProperty(Property.FONT, new String[] { StandardFonts.COURIER });
             doc.Add(paragraph);
             doc.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
@@ -133,8 +132,8 @@ public virtual void CustomFontProvider() {
             doc.SetFontProvider(fontProvider);
             Paragraph paragraph1 = new Paragraph("Default Helvetica should be selected.");
             doc.Add(paragraph1);
-            Paragraph paragraph2 = new Paragraph("Default Helvetica should be selected.").SetFont(StandardFonts.COURIER
-                );
+            Paragraph paragraph2 = new Paragraph("Default Helvetica should be selected.").SetFontFamily(StandardFonts.
+                COURIER);
             doc.Add(paragraph2);
             doc.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
@@ -160,7 +159,7 @@ public virtual void CustomFontProvider2() {
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(fontProvider);
             Paragraph paragraph = new Paragraph("There is no default font (Helvetica) inside the used FontProvider's instance. So the first font, that has been added, should be selected. Here it's FreeSans."
-                ).SetFont("ABRACADABRA_THERE_IS_NO_SUCH_FONT");
+                ).SetFontFamily("ABRACADABRA_THERE_IS_NO_SUCH_FONT");
             doc.Add(paragraph);
             doc.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder

itext.tests/itext.layout.tests/itext/layout/FontSelectorTest.cs

@@ -45,7 +45,9 @@ source product.
 using System.IO;
 using iText.IO.Font;
 using iText.IO.Font.Constants;
+using iText.IO.Util;
 using iText.Kernel.Colors;
+using iText.Kernel.Font;
 using iText.Kernel.Pdf;
 using iText.Kernel.Utils;
 using iText.Layout.Element;
@@ -84,7 +86,7 @@ public virtual void CyrillicAndLatinGroup() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetProperty(Property.FONT, "Puritan42");
+            doc.SetProperty(Property.FONT, new String[] { "Puritan42" });
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);
@@ -108,8 +110,7 @@ public virtual void CyrillicAndLatinGroup2() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetFont("'Puritan', \"FreeSans\"");
-            // TODO DEVSIX-2120 font-family is Puritan 2.0 here, however it doesn't match font-family pattern
+            doc.SetFontFamily("Puritan 2.0", "FreeSans");
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);
@@ -130,7 +131,7 @@ public virtual void LatinAndNotdefGroup() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetFont("Puritan");
+            doc.SetFontFamily("Puritan 2.0");
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);
@@ -154,7 +155,7 @@ public virtual void CustomFontWeight() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            Div div = new Div().SetFont(StandardFonts.TIMES_ROMAN);
+            Div div = new Div().SetFontFamily(StandardFonts.TIMES_ROMAN);
             Paragraph paragraph = new Paragraph("Times Roman Bold text");
             paragraph.SetProperty(Property.FONT_WEIGHT, "bold");
             div.Add(paragraph);
@@ -180,8 +181,7 @@ public virtual void CustomFontWeight2() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            Div div = new Div().SetFont(StandardFontFamilies.TIMES);
-            // TODO DEVSIX-2136 Update of necessary
+            Div div = new Div().SetFontFamily(StandardFontFamilies.TIMES);
             Paragraph paragraph = new Paragraph("Times Roman Bold text");
             paragraph.SetProperty(Property.FONT_WEIGHT, "bold");
             div.Add(paragraph);
@@ -206,8 +206,7 @@ public virtual void CustomFontWeight3() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            Div div = new Div().SetFont(StandardFontFamilies.TIMES);
-            // TODO DEVSIX-2136 Update of necessary
+            Div div = new Div().SetFontFamily(StandardFontFamilies.TIMES);
             Paragraph paragraph = new Paragraph("Times Roman Bold text");
             paragraph.SetProperty(Property.FONT_WEIGHT, "bold");
             div.Add(paragraph);
@@ -230,10 +229,10 @@ public virtual void StandardPdfFonts() {
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
             Paragraph paragraph = new Paragraph(s);
-            paragraph.SetFont("Courier");
+            paragraph.SetFontFamily("Courier");
             doc.Add(paragraph);
             paragraph = new Paragraph(s);
-            paragraph.SetProperty(Property.FONT, "Times");
+            paragraph.SetProperty(Property.FONT, new String[] { "Times" });
             doc.Add(paragraph);
             doc.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
@@ -306,6 +305,63 @@ public virtual void SearchNames2() {
             NUnit.Framework.Assert.IsTrue(GetFirst(sel.GetFontSet().Get("puritan42")) == null, "Puritan42 found!");
         }
 
+        [NUnit.Framework.Test]
+        public virtual void SearchFontAliasWithUnicodeChars() {
+            String cyrillicAlias = "\u0444\u043E\u043D\u04421";
+            // фонт1
+            String greekAlias = "\u03B3\u03C1\u03B1\u03BC\u03BC\u03B1\u03C4\u03BF\u03C3\u03B5\u03B9\u03C1\u03AC2";
+            // γραμματοσειρά2
+            String japaneseAlias = "\u30D5\u30A9\u30F3\u30C83";
+            // フォント3
+            IDictionary<String, String> aliasToFontName = new LinkedDictionary<String, String>();
+            aliasToFontName.Put(cyrillicAlias, "NotoSans-Regular.ttf");
+            aliasToFontName.Put(greekAlias, "FreeSans.ttf");
+            aliasToFontName.Put(japaneseAlias, "Puritan2.otf");
+            FontProvider provider = new FontProvider();
+            foreach (KeyValuePair<String, String> e in aliasToFontName) {
+                provider.GetFontSet().AddFont(fontsFolder + e.Value, PdfEncodings.IDENTITY_H, e.Key);
+            }
+            ICollection<String> actualAliases = new HashSet<String>();
+            foreach (FontInfo fontInfo in provider.GetFontSet().GetFonts()) {
+                actualAliases.Add(fontInfo.GetAlias());
+            }
+            ICollection<String> expectedAliases = aliasToFontName.Keys;
+            NUnit.Framework.Assert.IsTrue(actualAliases.ContainsAll(expectedAliases) && expectedAliases.ContainsAll(actualAliases
+                ));
+            foreach (String fontAlias in expectedAliases) {
+                PdfFont pdfFont = provider.GetPdfFont(provider.GetFontSelector(JavaCollectionsUtil.SingletonList(fontAlias
+                    ), new FontCharacteristics()).BestMatch());
+                String fontName = pdfFont.GetFontProgram().GetFontNames().GetFontName();
+                NUnit.Framework.Assert.IsTrue(aliasToFontName.Get(fontAlias).Contains(fontName));
+            }
+        }
+
+        /// <exception cref="System.IO.IOException"/>
+        /// <exception cref="System.Exception"/>
+        [NUnit.Framework.Test]
+        public virtual void WriteTextInFontWhichAliasWithUnicodeChars() {
+            String fileName = "writeTextInFontWhichAliasWithUnicodeChars";
+            String outFileName = destinationFolder + fileName + ".pdf";
+            String cmpFileName = sourceFolder + "cmp_" + fileName + ".pdf";
+            String japaneseAlias = "\u30D5\u30A9\u30F3\u30C83";
+            // フォント3
+            FontProvider provider = new FontProvider();
+            provider.AddFont(fontsFolder + "NotoSans-Regular.ttf");
+            provider.GetFontSet().AddFont(fontsFolder + "Puritan2.otf", PdfEncodings.IDENTITY_H, japaneseAlias);
+            provider.AddFont(fontsFolder + "FreeSans.ttf");
+            String s = "Hello world!";
+            PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
+            Document doc = new Document(pdfDoc);
+            doc.SetFontProvider(provider);
+            Paragraph paragraph = new Paragraph(new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY));
+            paragraph.SetFontFamily(japaneseAlias);
+            doc.Add(paragraph);
+            doc.Close();
+            // Text shall be written in Puritan 2.0
+            NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
+                ));
+        }
+
         /// <exception cref="System.Exception"/>
         [NUnit.Framework.Test]
         public virtual void CyrillicAndLatinWithUnicodeRange() {
@@ -322,7 +378,7 @@ public virtual void CyrillicAndLatinWithUnicodeRange() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetProperty(Property.FONT, "FontAlias");
+            doc.SetProperty(Property.FONT, new String[] { "FontAlias" });
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);
@@ -348,7 +404,7 @@ public virtual void DuplicateFontWithUnicodeRange() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetProperty(Property.FONT, "FontAlias");
+            doc.SetProperty(Property.FONT, new String[] { "FontAlias" });
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);
@@ -374,7 +430,7 @@ public virtual void SingleFontWithUnicodeRange() {
             PdfDocument pdfDoc = new PdfDocument(new PdfWriter(new FileStream(outFileName, FileMode.Create)));
             Document doc = new Document(pdfDoc);
             doc.SetFontProvider(sel);
-            doc.SetProperty(Property.FONT, "FontAlias");
+            doc.SetProperty(Property.FONT, new String[] { "FontAlias" });
             Text text = new Text(s).SetBackgroundColor(ColorConstants.LIGHT_GRAY);
             Paragraph paragraph = new Paragraph(text);
             doc.Add(paragraph);

itext.tests/itext.layout.tests/itext/layout/NonBreakingHyphenTest.cs

@@ -85,36 +85,36 @@ public virtual void NonBreakingHyphenDifferentFonts() {
             document.Add(new Paragraph("StandardFonts - non-breaking hyphen \\u2011").SetUnderline().SetTextAlignment(
                 TextAlignment.CENTER));
             document.Add(new Paragraph("for Standard font TIMES_ROMAN: <&#8209;> non-breaking hyphen <\u2011> 2 hyphens<\u2011\u2011>here "
-                ).SetFont(StandardFonts.TIMES_ROMAN));
+                ).SetFontFamily(StandardFonts.TIMES_ROMAN));
             document.Add(new Paragraph("for Standard font COURIER: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
-                ).SetFont(StandardFonts.COURIER));
+                ).SetFontFamily(StandardFonts.COURIER));
             document.Add(new Paragraph("for Standard font HELVETICA_BOLD: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
                 ).SetFont(PdfFontFactory.CreateFont(StandardFonts.HELVETICA_BOLD)));
             document.Add(new Paragraph("for Standard font SYMBOL: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
                 ).SetFont(PdfFontFactory.CreateFont(StandardFonts.SYMBOL)));
             document.Add(new Paragraph("Non-Standard fonts - non-breaking hyphen \\u2011").SetUnderline().SetTextAlignment
                 (TextAlignment.CENTER));
-            document.Add(new Paragraph("for NotoSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFont("NotoSans"
-                ));
-            document.Add(new Paragraph("for Puritan2: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFont("Puritan2"
-                ));
+            document.Add(new Paragraph("for NotoSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFontFamily
+                ("NotoSans"));
+            document.Add(new Paragraph("for Puritan2: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFontFamily
+                ("Puritan2"));
             sel.GetFontSet().AddFont(fontsFolder + "FreeSans.ttf", PdfEncodings.IDENTITY_H, "FreeSans");
             document.Add(new Paragraph("AFTER adding of FreeSans font with non-breaking hyphen \\u2011 support").SetUnderline
                 ().SetTextAlignment(TextAlignment.CENTER));
             document.Add(new Paragraph("for Standard font TIMES_ROMAN: <&#8209;> non-breaking hyphen <\u2011> 2 hyphens<\u2011\u2011>here "
-                ).SetFont(StandardFonts.TIMES_ROMAN));
+                ).SetFontFamily(StandardFonts.TIMES_ROMAN));
             document.Add(new Paragraph("for Standard font COURIER: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
-                ).SetFont(StandardFonts.COURIER));
+                ).SetFontFamily(StandardFonts.COURIER));
             document.Add(new Paragraph("for Standard font HELVETICA_BOLD: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
                 ).SetFont(PdfFontFactory.CreateFont(StandardFonts.HELVETICA_BOLD)));
             document.Add(new Paragraph("for Standard font SYMBOL: <&#8209;> non-breaking hyphen<\u2011> 2hyphens <\u2011\u2011>here "
                 ).SetFont(PdfFontFactory.CreateFont(StandardFonts.SYMBOL)));
-            document.Add(new Paragraph("for FreeSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFont("FreeSans"
-                ));
-            document.Add(new Paragraph("for NotoSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFont("NotoSans"
-                ));
-            document.Add(new Paragraph("for Puritan2: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFont("Puritan2"
-                ));
+            document.Add(new Paragraph("for FreeSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFontFamily
+                ("FreeSans"));
+            document.Add(new Paragraph("for NotoSans: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFontFamily
+                ("NotoSans"));
+            document.Add(new Paragraph("for Puritan2: <&#8209;> hyphen<\u2011> 2hyphens <\u2011\u2011>here").SetFontFamily
+                ("Puritan2"));
             document.Close();
             NUnit.Framework.Assert.IsNull(new CompareTool().CompareByContent(outFileName, cmpFileName, destinationFolder
                 , diffPrefix));

itext.tests/itext.layout.tests/itext/layout/renderer/TextRendererTest.cs

@@ -81,7 +81,7 @@ public virtual void SetTextException() {
             FontProvider fp = new FontProvider();
             fp.AddFont(fontName);
             rend.SetProperty(Property.FONT_PROVIDER, fp);
-            rend.SetProperty(Property.FONT, fontName);
+            rend.SetProperty(Property.FONT, new String[] { fontName });
             rend.SetText(val);
             NUnit.Framework.Assert.AreEqual(val, rend.GetText().ToString());
         }
@@ -104,7 +104,7 @@ public virtual void SetFontAsText() {
             FontProvider fp = new FontProvider();
             fp.AddFont("Helvetica");
             txt.SetProperty(Property.FONT_PROVIDER, fp);
-            txt.SetFont("Helvetica");
+            txt.SetFontFamily("Helvetica");
             doc.Add(new Paragraph().Add(txt));
             doc.Close();
         }

itext.tests/itext.layout.tests/resources/itext/layout/FontSelectorTest/cmp_cyrillicAndLatinGroup2.pdf

@@ -133,7 +133,9 @@ public const String ENCRYPTED_PAYLOAD_FILE_SPEC_SHALL_HAVE_AFRELATIONSHIP_FILED_
 
         public const String FONT_HAS_INVALID_GLYPH = "Font {0} has invalid glyph: {1}";
 
-        public const String FONT_PROPERTY_MUST_BE_PDF_FONT_OBJECT = "The Font Property must be a PdfFont object";
+        public const String FONT_PROPERTY_MUST_BE_PDF_FONT_OBJECT = "The \"Property.FONT\" property must be a PdfFont object in this context.";
+
+        public const String FONT_PROPERTY_OF_STRING_TYPE_IS_DEPRECATED_USE_STRINGS_ARRAY_INSTEAD = "The \"Property.FONT\" property with values of String type is deprecated, use String[] as property value type instead.";
 
         public const String FONT_SUBSET_ISSUE = "Font subset issue. Full font will be embedded.";