# Tutorial: iText by Example

## Font characteristics

Width and heigths of glyphs:
When getting a font from the FontFactory or when constructing a Font directly, you always specify a font size. This size is an indication of the height of the glyphs in points. It doesn't tell you how height each glyph will be and it doesn't tell you anything about the width.
The width and heights of each glyph are defined in the font file. If you need to fit some text into a certain area, you may want to know the width and height of some textstring in advance. You can ask the width from class Chunk, but you can also ask a basefont for its dimensions, using BaseFont.getWidthPoint(java.lang.String, float), BaseFont.getAscentPoint(java.lang.String, float) and getDescentPoint(java.lang.String, float).
Text is written on a 'baseline'. The ascent is the maximum height above reached by the glyphs in your text above this baseline. It is always a positive value. The descent is the maximum depth below the baseline. It is always a negative value. The height of your text is (ascent - descent). Take a look at the example below to see how the basic methods work and check the API if you need some more methods to get widths, ascents and descents.
Example: java com.lowagie.examples.fonts.styles.WidthHeight
Asking a font for the width/height of a textstring: see widthheight.pdf
In some cases you may want full control over the width of each glyph. No problem, just use BaseFont.getWidths(), change the widths and and force the basefont to use these changed widths with BaseFont.setForceWidthsOutput(boolean).
Example: java com.lowagie.examples.fonts.styles.FixedFontWidth
Changing the width of the font glyphs: see fixedfontwidth.pdf
Go to top of the page
Font Styles:
Fonts that don't have the style bold and/or italic
Some font families don't have font definitions to show the font in bold or italic. In this case, iText can simulate a bold font by changing the way glyphs are rendered (see Stroking vs. Filling). Italic can be simulated by skewing chunks.
Font Style Propagation
There are some rules you should know about 'font propagation'.
When you create a Phrase or a Paragraph with some content in a certain font (NOT THE DEFAULT FONT) and you add some more content. The fontstyle of the initial object can be propagated if you want to. This is what happens in 'Hello 1!' and 'Hello 2' of the example.

    Phrase myPhrase =
      new Phrase("Hello 1! ",
        new Font(Font.TIMES_ROMAN, 8, Font.BOLD));
    myPhrase.add(
      new Phrase("some other font ",
        new Font(Font.HELVETICA, 8)));
    myPhrase.add(
      new Phrase("This is the end of the sentence.\n",
        new Font(Font.TIMES_ROMAN, 8, Font.ITALIC)));

The initial Phrase with the text 'Hello 1!' was bold, some italic text was added, but style bold is propagated, so the style of the printed text is now bold and italic.
If the Font(style) of the initial Phrase is undefined, the font is not propagated:

    myPhrase = new Phrase(12);
    myPhrase.add(
      new Phrase("Hello 2! ",
        new Font(Font.TIMES_ROMAN, 8, Font.BOLD)));
    myPhrase.add(
      new Phrase("This is the end of the sentence.\n",
        new Font(Font.TIMES_ROMAN, 8, Font.ITALIC)));

As you can see, 'This is the end of the sentence' is italic, but not bold. The font wasn't propagated. The same applies if you use FontFactory to get the Font-object. This is because the FontFactory uses another technique to construct a font.

    myPhrase =
      new Phrase("Hello 3! ",
        FontFactory.getFont(FontFactory.TIMES_ROMAN, 8, Font.BOLD));
    myPhrase.add(
      new Phrase("some other font ",
        FontFactory.getFont(FontFactory.HELVETICA, 8)));
    myPhrase.add(
      new Phrase("This is the end of the sentence.\n",
        FontFactory.getFont(FontFactory.TIMES_ROMAN, 8, Font.ITALIC)));

