This section covers the following topics:
All text drawing operations of PDF Graphics .NET require fonts. A font contains all the information needed to render letters, markup and other tokens for a given type, such as Times New Roman. PDF Graphics .NET uses the font information stored in the system; if you have installed a font, it will be available to draw text onto a PDF page.
To write text onto a page, you need to create an instance of the Font class. Its constructor accepts the name of a type, which must be that type's full name. That means that in order to write bold-face text in Times New Roman, you need a Font instance for "Times New Roman Bold". If the font does not exist in the system, an exception is raised. The following are all examples of font instances:
A Font instance is not tied to the current page, or even a Graphics instance. You can use the same instance on multiple pages, and across Graphics instances.
The Graphics class provides a number of methods for drawing text. In its simplest form, the overloaded DrawString() method accepts a brush, font and size, and the (x,y) coordinates to start drawing at.
This draws the text "The quick brown fox...", with the top-left hand corner at the point (20, 20). The text is drawn at 12 points size. The size parameter is always expressed in points, no matter what the current page unit is.
In this simple form, text is drawn on a single line and does not wrap. If the text is too long to fit on the page, it is clipped, as can be seen in the following example:
Another overload of DrawString() accepts a Rectangle instance to be used as the bounding box of the text. The text will now wrap and continue onto subsequent lines, provided there is enough space in the bounding box to fit all the lines. Lines that do not fit are not drawn at all. The code below illustrates this:
Note: If the bounding box does not fit onto the page, the text will of course still be clipped.
So far, we have drawn text without specifying formatting details. PDF Graphics .NET provides a number of formatting options through the StringFormat class and an overload of DrawString() that accepts a StringFormat instance. These options control the alignment of text, as well as various types of spacing. The formatting options are only available when drawing text inside a bounding box.
Character spacing is controlled through the CharacterSpacing property of the StringFormat class. By default, character spacing is set to 0. Positive and negative values are allowed. Character spacing is measured in points, regardless of the page unit.
| Character spacing | |
|---|---|
 |
 |
| Default character spacing | 2 points spacing |
Word spacing is controlled through the WordSpacing property of the StringFormat class. By default, word spacing is set to 0. Positive and negative values are allowed. Word spacing is measured in points, regardless of the page unit.
| Word spacing | |
|---|---|
|
 |
| Default word spacing | 4 points spacing |
Line spacing is controlled through the LineSpacing property of the StringFormat class. By default, line spacing is set to 0. Positive and negative values are allowed. Line spacing is measured in points, regardless of the page unit.
| Line spacing | |
|---|---|
|
 |
| Default line spacing | 3 points spacing |
Text ratio is controlled through the TextRatio property of the StringFormat class. By default, text ratio is set to 1. A value of 0.5 narrows text to 50%. A value of 2 doubles the width of text. Negative values are not allowed.
| Text ratio | |
|---|---|
|
 |
| Default ratio | 0.7 ratio |
Vertical alignment is controlled through the VerticalAlignment property of the StringFormat class. Text can be aligned to the top of the bounding box (the top of the first line will be equal to the top of the bounding box) or to the bottom (the bottom of the last line will be aligned to the bottom of the bounding box), or centered within the bounding box. By default, text is aligned to the top of the bounding box.
| Vertical alignment | ||
|---|---|---|
|
 |
 |
| VerticalAlignment.Top | VerticalAlignment.Center | VerticalAlignment.Bottom |
Horizontal alignment is controlled through the HorizontalAlignment property of the StringFormat class. Text can be aligned to the left or right side of the bounding box, or centered within the box, or fully justified. Fully justified text spans the width of the bounding box. This implies that on each line, word spacing is adjusted to make the text fill the entire width. This overrules the word spacing currently in effect. By default, text is left-aligned.
| Horizontal alignment | |||
|---|---|---|---|
|
 |
 |
 |
| HorizontalAlignment.Left | HorizontalAlignment.Center | HorizontalAlignment.Right | HorizontalAlignment.FullyJustified |
In all the examples above, text was written in a single font. While this is sufficient in most cases, sometimes a piece of text requires multiple font styles (bold, or italic) or even different font types. PDF Graphics .NET supports this in the form of the DrawStyledText() method in conjunction with the StyledText class.
The StyledText class is composed of one or more text elements, each with its own style. The elements are represented by instances of the InlineText class, which encapsulates a brush, font and font size, together with the text to draw in that style. Text elements are added to a StyledText instance by calling its Append() method with an InlineText argument. Alternatively, specify the style properties directly using an overload of Append().
To draw styled text, create a new instance of StyledText and add text sections to it using one of its Append() method overloads. Alternatively, you can use one of the overloaded constructors of StyledText and specify text sections directly. Finally, call DrawStyledText() on the Graphics object to place the styled text. All of the example below have the same result:
The Append() methods return a reference to the StyledText instance, so you can daisy-chain the calls. The following example produces the same output as the ones above:
Note: In the examples above, the first and last text elements include a space at their end and start, respectively. Although the InlineText elements seem to work like words in a sentence, the spaces are essential. Without them, the text elements would be joined together, as in the following example:
The height of a line of text is determined by the size of the text. When text is composed of multiple fonts, line height is based on the tallest font. This takes into account the sizes of fonts used in InlineText elements as well as some font metrics, such as the 'descent' figure. In the example below, one of the lines is moved down to accommodate the larger font used in some of the text.
Because PDF was designed to allow portable documents, the specification provides document creators with a degree of control over the handling of fonts. A PDF document may contain copies of the fonts used on its pages, or it can rely on system-installed versions. For a handful of standard fonts, such as Times New Roman, it is safe to assume a font exists on target systems. For other fonts, however, embedding the font inside the document guarantees that the document retains fidelity.
PDF Graphics .NET library embeds fonts by default, except for the 'stock' fonts guaranteed by Adobe to be rendered correctly. However, if for some reason you are using a font that cannot be embedded (it may be too large to include in your document, or licence restrictions prevent you from spreading it), the Font class provides an option to disable the embedding. The following code creates a font that will not be embedded in the PDF document:
This means that the PDF document will not render accurately; that is, the PDF reader (such as Adobe Acrobat Reader) will render the text in a standard font. However, PDF Graphics .NET will provide the PDF document with character spacing information so that the text is rendered in the same size as the original, and no text will be clipped or appear out of place.