<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>iText Tutorial: Direct Content</title><meta name="Description" content="Add content directly to the PDF file using the PdfContentByte class."><meta name="Keywords" content="PDF, JAVA, iText, examples, PdfContentByte, Graphics, absolute positions, Lowagie, Bruno"><link rel="stylesheet" href="./../style.css" type="text/css"></head><body><a name="top" class="logo" href="http://www.lowagie.com/iText"><img src="http://www.lowagie.com/iText/images/logo.gif" border="0" alt="iText"></a><h1>Tutorial: iText by Example</h1><h2>Direct Content</h2><div id="content"><div id="sidebar"><a class="toc" href="./../index.html#directcontent">
Table of Contents
</a><div align="Center" class="small">Best viewed with:<br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 180;
google_ad_height = 60;
google_ad_format = "180x60_as_rimg";
google_cpa_choice = "CAAQyaj8zwEaCIwcWMzeycafKMu293M";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script></div><div class="sidetitle">Sections:</div><ul><li><a href="#inaction">In the book</a></li><li><a href="#pdfsyntax">PDF Syntax</a></li><li><a href="#pdfcontentbyte">iText approach</a></li><li><a href="#templates">Using templates (Form XObjects)</a></li><li><a href="#Postscript">PostScript XObjects</a></li></ul><br><br><div class="sidetitle">Examples:</div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/Layers.java">Layers</a><br><div class="description">Explains the concept of PdfContentByte layers in iText</div><div class="small">Input:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/hitchcock.png">hitchcock.png</a></li></ul><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/layers.pdf">layers.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/Templates.java">Templates</a><br><div class="description">Using templates</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/templates.pdf">templates.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/TemplateImages.java">TemplateImages</a><br><div class="description">Templates used as image</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/templateImages.pdf">templateImages.pdf</a></li></ul></div><div class="example"><div class="small">ANT script (all examples):</div><ul><li><a href="./../directcontent/build.xml">
build.xml
</a></li></ul></div></div><div id="main"><a name="inaction"></a><div class="title">In the book:</div><div xmlns="http://www.w3.org/1999/xhtml" xmlns:site="http://www.lowagie.com/iText/site">
<p xmlns=""><a href="http://itext.ugent.be/itext-in-action/"><img src="http://itext.ugent.be/img/lowagie_3d.jpg" border="0" align="right"></a>
The examples in this free online tutorial will help you getting started
with iText. Note that most examples are two years old.
Some of the examples may be obsolete. Also the theory that
comes with the examples isn't always 100% accurate.
If you want more recent examples or if you want to know more
about the theoretical background of PDF and iText, please consult the book
<a href="http://itext.ugent.be/itext-in-action/">
"iText in Action".
</a>
Note that the first and the third chapter of the book
can be downloaded for free from <a href="http://www.manning.com/affiliate/idevaffiliate.php?id=223_53">http://manning.com/lowagie/</a></p><p>
More specifically:
<ul><li><a class="subtitle" href="http://itext.ugent.be/itext-in-action/chapter.php?chapter=10">
Chapter 10:
</a>Constructing and painting paths</li><li><a class="subtitle" href="http://itext.ugent.be/itext-in-action/chapter.php?chapter=11">
Chapter 11:
</a>Adding color and text</li><li><a class="subtitle" href="http://itext.ugent.be/itext-in-action/chapter.php?chapter=12">
Chapter 12:
</a>Drawing to Java Graphics2D</li></ul></p>
</div><a class="top" href="#top">Go to top of the page</a><a name="pdfsyntax"></a><div class="title">PDF Syntax:</div><div xmlns="http://www.w3.org/1999/xhtml">
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.<br>
But let's start by quoting what is on page 163 of the Reference Manual:
<blockquote>
The graphics operators form six main groups.<br>
<ul>
<li><i>Graphics state operators</i> manipulate the data structure called
the <i>graphics state</i>, the global framework within which the other
graphics operators execute. The graphics state includes the <i>current
transformation matrix</i> (CTM), which maps user space coordinates used
within a PDF content stream into output device coordinates. It also
includes the <i>current color</i>, the <i>current clipping path</i>,
and many other parameters that are implicit operands of the painting
operators.<br>
<div class="small">For more info on how iText deals with this, see:
<ul>
<li><a xmlns="" href="./../directcontent/coordinates/index.html#">PDF coordinate system</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/graphics/index.html#state">Graphics State</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/colors/index.html#">Colors</a></li>
</ul></div>
</li>
<li xmlns="http://www.w3.org/1999/xhtml"><i>Path construction operators</i> specify <i>paths</i>, 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.<br>
<div class="small">For more info on how iText deals with this, see:<ul><li>
<a xmlns="" href="./../directcontent/graphics/index.html#paths">Path construction and painting</a></li></ul></div></li>
<li xmlns="http://www.w3.org/1999/xhtml"><i>Path painting operators</i> fill a path with a color, paint a stroke
along it, or use it as a clipping boundary.
<div class="small">For more info on how iText deals with this, see:<ul><li>
<a xmlns="" href="./../directcontent/graphics/index.html#paths">Path construction and painting</a></li></ul></div></li>
<li xmlns="http://www.w3.org/1999/xhtml"><i>Other painting operators</i> 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.
<div class="small">For more info on how iText deals with this, see:
<ul>
<li><a xmlns="" href="./../objects/images/index.html#">Image XObjects</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/index.html#templates">Form XObjects</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/index.html#postscript">PostScript XObjects</a></li>
</ul></div></li>
<li xmlns="http://www.w3.org/1999/xhtml"><i>Text operators</i> select and show <i>character glyphs</i> from
<i>fonts</i> (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. (...)<br>
<div class="small">For more info on how iText deals with this, see:
<ul>
<li><a xmlns="" href="./../directcontent/text/index.html#">Text</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../fonts/index.html#">Fonts</a></li>
</ul></div></li>
<li xmlns="http://www.w3.org/1999/xhtml"><i>Marked-content operators</i> associate higher-level logical information
with objects in the content stream. This information does not affect the rendered
appearance of the content (...).<br>
<div class="small">For more info on how iText deals with this, see:<ul><li>
<a xmlns="" href="./../directcontent/optionalcontent/index.html#">Optional Content</a></li></ul></div></li>
</ul>
</blockquote>
</div><a class="top" href="#top">Go to top of the page</a><a name="pdfcontentbyte"></a><div class="title">iText approach:</div><div xmlns="http://www.w3.org/1999/xhtml">
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 <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html">com.lowagie.text.pdf.PdfContentByte</a>.<br xmlns="http://www.w3.org/1999/xhtml">
Each page in an iText PDF file, is built using 4 different layers.
Two of them (the middle ones) are stored in class <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfDocument.html">PdfDocument</a>.
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.<br xmlns="http://www.w3.org/1999/xhtml">
Then there's the other two layers, stored in class <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html">PdfWriter</a>.
You can get them with the methods
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getDirectContent()">getDirectContent()</a> and
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getDirectContentUnder()">getDirectContentUnder()</a>.
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.<br xmlns="http://www.w3.org/1999/xhtml">
<img xmlns="" border="0" src="./../images/layers.gif" alt="PdfContentByte layers"><br xmlns="http://www.w3.org/1999/xhtml">
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:
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/Layers.java">
com.lowagie.examples.directcontent.Layers</a><br>Explains the concept of PdfContentByte layers in iText: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/layers.pdf">layers.pdf</a><br>
External resources for this example:
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/hitchcock.png">hitchcock.png</a><br></div>
Summarized: when a page is finished, 4 layers are drawn on top of eachother in this order:
<ol xmlns="http://www.w3.org/1999/xhtml">
<li>the PdfContentByte you can retrieve and with the method <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getDirectContentUnder()">getDirectContentUnder()</a></li>
<li xmlns="http://www.w3.org/1999/xhtml">the internal PdfContentByte-object that contains the graphics of high level objects</li>
<li>the internal PdfContentByte-object that contains the text of high level objects</li>
<li>the PdfContentByte you can retrieve and with the method <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getDirectContent()">getDirectContent()</a></li>
</ol>
Remark: this is iText specific stuff, do not confuse this tutorial section with the section on
the <a href="./../directcontent/optionalcontent/index.html#">Optional Content</a> layers.
</div><a class="top" href="#top">Go to top of the page</a><a name="templates"></a><div class="title">Using templates (Form XObjects):</div><div xmlns="http://www.w3.org/1999/xhtml">
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 <i>PdfTemplate</i>
that can be external to the PDF page stream. It will be treated as an <i>external object</i>.<br>
There are 3 types of external objects in PDF:
<ol>
<li><a xmlns="" href="./../objects/images/index.html#">Image XObjects</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/index.html#templates">Form XObjects</a></li>
<li xmlns="http://www.w3.org/1999/xhtml"><a xmlns="" href="./../directcontent/index.html#postscript">PostScript XObjects</a></li>
</ol>
In iText, you can use a <i xmlns="http://www.w3.org/1999/xhtml">Form XObject</i> by creating a <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfTemplate.html">PdfTemplate</a>.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfTemplate.html">PdfTemplate</a>.
This is done with the method <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#createTemplate(float,%20float)">PdfContentByte.createTemplate(float, float)</a>
(the parameters specify the width and height). You can add a template with on of the
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addTemplate(com.lowagie.text.pdf.PdfTemplate,%20float,%20float)">PdfContentByte.addTemplate</a> methods.
But you should read more about the <a href="./../directcontent/coordinates/index.html#templates">Transformation Matrix</a> first if you want to know what the parameters of these methods represent.<br xmlns="http://www.w3.org/1999/xhtml">
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/Templates.java">
com.lowagie.examples.directcontent.Templates</a><br>Using templates: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/templates.pdf">templates.pdf</a><br></div>
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).
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/TemplateImages.java">
com.lowagie.examples.directcontent.TemplateImages</a><br>Templates used as image: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/templateImages.pdf">templateImages.pdf</a><br></div>
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.<br xmlns="http://www.w3.org/1999/xhtml">
DO NOT confuse Form XObjects with <i>AcroForms</i>. A Form XObjects isn't a form(field) as in the context of
<i>interactive forms</i> (see <a xmlns="" href="./../forms/index.html#">Forms</a>). That's why we prefer to use
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfTemplate.html">PdfTemplate</a> when refering to Form XObjects.<br xmlns="http://www.w3.org/1999/xhtml">
In iText PdfTemplates are mainly used for two reasons:
<ol>
<li>You want to <i>repeat</i> 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).</li>
<li>You want to add some content to a page, but you <i>don't know in advance</i> 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.</li>
</ol>
There's probably only one thing left that keeps you from using PdfTemplates: you will have to learn about <a xmlns="" href="./../directcontent/pageevents/index.html#eps">Page Events</a> 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.
</div><a class="top" href="#top">Go to top of the page</a><a name="Postscript"></a><div class="title">PostScript XObjects:</div><div xmlns="http://www.w3.org/1999/xhtml">
There is also basic support for PostScript XObjects (in iText <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPSXObject.html">PdfPSXObject</a> extends
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfTemplate.html">PdfTemplate</a>). You can add PS Syntax to this object with
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#setLiteral(String)">setLiteral</a>
and add the PS XObject with
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html#addPSXObject(com.lowagie.text.pdf.PdfPSXObject)">PdfContentByte.addPSXObject</a>).
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).
</div><a class="top" href="#top">Go to top of the page</a><div id="footer" xmlns="http://www.w3.org/1999/xhtml">
Page Updated: 2006/09/17 10:13:58
Copyright © 1999-2005
Bruno Lowagie<br><a href="http://www.lowagie.com/iText/">iText</a> is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.
</div></div></div><div class="commercial"><br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 120;
google_ad_height = 600;
google_ad_format = "120x600_as";
google_ad_channel ="";
google_ad_type = "text_image";
google_color_border = "FFFFFF";
google_color_bg = "FFFFFF";
google_color_link = "1B09BD";
google_color_url = "100670";
google_color_text = "707070";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script><br><br><div class="subtitle">Amazon books:</div><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=1932394796&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a xmlns="" href="http://www.amazon.co.uk/exec/obidos/ASIN/1932394796/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=0321304748&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a href="http://www.amazon.co.uk/exec/obidos/ASIN/0321304748/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=JAVA&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=PDF&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br></div></body></html>
