# Tutorial: iText by Example

## Direct Content

PDF Syntax:
You can really do a lot of great things with the high-level objects iText offers you, but if you really want to make use of the full power of PDF, you need to know more about PDF syntax. Maybe you should read chapter 4 (Graphics) and chapter 5 (Text) of the PDF Reference Manual (version 1.6) first. They will give you a good insight about the different operators and operands we are going to use in the next chapters. In this tutorial chapter, I will do an attempt to summarize some of the most important concepts.
But let's start by quoting what is on page 163 of the Reference Manual:

> The graphics operators form six main groups.
> - Graphics state operators manipulate the data structure called the graphics state, the global framework within which the other graphics operators execute. The graphics state includes the current transformation matrix (CTM), which maps user space coordinates used within a PDF content stream into output device coordinates. It also includes the current color, the current clipping path, and many other parameters that are implicit operands of the painting operators.
>   For more info on how iText deals with this, see:
>   - PDF coordinate system
>   - Graphics State
>   - Colors
> - Path construction operators specify paths, which define shapes, linie trajectories, and regions of various sorts. They include operators for beginning a new path, adding line segments and curves to it, and closing it.
>   For more info on how iText deals with this, see:
>   - Path construction and painting
> - Path painting operators fill a path with a color, paint a stroke along it, or use it as a clipping boundary.
>   For more info on how iText deals with this, see:
>   - Path construction and painting
> - Other painting operators paint certain self-describing graphics objects. These include sampled images, geometrically defined shadings, and entire content streams that in turn contain sequences of graphics operators.
>   For more info on how iText deals with this, see:
>   - Image XObjects
>   - Form XObjects
>   - PostScript XObjects
> - Text operators select and show character glyphs from fonts (descriptions of typefaces for representing text characters). Because PDF treats glyphs as general graphical shapes, many of the text operators could be grouped with the graphics state or painting operators. (...)
>   For more info on how iText deals with this, see:
>   - Text
>   - Fonts
> - Marked-content operators associate higher-level logical information with objects in the content stream. This information does not affect the rendered appearance of the content (...).
>   For more info on how iText deals with this, see:
>   - Optional Content

Go to top of the page
iText approach:
When using high-level objects in iText, you add text and images, chapters and sections, paragraphs and chunks,... without bothering about layout. iText takes care of dividing the text into pages and positioning every word, sentence, paragraph on a page. But sometimes we don't want this automatic formatting. Sometimes we want to put some graphic or some text at some exact position on a page. The key class to achieve this, is com.lowagie.text.pdf.PdfContentByte.
Each page in an iText PDF file, is built using 4 different layers. Two of them (the middle ones) are stored in class PdfDocument. You don't have access to them. They are to be used by high-level objects only. The upper one, called 'text' is used for text, the lower one, called graphics, for all other content. For instance: the contents of a Chunk are added to the 'text' layer, but if the Chunk contains an Image, it is added to the 'graphics' layer. This way, an image never covers up text.
Then there's the other two layers, stored in class PdfWriter. You can get them with the methods getDirectContent() and getDirectContentUnder(). There is only one PdfContentByte-object representing the 'Direct Content' and one PdfContentByte-object representing the 'Direct Content Under'. Multiple calls to these methods will allways retrieve the same corresponding PdfContentByte.
You can cover content added with high-level objects by writing content to the 'Direct Content' PdfContentByte. You can add content under the high-level objects (for instance a Watermark) by adding content to the 'Direct Content Under' PdfContentByte. This is illustrated in the following example:
Example: java com.lowagie.examples.directcontent.Layers
Explains the concept of PdfContentByte layers in iText: see layers.pdf
External resources for this example: hitchcock.png
Summarized: when a page is finished, 4 layers are drawn on top of eachother in this order:

1. the PdfContentByte you can retrieve and with the method getDirectContentUnder()
2. the internal PdfContentByte-object that contains the graphics of high level objects
3. the internal PdfContentByte-object that contains the text of high level objects
4. the PdfContentByte you can retrieve and with the method getDirectContent()

Remark: this is iText specific stuff, do not confuse this tutorial section with the section on the Optional Content layers.
Go to top of the page
Using templates (Form XObjects):
The 4 iText layers (direct content, high level text, high level graphics and direct content under) are written to a PDF stream of a page. However, there is a possibility to get a layer, a canvas, a PdfTemplate that can be external to the PDF page stream. It will be treated as an external object.
There are 3 types of external objects in PDF:

1. Image XObjects
2. Form XObjects
3. PostScript XObjects

In iText, you can use a Form XObject by creating a PdfTemplate. PdfTemplate. This is done with the method PdfContentByte.createTemplate(float, float) (the parameters specify the width and height). You can add a template with on of the PdfContentByte.addTemplate methods. But you should read more about the Transformation Matrix first if you want to know what the parameters of these methods represent.
Example: java com.lowagie.examples.directcontent.Templates
Using templates: see templates.pdf
If all those transformation parameters are too complex to understand, you might want to wrap a PdfTemplate in an Image object (class Image has methods that are much easier to understand).
Example: java com.lowagie.examples.directcontent.TemplateImages
Templates used as image: see templateImages.pdf
Summarized: a Form XObject is a PDF content stream that is a self-contained description of any sequence of graphics objects. A form XObject may be painted multiple times, either on several pages or at several locations on the same page. It produces the same results each time, subject only to the graphics state at the time it is invoked.
DO NOT confuse Form XObjects with AcroForms. A Form XObjects isn't a form(field) as in the context of interactive forms (see Forms). That's why we prefer to use PdfTemplate when refering to Form XObjects.
In iText PdfTemplates are mainly used for two reasons:

1. You want to repeat a certain sequence of PDF syntax, but you want to save on disc space (reuse the stream) and processing time (write the stream only once).
2. You want to add some content to a page, but you don't know in advance what the content will be. For instance: you want to add a footer saying 'this it is page x of y', but you don't know the value of y yet. In this case, you can add a template for y, but you can wait to add content to the template untill you know the exact number of pages in your document.

There's probably only one thing left that keeps you from using PdfTemplates: you will have to learn about Page Events first, to know how to add a PdfTemplate each time a page is finished, or to fill the contents of a PdfTemplate, just before the Document is closed.
Go to top of the page
PostScript XObjects:
There is also basic support for PostScript XObjects (in iText PdfPSXObject extends PdfTemplate). You can add PS Syntax to this object with setLiteral and add the PS XObject with PdfContentByte.addPSXObject). However, it is no longer recommended to use Postscript XObjects in PDF. These PS fragments are used only when printing to a PostScript output device. They should be used with extreme caution, because they can cause PDF files to print incorrectly (See section 4.7.1 if the PDF Reference Manual: this feature is likely to be removed from PDF in a future version).
Go to top of the page
Amazon books:
amazon.co.uk-link