iText Tutorial
|
|
iText, a Free Java-PDF library
by Bruno Lowagie
|
[Home] |
[Previous] |
[TOC] |
[Next] |
[PDF] |
Part III: Advanced iText
Chapter 11: Local and Remote Goto's, Destinations and Outlines
|
Local goto
Sometimes you need a link to allow the reader of your document to jump from
one position in the text to another. You can achieve this with two methods of
class Chunk: setLocalGoto
and setLocalDestination. Both methods take 1 parameter:
this is the unique name you want to give to the destination.
Example:
Chunk localgoto = new Chunk("this word", FontFactory.getFont(FontFactory.HELVETICA, 12, Font.NORMAL, new Color(0, 0, 255))).setLocalGoto("test");
Chunk destination = new Chunk("local destination", FontFactory.getFont(FontFactory.HELVETICA, 12, Font.NORMAL, new Color(0, 255, 0))).setLocalDestination("test");
The 'local goto' functionality is demonstrated in example 1
and it can be tested in the resulting document Chap1101.pdf.
|
Remote goto
anchors again
In Chapter 3 we showed how an Anchor
to an external URL could be created. Class Anchor extended
class Phrase, so an anchor could contains different chunks
with different fonts, styles and colors. In advanced iText, there is another way to define
a link to an URL:
Chunk chunk = new Chunk("anchor", FontFactory.getFont(FontFactory.HELVETICA, 12)).setAnchor(new URL("http://www.lowagie.com/iText/"));
Jump to a specific position in another PDF document
If you have defined a local destination in a certain document (see section
local goto), you can jump to this destination from
another document. To achieve this, you can use the method
setRemoteGoto:
Chunk chunk = new Chunk("jump", FontFactory.getFont(FontFactory.HELVETICA, 12, Font.ITALIC)).setRemoteGoto("test.pdf", "test"));
'test.pdf' being another document and 'test' a local destination in this document.
Jump to a specific page in another PDF document
It's even easier to jump to a specific page in another document,
just use the method setRemoteGoto with a
pagenumber instead of the name of some local destination:
Chunk chunk = new Chunk("jump", FontFactory.getFont(FontFactory.HELVETICA, 12, Font.ITALIC)).setRemoteGoto("test.pdf", 3));
Check out example 2 and Chap1102a.pdf/Chap1102b.pdf
for a little demonstration.
|
Actions
A PDF document can have a certain interactivity: you can create several 'actions' to jump to another page or location,
to start an other application,... These are the actions that are supported in iText:
Named actions
There are 4 predefined named actions in iText:
- PdfAction.FIRSTPAGE: jumps to the first page
- PdfAction.PREVPAGE: jumps to the previous page
- PdfAction.NEXTPAGE: jumps to the next page
- PdfAction.LASTPAGE: jumps to the last page
It is very easy to use one of these named destinations:
PdfAction action = new PdfAction(PdfAction.FIRSTPAGE);
Chunk chunk = new Chunk("Click me to go to the first page");
chunk.setAction(action);
document.add(chunk);
You can find an example of these 4 named destinations in example 3 (Chap1103.pdf).
Launching an application
This feature is also demonstrated in example 3 (but it is very platformdependent).
If you use this constructor:
public PdfAction(String application, String parameters, String operation, String defaultDir)
with for instance application equals to "c:/winnt/notepad.exe" (the rest of the parameters can be null),
you can launch NOTEPAD from a link in your PDF document (if you have the notepad executable in the specified directory).
Open action
You can also trigger an action the moment somebody opens the document.
This can be done in two different ways:
- Using the PdfContentByte object:
PdfContentByte cb = writer.getDirectContent();
cb.localDestination("page2", new PdfDestination(PdfDestination.XYZ, -1, 10000, 0));
writer.setOpenAction("page2");
This is shown in example 4.
- Using the PdfAction object:
PdfAction action = PdfAction.gotoLocalPage(2, new PdfDestination(PdfDestination.XYZ, -1, 10000, 0), writer);
writer.setOpenAction(action);
This is shown in example 5.
The moment you open Chap1104.pdf
or Chap1105.pdf you jump directly to page 2.
Javascript
You can add javascript to a document using the Javascript-object:
PdfAction jAction = PdfAction.javaScript("this.print(true);\r", writer);
writer.addJavaScript(jAction);
Try out example 6 and open
Chap1106.pdf; a print dialog will
open immediately.
files and URLs
If you want to jump to another document or URL, you have to create a PdfAction
using one of the following constructors:
PdfAction(String filename, String name);
PdfAction(String filename, int page);
PdfAction(URL url);
PdfAction(String url);
The first two constructors allow you to define an action to jump to a certain
page or location in another PDF file. The last two allow you to jump to a certain URL.
We are going to use these actions in some of the examples below.
|
Destinations
Uptill now the destinations we used allways were related to a chunk,
but it's also possible to create your own destinations.
This is a list of the possible types:
- Destination.XYZ
- Destination.FIT
- Destination.FITH
- Destination.FITV
- Destination.FITR
- Destination.FITB
- Destination.FITBH
- Destination.FITBV
You can't use any constructor to create any type of destination. This is a list of
constructors:
- public PdfDestination(int type) can be used for types
FIT and FITB. FIT points to the current page designated by page, with its contents
magnified just enough to fit the entire page within the window both horizontally and
vertically. FITB does the same, but the contents are magnified just enough to fit its
bounding box.
- public PdfDestination(int type, float parameter) can be
used for types FITH, FITV, FITBH and FITBV.If type
equals FITBV, the height of the bounding box of a page will fit the window of the Reader.
The parameter will specify the x coordinate of the left edge of the window. If the type
equals FITV the height of the entire page will fit the window and the parameter will specify
the x coordinate of the left edge. If type equals FITBH, the width of the bounding
box of a page will fit the window of the Reader. The parameter will specify the y coordinate
of the top edge of the window. If the type equals FITH the width of the entire page will
fit the window and the parameter will specify the y coordinate of the top edge.
- public PdfDestination(int type, float left, float top, float zoom) can be used for type XYZ.
with the coordinates (left, top) as the top-left corner of the destination window and the
contents of the page magnified by the factor zoom. A negative value for any of the
parameters left or top, or a zoom value of 0 specifies that the current value of that
parameter is to be retained unchanged.
- public PdfDestination(int type, float left, float bottom, float right, float top) can be used for type FITR
the destination will be a rectangle specified by the coordinates left, bottom, right, and top. If the required
horizontal and vertical magnification factors are different, use the smaller of
the two, centering the rectangle within the window in the other dimension.
Examples:
PdfDestination d1 = new PdfDestination(PdfDestination.XYZ, 300, 800, 0);
PdfDestination d2 = new PdfDestination(PdfDestination.FITH, 500);
PdfDestination d3 = new PdfDestination(PdfDestination.FITR, 200, 300, 400, 500);
PdfDestination d4 = new PdfDestination(PdfDestination.FITBV, 100);
PdfDestination d5 = new PdfDestination(PdfDestination.FIT);
When a destination is created, it is not linked to a certain page in the document.
Only when add the destination the outline tree, it will point to the 'current' page.
We will use these destinations in the next section:
|
Outlines
In Chapter 4, we were able to build an outline tree
by using the objects Chapter and Section.
Now we are going to build an outline tree manually. First of all we have to ask the contentbyte
of the writer for the root of the outline tree:
PdfContentByte cb = writer.getDirectContent();
PdfOutline root = cb.getRootOutline();
To this root we can add several branches and subbranches:
PdfOutline out1 = new PdfOutline(root, d1, "root");
PdfOutline out2 = new PdfOutline(out1, d2, "sub 1");
PdfOutline out3 = new PdfOutline(out1, d3, "sub 2");
PdfOutline out4 = new PdfOutline(out2, d4, "sub 2.1");
PdfOutline out5 = new PdfOutline(out2, d5, "sub 2.2");
In example 7, we first place some crosses.
These crosses will mark different destinations. Click on the different
outline entries in document Chap1107.pdf to
test the destination functionality.
In example 8, we build the outline tree
automatically again, just as when we used Chapters and Sections.
This time however, we use a PageEventHelper class that adds an
outline every time a new paragraph is started. But more about these
page events in the next chapter. Check out
Chap1108.pdf (and read all about some
brave belgians).
It is also possible to add actions to an outline tree.
This is demonstrated in example 9
(Chap1109.pdf).
|
Page labels on thumbnails
Besides outlines, you also have 'thumbnails' that show you a small version of every page.
Under each thumbnail, you have a label. If you want to change the style of these page labels,
you have to create a PdfPageLabels-object and add a new style,
content or pagenumber value, starting from a certain 'real' pagenumber.
These are the different styles you can use:
- PdfPageLabels.DECIMAL_ARABIC_NUMERALS
- PdfPageLabels.UPPERCASE_ROMAN_NUMERALS
- PdfPageLabels.LOWERCASE_ROMAN_NUMERALS
- PdfPageLabels.UPPERCASE_LETTERS
- PdfPageLabels.LOWERCASE_LETTERS
- PdfPageLabels.EMPTY
Please take a look at example 10
and the resulting PDF file.
|
[Top] |
[Previous] |
[TOC] |
[Next] |
[PDF] |
Page Updated: $Date: 2004/02/07 10:48:07 $
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
|
|