# Tutorial: iText by Example

## Getting fonts

Fonts supported in iText:
The first part of Chapter 5 of the PDF Reference Manual deals with Text State; the second part (starting with section 5.4) tells you all about fonts. If you want to know more about how to use a Font object with iText, please read the chapter on Font objects first. This chapter will tell you where to find the font you need.
Go to top of the page
Built-in fonts:
PDF prescribes a set of 14 standard fonts that can be used without prior definition. These include four faces each of three Latin text typefaces (Courier, Helvetica and Times), as well as two symbolic fonts (Symbol and ITC Zapf Dingbats ®). These fonts, or suitable substitute fonts with the same metrics, are considered to be available in all PDF consumer applications. You don't have to embed them in your PDF document.
These 'Base14 Fonts' were historically the first fonts supported in iText. If you take a look inside the iText jar, you find an AFM file for each of these fonts in directory com/lowagie/text/pdf/fonts. AFM is Adobe's ASCII-based file format used for storing font metric data as human-readable data. iText reads these files to retrieve information on the width, the kerning and other metrics of each character (or, to use the correct term: of each 'glyph').

Font | AFM file
--- | ---
Courier | Courier.afm
Courier Bold | Courier-Bold.afm
Courier Italic (Oblique) | Courier-Oblique.afm
Courier Bold and Italic | Courier-BoldOblique.afm
Helvetica | Helvetica.afm
Helvetica Bold | Helvetica-Bold.afm
Helvetica Italic (Oblique) | Helvetica-Oblique.afm
Helvetica Bold and Italic | Helvetica-BoldOblique.afm
Times Roman | Times-Roman.afm
Times Roman Bold | Times-Bold.afm
Times Roman Italic | Times-Italic.afm
Times Roman Bold and Italic | Times-BoldItalic.afm
Symbol | Symbol.afm
ZapfDingBats® | ZapfDingbats.afm

As you can see the different faces (normal, bold, italic and bolditalic) of the same type face (Courier, Helvetica, Times Roman) are considered to be different fonts.
Go to top of the page
Fonts from files:
TTF Files (True Type Fonts)
The True Type font format was developed by Apple Computer, Inc., and has been adopted as a standard font format for the MicroSoft Windows operating system. You will find lots of TTF files in the directory 'C:/WINDOWS/FONTS'. These font files can be read by iText. It doesn't matter on which operating system you are working: you can use a ttf-file on LINUX as well as on Apple computers as long as you don't violate any copyrights that may rest on the font (in which case iText will throw an exception).
Example: java com.lowagie.examples.fonts.getting.TrueType
Using a True Type font: see truetype.pdf
Registering font files
Instead of creating a BaseFont and wrap it in a Font, you could use FontFactory, which is the most uniform way to get your font. Unfortunately FontFactory doesn't know where your font-files (ttf or other) are stored. So you have to register the fonts you want to use:

    FontFactory.register("c:\\windows\\fonts\\comic.ttf");
    FontFactory.register("c:\\windows\\fonts\\msgothic.ttc");

If you register a font file with register(java.lang.String), you can get the font by its name. You can ask the FontFactory for a list with all the registered fonts with getRegisteredFonts(). If you want to use fontnames defined by yourself, just register them with an alias (register(java.lang.String, java.lang.String)) and use that alias instead of the actual fontname.
Example: java com.lowagie.examples.fonts.getting.RegisterFont
Registering Fonts with the FontFactory: see registerfont.pdf registered.txt
Remark that all methods in class FontFactory are static. So if you have different applications in the same JVM, you may discover that there were more fonts registered than you expected...
Remember when we said there was a different font for every fontstyle? It can be quite difficult having to switch to another font everytime you want to change the style. Sometimes you have to look for the fontitalic, sometimes you have to look for the fontoblique. If you register all the styles of the same font family in advance, FontFactory looks up which font corresponds with which style automatically.
Example: java com.lowagie.examples.fonts.getting.FontFactoryStyles
Changing the style of a fontfactory font: see fontfactorystyles.pdf
Of course it's still not very userfriendly having to point to the location of the font file on the disk everytime you need a new font. You could register all the fonts in a directory with registerDirectory(java.lang.String). This way you don't have to look up the exact names of the normal, bold, italic or bolditalic font of a same family. It gets even easier if you use registerDirectories(). This method looks in some probable directories such as c:\windows\fonts, /usr/X/lib/X11/fonts/TrueType, /usr/X11R6/lib/X11/fonts/ttf, etc... This works on most Windows, Linux and Solaris systems. (If not, you will have to go and look for the font files yourself.) In the next example, you can see what fonts are available in the standard directories on my own computer:
Example: java com.lowagie.examples.fonts.getting.UsingFontFactory
Sums up the Fonts that are available in some standard font directories on your system: see FontFactory.pdf
TTC Files (True Type Collections)
A True Type Collection contains more than one font. As you can see in the example, we add a number after the TTC-file to indicate which of the fonts we want to use. If you want to know the names of the fonts in a certain TTC-file, you can use the method enumerateTTCNames(java.lang.String). The file msgothic.ttc contains 3 fonts: (0) MS-Gothic, (1) MS-PGothic and (2) MS-UIGothic. In the example, we want to use MS-PGothic, so we add 1 to the path:

    BaseFont.createFont(
      "c:\\windows\\fonts\\msgothic.ttc,1",
      BaseFont.IDENTITY_H,
      BaseFont.EMBEDDED);