As mentioned earlier: FontFactory is the safest way to get a Font. It will always give you the font style you are expecting, regardless of the font style that was used before. Font Propagation can be useful in some cases, but it's a rather quirky feature.
Example: java com.lowagie.examples.fonts.styles.FontStylePropagation
Explains the mechanism of Font Style Propagation: see FontStylePropagation.pdf
Underline and strike through
Allthough underlining and striking through text isn't really font-related, both 'style-types' are added to the Font-class: Font.UNDERLINE and Font.STRIKETHRU. In the example, we generate PDF, RTF and HTML. If however, you only need to generate PDF, it is much better to use Chunk-functionality. Font.UNDERLINE and Font.STRIKETHRU use some default values of this functionality. If you want complete control over the height, width, color,... of the line, you should use the method Chunk.setUnderline as described in the chapter on Chunks.
Example: java com.lowagie.examples.fonts.styles.ExtraStyles
Demonstrates how to underline or strike through text: see ExtraStyles.pdf ExtraStyles.rtf ExtraStyles.html
Font Color
If you want to change the font color, just ask the FontFactory for another font with the color of your choice:

    font red =
      FontFactory.getFont(
        FontFactory.COURIER,
        Font.DEFAULTSIZE,
        Font.NORMAL,
        new Color(0xFF, 0x00, 0x00));

It's a little more complicated if you want to change the color of some text you want to add at an absolute position. As you can read in the Text State chapter, you have to use class BaseFont and this class doesn't have a color value. In this case, you have to know that, according to the PDF specs, characters are seen as 'shapes'. Those shapes are filled with a certain color. So if you want to change the color of the font, you need to change the color with the 'ColorFill' of your choice in PdfContentByte:

    BaseFont bf =
      FontFactory.getFont(FontFactory.COURIER).getCalculatedBaseFont();
    cb.beginText();
    cb.setRGBColorFill(new Color(0x00, 0x00, 0xFF));
    cb.setFontAndSize(bf, 12);
    cb.showTextAligned(PdfContentByte.ALIGN_CENTER, text + "This text is centered", 250, 700, 0);
    cb.endText();

Example: java com.lowagie.examples.fonts.styles.FontColor
Shows how to change the color of a font: see FontColor.pdf
Go to top of the page
Direction:
When adding objects to a document, iText always writes text from left to right by default. Of course there are languages that are written in another direction. Arabic and Hebrew for instance are written from right to left. Most Asian characters should be written vertically. Japanese for instance, is written in columns starting on the right top of a page.
Changing the run direction
There are two objects in iText that allow you to change the run direction of the text: tables and columns. Both objects have a method (ColumnText.setRunDirection(int) and PdfPTable.setRunDirection(int)) to change the run direction to one of the following values:

- PdfWriter.RUN_DIRECTION_DEFAULT: the default run direction
- PdfWriter.RUN_DIRECTION_NO_BIDI: do not use bidirectional reordering
- PdfWriter.RUN_DIRECTION_LTR: use bidirectional reordering with left-to-right preferential run direction.
- PdfWriter.RUN_DIRECTION_RTL: use bidirectional reordering with right-to-left preferential run direction.

In the following example, the use of NO_BIDI and RTL is demonstrated with ColumnText (first page) and PdfPTable (second page).
Example: java com.lowagie.examples.fonts.styles.RightToLeft
Writing text from left to right: see righttoleft.pdf
If you're adding RTL text at absolute positions, you should always use a ColumnText object. In the next example, some RTL text is added with a rotation of 20 degrees.
Example: java com.lowagie.examples.fonts.styles.ComplexText
Writing text from left to right at absolute positions: see complextext.pdf
Vertical text
If you want to add vertical text to a PDF document, you will have to use the VerticalText object. It writes Text vertically. Note that the naming is done according to horizontal text although it referrs to vertical text. A line with the alignment Element.LEFT_ALIGN will actually be top aligned. Take a look at the example to see how it's done:
Example: java com.lowagie.examples.fonts.styles.Vertical
Writing vertical text: see vertical.pdf
Extra jars needed in your CLASSPATH: iTextAsian.jar
Go to top of the page
Amazon books:
amazon.co.uk-link