# Tutorial: iText by Example

## Basic Text Objects

Introduction:
iText is a library that produces PDF, but you don't need to know anything about PDF syntax, PDF objects, PDF operators or operands to use it (allthough it's possible to add direct content if you want to). iText comes with a large number of its own high level objects that can be used to add content to a PDF document.
This is a short (and incomplete) list of iText high-level objects:

- Chunk
- Paragraph
- Font
- Anchors
- Bookmarks
- List
- Images
- Tables
- Columns
- ...

Remark: some objects such as HeaderFooter and Graphic are not in the list (and not documented) because they are no longer supported. There are sufficient alternatives for those objects (see for instance page events and graphics2D).
Go to top of the page
The Chunk object:
A Chunk is the smallest significant part of text that can be added to a document. It is the 'atom' building block of most of the other High Level Text objects. All the contents of a Chunk are of the same font, fontsize, style, color, etc... For the complete functionality on this object, please read the chapter on the Chunk object. Functionalities such as subscript, superscript, underline and background are demonstrated in the following example:
Example: java com.lowagie.examples.objects.Chunks
Demonstrates some Chunk functionality: see Chunks.pdf
There is a complete chapter on the Chunk object if you need to know more about Chunks. Also related are the chapters on Anchors and Fonts.
Go to top of the page
The Paragraph object:
Paragraph is the text object you are likely to use the most. It is an ArrayList of one or more other high level elements, such as Chunk, Phrase, List, Image,... Unlike a Chunk, a Paragraph can contain text in different fonts.
Example: java com.lowagie.examples.objects.DifferentFonts
A Paragraph can contain text in different fonts: see differentfonts.pdf
The most important thing you need to know about paragraph, is that they have a leading and that every new Paragraph starts on a new line.
Example: java com.lowagie.examples.objects.Paragraphs
Demonstrates some Paragraph functionality: see Paragraphs.pdf
You can set the aligment of a Paragraph with the method setAlignment(int alignment). The alignment can be one of the following values:

- Element.ALIGN_LEFT
- Element.ALIGN_CENTER
- Element.ALIGN_RIGHT
- Element.ALIGN_JUSTIFIED

If you want the alignment to be justified, the space between the words can be stretched, as well as the space between the characters of a word. The default ratio of this word-char space is 2.5. You can change this ratio with setSpaceCharRatio. For instance, if you don't want the space between the characters of a word to be stretched, just do:

    writer.setSpaceCharRatio(PdfWriter.NO_SPACE_CHAR_RATIO);

The effect can be seen in the next example (compare page 1 and page 2 of the resulting PDF).
Example: java com.lowagie.examples.objects.SpaceWordRatio
Space Word Ratio: see spacewordratio.pdf
The following methods need no further explanation, they are pretty straightforward:

- setIndentationLeft(float indentation)
- setIndentationRight(float indentation)
- setSpacingBefore(float spacing)
- setSpacingAfter(float spacing)

Remark: the method setFirstLineIndent(float firstLineIndent) only works for paragraphs inside a ColumnText or PdfPTable object.
Example: java com.lowagie.examples.objects.ParagraphAttributes
Demonstrates some more Paragraph functionality: see ParagraphAttributes.pdf
Go to top of the page
The Phrase Object:
This extra section deals with the somewhat quirky class Phrase for the sake of completeness. In most cases you will prefer to use the class Paragraph.
Example: java com.lowagie.examples.objects.Phrases
Demonstrates the different constructors of class Phrase: see Phrases.pdf
The 'leading' parameter is very important for all other High Level Objects in iText, it's the space between two line and should therefore be a positive value.
Example: java com.lowagie.examples.objects.NegativeLeading
Shows the effect of a negative leading: see NegativeLeading.pdf
You can use a constructor to create a Phrase-object, but if you have special symbols in your text-string, you can use Phrase.getInstance to have your special symbols substituted (this only works with the base 14 fonts, Symbol and ZapfDingBats not included).
Example: java com.lowagie.examples.objects.SymbolSubstitution
Demonstrates how special characters are substituted by Symbols with Phrase.getInstance: see SymbolSubstitution.pdf
A more safe way to do font substitution, is be using class FontSelector:
Example: java com.lowagie.examples.objects.FontSelection
Selects the appropriate fonts that contain the glyphs needed to render text correctly: see fontselection.pdf
Go to top of the page
The List object:
The List object gives you functionality that is very similar to the <UL> or <OL> tags in HTML. The iText equivalent of <LI> is ListItem.
The type of List is chosen with the parameters numbered and lettered in the constructor. You also have to specify a parameter symbolIndent. This is the space that will be reserved for the list symbol. For unordered lists, you can choose any Chunk or String as list symbol with methods setListSymbol(Chunk symbol) or setListSymbol(String symbol). A numbered list always starts with '1', unless you change the first number with setFirst(int first). The default first character for lists that are ordered with letters is 'A' (uppercase), you can change it to lower case with method setFirst(char first) and pass 'a' as parameter.

    List list = new List(true, 20);
    list.add(new ListItem("First line"));

Example: java com.lowagie.examples.objects.Lists
Demonstrates some List functionality: see lists.pdf lists.html
There are some extra classes derived from the List object that allow you to generate more fancy lists: RomanList, GreekList, ZapfDingbatsList and ZapfDingbatsNumberList. Their usage is pretty straightforward:
Example: java com.lowagie.examples.objects.FancyLists
Demonstrates some List with Roman numerals, Greek letters, zapfdingbats,...: see fancylists.pdf
Go to top of the page
Amazon books:
amazon.co.uk-link