<!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: Page Events</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>Page Events</h2><div id="content"><div id="sidebar"><a class="toc" href="./../../index.html#directcontent_pageevents">
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="#pageevents">Page Event Methods</a></li><li><a href="#examples">Examples</a></li><li><a href="#romeojuliet">Romeo and Juliet: XML to PDF</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/pageevents/EndPage.java">EndPage</a><br><div class="description">Headers and footers in an EndPage event</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/endpage.pdf">endpage.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/PageNumbersWatermark.java">PageNumbersWatermark</a><br><div class="description">Making a document with a header containing 'page x of y' and with a watermark on every page.</div><div class="small">Input:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/logo.gif">logo.gif</a></li></ul><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/pageNumbersWatermark.pdf">pageNumbersWatermark.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/Bookmarks.java">Bookmarks</a><br><div class="description">Using paragraph events</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/bookmarks.pdf">bookmarks.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/Events.java">Events</a><br><div class="description">Using PageEvents</div><div class="small">Extra jars needed:</div><ul><li>crimson.jar</li></ul><div class="small">Input:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/tagmapRomeoJuliet.xml">tagmapRomeoJuliet.xml</a></li><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/playRomeoJuliet.xml">playRomeoJuliet.xml</a></li></ul><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/RomeoJuliet.pdf">RomeoJuliet.pdf</a></li></ul></div><div class="example"><div class="small">ANT script (all examples):</div><ul><li><a href="./../../directcontent/pageevents/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=14">
Chapter 14:
</a>Automating PDF creation</li></ul></p>
</div><a class="top" href="#top">Go to top of the page</a><a name="pageevents"></a><div class="title">Page Event Methods:</div><div xmlns="http://www.w3.org/1999/xhtml">
If you generate a PDF file using high-level iText objects, you add structured content
to a <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/Document.html">Document</a>-object.
This content is automatically being translated to PDF syntax by the
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html">PdfWriter</a>.
The hidden (package private) object <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfDocument.html">PdfDocument</a>-object
is responsible for drawing the content on different pages.
While this happens, the process adding content (your program) is not aware of all this PDF specific work.
You can ask the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html">PdfWriter</a> for the current page number
with <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getPageNumber()">PdfWriter.getPageNumber()</a>,
but this is all very limited. If you really want to control what happens inside the writer,
you need to add a <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html">PdfPageEvent</a>:<br xmlns="http://www.w3.org/1999/xhtml">
<pre class="commandline">// class MyPageEvent implements the PdfPageEvent interface
MyPageEvent event = new MyPageEvent();
writer.setPageEvent(event);</pre>
The <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html">PdfPageEvent</a> interface contains the following methods you have to implement in your own class MyPageEvent:
<ul xmlns="http://www.w3.org/1999/xhtml">
<li>public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onOpenDocument(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onOpenDocument(PdfWriter writer, Document document)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onCloseDocument(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onCloseDocument(PdfWriter writer, Document document)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onStartPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onStartPage(PdfWriter writer, Document document)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onEndPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onEndPage(PdfWriter writer, Document document)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onParagraph(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onParagraph(PdfWriter writer, Document document, float paragraphPosition)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onParagraphEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onParagraphEnd(PdfWriter writer,Document document,float paragraphPosition)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onChapter(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float,%20com.lowagie.text.Paragraph)">onChapter(PdfWriter writer,Document document,float paragraphPosition, Paragraph title)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onChapterEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onChapterEnd(PdfWriter writer,Document document,float paragraphPosition)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onSection(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float,%20int,%20com.lowagie.text.Paragraph)">onSection(PdfWriter writer,Document document,float paragraphPosition, int depth, Paragraph title)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onSectionEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onSectionEnd(PdfWriter writer,Document document,float paragraphPosition)</a>;</li>
<li xmlns="http://www.w3.org/1999/xhtml">public void <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onGenericTag(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20com.lowagie.text.Rectangle,%20java.lang.String)">onGenericTag(PdfWriter writer, Document document, Rectangle rect, String text)</a>;</li>
</ul>
Of course, you don't always need all these methods, so it's easier not just to
implement the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html">PdfPageEvent</a>-interface, but to extend
the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEventHelper.html">PdfPageEventHelper</a>. This class contains 'empty'
implementations of all the methods mentioned above. You just have to override
the methods you need.<br xmlns="http://www.w3.org/1999/xhtml"><br>
<div class="subtitle">Open and close a document, start and end a page</div>
The <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onOpenDocument(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onOpenDocument</a> method
and the first <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onStartPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onStartPage</a> method
are called just after the document is opened and after the first page has been initialized.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onOpenDocument(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onOpenDocument</a> is mostly used to initialize some parameters that you defined
yourself in your own page event implemantation.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onStartPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onStartPage</a> is called just after each new page has been initialized.
The <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onEndPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onEndPage</a> method is called just before a new page is started
and initialized. This is the best method to add some headers and footers.
I don't recomment to add headers and footers in the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onStartPage(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onStartPage</a> method,
because this can lead to all kinds of quirky effect (for instance an extra, unwanted blank page at the end of your document).
The <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onCloseDocument(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document)">onCloseDocument</a>
method is called just before all streams are closed. This is the ideal place to complete
the template containing the total number of pages, if you have some footer indicating
'page X of Y'. It is only just before closing the document that you know the exact value of Y.
In your implementation of these methods, you always get the instance of the writer that
triggered the event a <a href="http://itext.ugent.be/library/api/com/lowagie/text/Document.html">Document</a>-object. THIS IS NOT THE SAME
OBJECT as the one you are adding structured content to. This is an instance of the (hidden)
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfDocument.html">PdfDocument</a>-object. You can only invoke a limited number of
methods on this object.<br xmlns="http://www.w3.org/1999/xhtml"><br>
<div class="subtitle">Adding paragraphs, chapters, section</div>
When a paragraph is added, you might want to know the current Y position on your page.
Below you'll find an example adding bookmarks automatically;
each entry in the outline tree points at the starting position of a paragraph.
This outline tree is generated in an <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onParagraph(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onParagraph</a> event.
If you need to add some object at an absolute place just after a paragraph, just use
the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onParagraphEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onParagraphEnd</a>-method.<br xmlns="http://www.w3.org/1999/xhtml">
The methods <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onChapter(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float,%20com.lowagie.text.Paragraph)">onChapter</a>,
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onSection(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float,%20int,%20com.lowagie.text.Paragraph)">onSection</a>,
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onChapterEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onChapterEnd</a> and
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfPageEvent.html#onSectionEnd(com.lowagie.text.pdf.PdfWriter,%20com.lowagie.text.Document,%20float)">onSectionEnd</a>
do just the same, but the first two also pass the chapter or section title. This can be used
to set the content of some header or footer (as in the <a href="./../../directcontent/pageevents/index.html#romeojuliet">'Romeo and Juliet' example</a> below), or to construct a Table-of-Contents.<br xmlns="http://www.w3.org/1999/xhtml"><br>
<div class="subtitle">Generic tags</div>
Generic tags are already discussed elsewhere, for instance when we added
<a xmlns="" href="./../../objects/chunk/index.html#generic">generic functionality</a>
to a Chunk object. In the <a href="./../../directcontent/pageevents/index.html#romeojuliet">'Romeo and Juliet' example</a>, we are going to use this method to count
the number of interventions of each character in the play.
</div><a class="top" href="#top">Go to top of the page</a><a name="examples"></a><div class="title">Examples:</div><div xmlns="http://www.w3.org/1999/xhtml">
<div class="subtitle">Headers/Footers</div>
If you want to add a Header and/or a Footer to each page in your document,
you have to do this in an <span class="commandline">onEndPage</span> event.
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/EndPage.java">
com.lowagie.examples.directcontent.pageevents.EndPage</a><br>Headers and footers in an EndPage event: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/endpage.pdf">endpage.pdf</a><br></div>
<div xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Page X of Y</div>
In this example, not only we add a header and a footer.
We also use a template in the footer to display 'page X of Y'.
The total number of pages is added to the PdfTemplate in the
<span class="commandline">onCloseDocument</span> event.
As you can see, watermarks can be added in <span class="commandline">onStartPage</span>,
but you could also do this in <span class="commandline">onEndPage</span>
(where we also draw a Rectangle around the text on each page).
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/PageNumbersWatermark.java">
com.lowagie.examples.directcontent.pageevents.PageNumbersWatermark</a><br>Making a document with a header containing 'page x of y' and with a watermark on every page.: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/pageNumbersWatermark.pdf">pageNumbersWatermark.pdf</a><br>
External resources for this example:
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/logo.gif">logo.gif</a><br></div>
<div xmlns="http://www.w3.org/1999/xhtml" class="subtitle">Bookmarks</div>
This example was already mentioned in the chapter on
<a xmlns="" href="./../../objects/bookmarks/index.html#bookmarks">bookmarks</a>.
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/Bookmarks.java">
com.lowagie.examples.directcontent.pageevents.Bookmarks</a><br>Using paragraph events: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/bookmarks.pdf">bookmarks.pdf</a><br></div>
</div><a class="top" href="#top">Go to top of the page</a><a name="romeojuliet"></a><div class="title">Romeo and Juliet: XML to PDF:</div><div xmlns="http://www.w3.org/1999/xhtml">
In this example, we combine some of the most interesting functionalities of iText.
We have an XML file (<a href="playRomeoJuliet.xml">playRomeoJuliet.xml</a>) containing the complete play 'Romeo and Juliet' by William Shakespeare.
We have defined a tagmap (<a href="tagmapRomeoJuliet.xml">tagmapRomeoJuliet.xml</a>) that translates the tags in the XML to tags that can be understood by iText.
iText will parse the XML and generate the PDF file using this tagmap.<br>
A <span class="commandline">Speaker</span>-class was written to keep track
of all the different speakers. As you can see in the page event implementation,
we update the list of speakers in the <span class="commandline">onGenericTag</span> method.
We do some initialisations in the <span class="commandline">onOpenDocument</span> method,
we keep track of the current act in the <span class="commandline">onChapter</span> method,
we add this information as a header on every even page of the document and also put
a 'page X of Y'-footer in the <span class="commandline">onPageEnd</span> method
and finally, we set the value of this Y in the <span class="commandline">onCloseDocument</span> method.
After the document is parsed, we retrieve the alphabetical list of speaker from out event class
and add an extra page with this info.
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/Events.java">
com.lowagie.examples.directcontent.pageevents.Events</a><br>Using PageEvents: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/RomeoJuliet.pdf">RomeoJuliet.pdf</a><br>
External resources for this example:
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/tagmapRomeoJuliet.xml">tagmapRomeoJuliet.xml</a> <a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/pageevents/playRomeoJuliet.xml">playRomeoJuliet.xml</a><br>
Extra jars needed in your CLASSPATH:
crimson.jar<br></div>
</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:49
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>
