iText Tutorial
|
|
iText, a Free Java-PDF library
by Bruno Lowagie
|
[Home] |
[Previous] |
[TOC] |
|
[PDF] |
Part III: Advanced iText
Chapter 12: Page and Table Events
|
Page Events
If you generate a PDF file using iText, you add structured content to a Document-object
and this content is automatically being translated to a representation by the PdfWriter-object.
The hidden (package private) object PdfDocument is responsable for drawing the content
on different pages. While this happens, the process adding content is not aware of this. You can ask the writer if
a Table fits the page, you can ask the PdfWriter for the
current page number, but this is all very limited. If you really want to control what happens inside the writer,
you need to add a PdfPageEvent:
// class MyPageEvent implements the PdfPageEvent interface
MyPageEvent event = new MyPageEvent();
writer.setPageEvent(event);
This interface contains the following methods you have to implement.
- public void onOpenDocument(PdfWriter writer, Document document);
- public void onCloseDocument(PdfWriter writer, Document document);
- public void onStartPage(PdfWriter writer, Document document);
- public void onEndPage(PdfWriter writer, Document document);
- public void onParagraph(PdfWriter writer, Document document, float paragraphPosition);
- public void onParagraphEnd(PdfWriter writer,Document document,float paragraphPosition);
- public void onChapter(PdfWriter writer,Document document,float paragraphPosition, Paragraph title);
- public void onChapterEnd(PdfWriter writer,Document document,float paragraphPosition);
- public void onSection(PdfWriter writer,Document document,float paragraphPosition, int depth, Paragraph title);
- public void onSectionEnd(PdfWriter writer,Document document,float paragraphPosition);
- public void onGenericTag(PdfWriter writer, Document document, Rectangle rect, String text);
Of course, you don't always need all these methods, so it's easier not just to
implement the PdfPageEvent-interface, but to extend
the PdfPageEventHelper. This class contains 'empty'
implementations of all the methods mentioned above. You just have to override
the methods you need.
|
Open and close a document, start and end a page
The onOpenDocument method and the first onStartPage method
are called just after the document is opened and after the first page has been initialized.
onOpenDocument is mostly used to initialize some parameters that you defined
yourself in your own page event implemantation.
onStartPage is called just after each new page has been initialized.
The onEndPage method is called just before a new page is started
and initialized. This is the best method to add some headers and footers (if the
HeaderFooter-object isn't sufficient for your needs).
If you add headers and footers in the onStartPage method,
you sometimes have a blank page too many. The onCloseDocument
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 Document-object. THIS IS NOT THE SAME
OBJECT as the one you are adding structured content to. This is an instance of the (hidden)
PdfDocument-object. You can only invoke a limited number of
methods on this object.
|
Adding paragraphs, chapters, section
When a paragraph is added, you might want to know the current Y position on your page.
In example 4 of chapter 11,
we already used the onParagraph-method
to construct an outline tree. Each entry in the outline tree points at the starting position
of a paragraph (see Chap1104.pdf).
If you need to add some object at an absolute place just after a paragraph, just use
the onParagraphEnd-method.
The methods onChapter, onSection,
onChapterEnd and onSectionEnd 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.
|
Generic tags
In example 8 of chapter 2, we
already saw one example using generic tags to construct a glossary. In the next example, we are
going to use this method to count the number of interventions of each character in the play
'Romeo and Juliet' by William Shakespeare.
|
An example says a thousand words
Chap1201.java really says it all.
We use XML parsing from chapter 7 and
we will trigger some page events on Chap0703.xml
while generating the PDF file.
We will again use tagmap0703.xml, but
to be able to use the generictag functionality, we are going to change the behaviour of 1 element
in our own tagmap class that extends com.lowagie.text.xml.TagMap
(remark: if this wasn't an example, I would write a class that extends java.util.HashMap
instead, but that would make this example too long). We also write own handler class, because we don't want
the document to close when the closing documentroot tag is encountered. We want add an extra page before closing
the document ourselves.
A Speaker-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
onGenericTag method. We do some initialisations in the
onOpenDocument method, we keep track of the current act in the
onChapter 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 onPageEnd method
and finally, we set the value of this Y in the onCloseDocument 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. The result is a very nice document:
Chap1201.pdf
combining some of the most interesting functionalities of iText.
|
Table events
If you are using the PdfPTable-object, you can also
set the PdfPTableEvent:
MyTableEvent event = new MyTableEvent();
table.setTableEvent(event);
The table event interface has only one method you have to implement:
public void tableLayout(dfPTable table, float[] widths, float[] heights, int headerRows, int rowStart, PdfContentByte[] canvases);
This method is called at the end of the table rendering. You can add text or graphics to
one of the 4 PdfContentByte contained in parameter canvases:
- PdfPtable.BASECANVAS - the original PdfContentByte. Anything placed here will be under the table.
- PdfPtable.BACKGROUNDCANVAS - the layer where the background goes to.
- PdfPtable.LINECANVAS - the layer where the lines go to.
- PdfPtable.TEXTCANVAS - the layer where the text go to. Anything placed here will be over the table.
The layers are placed in sequence on top of each other.
The widths- and heightsarrays have the coordinates of the cells.
For the widthsarray the first element is the x coordinate of the left table border and the last
element is the x coordinate of the right table border. For the heightsarray the first element is
the y coordinate of the top table border and the last element is the y coordinate of the bottom
table border. Parameter headerRows is the number of rows defined for the header. It is always 0 if
the table is not rendered with Document.add.
Parameter rowStart is the first row number after the header.
Example 2 (Chap1202.pdf)
shows you how you can add an action to a cell and draw some lines on certain canvases.
|
[Top] |
[Previous] |
[TOC] |
[Next] |
[PDF] |
Page Updated: $Date: 2003/06/25 07:36:35 $
Copyright © 2000, 2001 by Bruno Lowagie
|
Adolf Baeyensstraat 121, 9040 Gent, BELGIUM,
tel +00 32 92 28 10 97 mailto:itext-questions@lists.sourceforge.net
|