Text Element and Fonts |
The text element adds text to a PDF document and is implemented by the TextElement class. The TextElement offers many constructors that call the following constructor with default values:
public TextElement(float x, float y, float width, float height, string text, PdfFont font, PdfColor textColor);
The constructor creates a text element rendered in the specified rectangle with the specified font and color. The text is wrapped to the width of the rectangle.
If the text pagination is not allowed (the Paginate property of the TextElement is False), the text is written on the current page, and the rendered text height is the smaller of the specified height and the height available on the page. The text that did not fit and the text bounds inside the current page are returned in the AddTextElementResult object when the element is added to a renderer.
If the text pagination is allowed (the Paginate property is True, the default) and the text needs pagination (no height is specified, or the specified height is bigger than the space available on the page), the height is ignored and the text is rendered to its end on as many pages as it needs. The text bounds inside the last page and the last page index are returned in the AddTextElementResult object when the element is added to a renderer.
If the text pagination is allowed but the text does not need pagination (the specified height is less than the space available on the page), the rendered text is truncated to fit the specified height, and the text that did not fit is returned in RemainingText. On a page of a document loaded from an existing PDF, the text is drawn on that page only.
Constructor parameters:
x - The x coordinate where the text starts.
y - The y coordinate where the text starts.
width - The width of the destination rectangle.
height - The height of the destination rectangle.
text - The text to be rendered.
font - The text font.
textColor - The text color.
Other properties of the element set the alignment (TextAlign, VerticalTextAlign), the spacing (LineSpacing, CharacterSpacing, WordSpacing), the direction of the text (TextAngle, RightToLeftLanguage) and a clipping rectangle (ClipRectangle). In a text element added to a template, &p; is replaced with the page number and &P; with the number of pages (see Template Class).
A text element draws with a PdfFont added to the document with one of the AddFont overloads (or the same methods of Fonts):
An installed font - AddFont(Font) with an Font: a family name, a size in points and a FontStyle. The font is subset-embedded in the PDF, so the document shows the same text on every viewer and Unicode text of any script the font covers is written correctly. AddFont(Font, Boolean) accepts only true for its embed flag.
A font file - AddFont(String) with the path of a TrueType or OpenType file, embedded the same way. The font does not have to be installed.
A standard PDF font - AddFont(StdFontBaseFamily) with one of the 14 fonts every PDF viewer has (Helvetica, Times, Courier, Symbol, ZapfDingbats). They are not embedded, which keeps the document small, and they cover Western European text. In a PDF/A or PDF/X document, which requires embedded fonts, Helvetica, Times and Courier are drawn with the bundled Liberation fonts of the same metrics, embedded; Symbol and ZapfDingbats cannot be used there.
A standard CJK font - AddFont(StandardCJKFont) for Chinese, Japanese and Korean text, not embedded: the PDF viewer supplies the glyphs. For a PDF/A document use an installed CJK font or a CJK font file instead.
The Size, IsUnderline and IsStrikeout properties can be changed after the font is created, and GetTextWidth(String) measures a text.
An installed font is looked up among the fonts of the computer the application runs on, so the families available depend on the platform: Arial or SimSun are installed on Windows and usually not on Linux. The library bundles the Liberation Sans, Liberation Serif and Liberation Mono fonts, which have the metrics of Arial, Times New Roman and Courier New: when one of these three families (or Helvetica, Times, Courier) is not installed, its Liberation twin is used, so text in these fonts is laid out the same on every platform. Any other family that is not installed fails with a PdfDocumentException.
The Liberation fonts cover Latin, Greek and Cyrillic text. For other scripts on Linux and macOS servers without fonts, add the ExpertPdf.Anywhere.Fonts package (the Noto fonts for every script, CJK included) or install fonts on the server. Font files placed in a fonts folder beside the application are also available by their family names, on every platform. InstalledFamilies lists the families the library can use and IsFamilyInstalled(String) checks one.
Below there is a sample code showing how to add text and fonts to a PDF document:
// add a page to the PDF document PdfPage firstPage = document.AddPage(); // Times New Roman fonts of 10 points in four styles (Liberation Serif where Times // New Roman is not installed) Font ttfFont = new Font("Times New Roman", 10); Font ttfFontItalic = new Font("Times New Roman", 10, FontStyle.Italic); Font ttfFontBold = new Font("Times New Roman", 10, FontStyle.Bold); Font ttfFontBoldItalic = new Font("Times New Roman", 10, FontStyle.Bold | FontStyle.Italic); // a CJK font: SimSun on Windows; Noto Sans CJK SC comes with the // ExpertPdf.Anywhere.Fonts package on Linux and macOS string cjkFamily = SystemFonts.IsFamilyInstalled("SimSun") ? "SimSun" : "Noto Sans CJK SC"; Font ttfCJKFont = new Font(cjkFamily, 10); // the PDF fonts, embedded in the document PdfFont newTimesFont = document.AddFont(ttfFont); PdfFont newTimesFontItalic = document.AddFont(ttfFontItalic); PdfFont newTimesFontBold = document.AddFont(ttfFontBold); PdfFont newTimesFontBoldItalic = document.AddFont(ttfFontBoldItalic); PdfFont cjkEmbeddedFont = document.AddFont(ttfCJKFont); // standard Times Type 1 fonts, not embedded PdfFont stdTimesFont = document.AddFont(StdFontBaseFamily.TimesRoman); PdfFont stdTimesFontItalic = document.AddFont(StdFontBaseFamily.TimesItalic); PdfFont stdTimesFontBoldItalic = document.AddFont( StdFontBaseFamily.TimesBoldItalic); // standard CJK fonts, not embedded PdfFont cjkJapaneseStandardFont = document.AddFont( StandardCJKFont.HeiseiKakuGothicW5); PdfFont cjkChineseTraditionalStandardFont = document.AddFont( StandardCJKFont.MonotypeHeiMedium); // add text elements to the page TextElement trueTypeText = new TextElement(0, 10, "True Type Fonts Demo:", newTimesFontBold); AddElementResult addResult = firstPage.AddElement(trueTypeText); // the result of adding the element gives the rendered size in the PDF page TextElement textElement1 = new TextElement(20, addResult.EndPageBounds.Bottom + 10, "Hello World !!!!", newTimesFont); addResult = firstPage.AddElement(textElement1); // another element 5 points below the text above, in a bigger font newTimesFontItalic.Size = 15; TextElement textElement2 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "Hello World !!!!", newTimesFontItalic); textElement2.ForeColor = Color.Green; addResult = firstPage.AddElement(textElement2); newTimesFontBoldItalic.Size = 20; TextElement textElement3 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "Hello World !!!!", newTimesFontBoldItalic); textElement3.ForeColor = Color.Blue; addResult = firstPage.AddElement(textElement3); TextElement stdTypeText = new TextElement(0, addResult.EndPageBounds.Bottom + 10, "Standard PDF Fonts Demo:", newTimesFontBold); addResult = firstPage.AddElement(stdTypeText); TextElement textElement4 = new TextElement(20, addResult.EndPageBounds.Bottom + 10, "Hello World !!!!", stdTimesFont); addResult = firstPage.AddElement(textElement4); stdTimesFontItalic.Size = 15; TextElement textElement5 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "Hello World !!!!", stdTimesFontItalic); textElement5.ForeColor = Color.Green; addResult = firstPage.AddElement(textElement5); stdTimesFontBoldItalic.Size = 20; TextElement textElement6 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "Hello World !!!!", stdTimesFontBoldItalic); textElement6.ForeColor = Color.Blue; addResult = firstPage.AddElement(textElement6); // Unicode text with the embedded fonts TextElement unicodeText = new TextElement(0, addResult.EndPageBounds.Bottom + 10, "Unicode Text Demo:", newTimesFontBold); addResult = firstPage.AddElement(unicodeText); // Russian text newTimesFont.Size = 15; TextElement textElement8 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "Появление на свет!!", newTimesFont); addResult = firstPage.AddElement(textElement8); // Japanese text TextElement textElementJapanese = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "こんにちは世界!", cjkEmbeddedFont); addResult = firstPage.AddElement(textElementJapanese); // Chinese text TextElement textElementChinese = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "你好世界!", cjkEmbeddedFont); addResult = firstPage.AddElement(textElementChinese); TextElement stdCJKText = new TextElement(0, addResult.EndPageBounds.Bottom + 10, "Standard CJK Fonts Demo:", newTimesFontBold); addResult = firstPage.AddElement(stdCJKText); // Hello World in Japanese TextElement textElement10 = new TextElement(20, addResult.EndPageBounds.Bottom + 20, "こんにちは世界!", cjkJapaneseStandardFont); addResult = firstPage.AddElement(textElement10); // Hello World in Chinese Traditional TextElement textElement11 = new TextElement(20, addResult.EndPageBounds.Bottom + 5, "你好世界!", cjkChineseTraditionalStandardFont); addResult = firstPage.AddElement(textElement11);