Remark that this example will not run on your system if you don't have msgothic.ttc in your fonts directory. It's not there by default! If you want to run this example, you should look on your WINDOWS installation CDs and extract it to your fonts directory.
Example: java com.lowagie.examples.fonts.getting.TrueTypeCollections
True Type Collections: see truetypecollections.pdf msgothic.txt
OTF Files (Open Type Fonts)
OpenType is a cross-platform font format developed jointly by Microsoft and Adobe. It simplifies font management, adds new typographic capabilities, and improves multilingual support. Both Microsoft and Adobe have announced that OpenType will replace their respective TrueType and Type 1 font formats, and Adobe has already converted the entire Adobe Type Library into this format.
Example: java com.lowagie.examples.fonts.getting.OpenTypeFont
Using an Open Type Font with Compact Font Format (CFF) data only (no true type outlines): see opentypefont.pdf
External resources for this example: liz.otf
AFM Files (Adobe Font Metrics)
If you have other .AFM and .PFB files than the afm files of Base14 fonts that are in the iText.jar,, you can put them in the same directory (com/lowagie/text/pdf/fonts) and then use something like this:

    BaseBont bf = BaseFont.createFont("myfont.afm", BaseFont.WINANSI, BaseFont.EMBEDDED);

However, if you have the alternative, use a true type font: the font will be subset and the resulting document will be a lot smaller.
Go to top of the page
Fonts from jars (and font packs):
CID fonts are Postscript-based fonts which can support a large number of characters (65,536 max). The format is often used for CJK fonts (CJK = Chinese Japanese Korean). CID format makes it possible to change the character order (encoding) of a font through the use of character-to-glyph tables (CMaps) which are external to the font.
If you want to use CJK fonts in iText, you need an extra jar: iTextAsian.jar. If you want to be able to read the text you generated with iText using CJK fonts, you will also need to download and install a special font pack for Acrobat Reader (or maybe your Reader will ask you to install such a font pack upon opening a PDF file with CJK fonts). For the rest, creating a CJK font supported by the iTextAsian.jar is as easy as using any other font:

    BaseFont bfChinese = BaseFont.createFont("STSong-Light", "UniGB-UCS2-H", BaseFont.NOT_EMBEDDED);
    Font FontChinese = new Font(bfChinese, 12, Font.NORMAL);
    Paragraph p = new Paragraph(chinese, FontChinese);
    document.add(p);

Skip to the direction-section if you want to know how to write vertical text!
Example: java com.lowagie.examples.fonts.getting.ChineseJapaneseKorean
Using CJK Fonts: see cjk.pdf
Extra jars needed in your CLASSPATH: iTextAsian.jar
This is the list of fonts supported in the iTextAsian.jar:

- Chinese Simplified:
  STSong-Light and STSongStd-Light with the encodings UniGB-UCS2-H and UniGB-UCS2-V
- Chinese Traditional:
  MHei-Medium, MSung-Light and MSungStd-Light with the encodings UniCNS-UCS2-H and UniCNS-UCS2-V
- Japanese:
  HeiseiMin-W3, HeiseiKakuGo-W5 and KozMinPro-Regular with the encodings UniJIS-UCS2-H, UniJIS-UCS2-V, UniJIS-UCS2-HW-H and UniJIS-UCS2-HW-V
- Korean:
  HYGoThic-Medium, HYSMyeongJo-Medium and HYSMyeongJoStd with the encodings UniKS-UCS2-H and UniKS-UCS2-V

CID fonts
But that's not all, there is also an extra jar iTextAsianCmaps.jar. It contains the cmaps for lots of other CID fonts. This is how you can use them:

    PdfEncodings.loadCmap(
      "GBK2K-H",
      PdfEncodings.CRLF_CID_NEWLINE); // needs to be done only once
    byte text[] = my_GB_encoded_text;
    String cid = PdfEncodings.convertCmap("GBK2K-H", text);
    BaseFont bf = BaseFont.createFont("STSong-Light", "Identity-H", false);
    Paragraph p = new Paragraph(cid, new Font(bf, 14));
    document .add(p);

Go to top of the page
Amazon books:
amazon.co.uk-link
amazon.co.uk-link